Configuration

Orbit Dynamic HUD 2.0 keeps public server-owner configuration outside escrow. Restart the resource after changing Lua configuration.

File map

Core settings

Config.Debug = false
Config.MoneyText = '$'
Config.HeadingType = 'camera'
Config.WaypointNavigation = {
    enabled = true,
    idleInterval = 500,
    updateInterval = 60
}
Config.Onboarding = {
    enabled = true,
    trigger = 'auto' -- 'auto' or 'manual'
}
Config.DriverPermissionAsPassenger = false
Config.SettingsLocked = false
Config.CinematicHeight = 0.1

When Config.SettingsLocked is true, server defaults are the source of truth. Users cannot bypass them with onboarding, Settings Share, saved browser data, or control-panel edits.

See Onboarding for automatic/manual behavior, trigger examples, command semantics, and integration scenarios.

Commands

Client commands are independently switchable:

Config.Commands = {
    controlpanel = { enabled = true },
    customize = { enabled = true },
    music = { enabled = true },
    carcontrol = { enabled = true },
    settings = { enabled = true },
    settingsshare = { enabled = true },
    editmode = { enabled = true },
    restarthud = { enabled = true },
    engine = { enabled = true },
    onboarding = { enabled = true }
}

Cash, bank, and stress commands are configured in server/config.lua with an enabled switch and optional ox_lib restriction group. See Commands for every command and parameter.

Phone offset

Config.PhoneOffset = {
    enabled = false,
    side = 'right',
    offset = 18.0,
    openEvent = 'orbit-dynamichud:phoneOpened',
    closeEvent = 'orbit-dynamichud:phoneClosed'
}

side is left or right; offset is clamped from 0 to 50 vh. Trigger the configured events when the phone opens/closes. The open event may receive a side override. Full examples are in Events and State Bags.

Dynamic Bar and widgets

Config.DynamicBar = {
    mode = 'free',
    hourFormat = '24',
    postCodes = false
}

hourFormat supports "24" and "12". postCodes enables postcode loading/display. Invalid mode values print a warning and fall back to free.

Default widget configuration lives in Config.DefaultSettings.dynamicbar_widgets:

dynamicbar_mode = 'dynamicbar',
dynamicbar_widgets = {
    weather = {
        enabled = true,
        size = 'default' -- default or mini
    },
    statuses = {
        {
            enabled = true,
            priorities = {
                'song', 'laststand', 'dead', 'oxygen',
                'navigation', 'drive', 'walking'
            }
        },
        {
            enabled = false,
            priorities = {
                'oxygen', 'song', 'laststand', 'dead',
                'navigation', 'drive', 'walking'
            }
        }
    }
}

Each status widget must contain every supported priority exactly once. The first item has the highest priority.

Performance and map

Config.PerformanceSettings = {
    performance = 300,
    balanced = 100,
    ultra = 30
}

Config.CustomMap = {
    usingCustomMap = true,
    radarZoom = 1100,
    waitTime = 300
}

Performance values are client refresh intervals in milliseconds. Lower values are more responsive and use more client time. Config.CustomMap repeatedly reapplies radar zoom for map resources that overwrite it; disable it when unnecessary.

Config.WaypointNavigation controls a separate GPS thread. When enabled, every client performs one lightweight waypoint/vehicle availability check at idleInterval; distance, direction, route, and color natives run only while that client is the driver and has an active waypoint. This may add a small client cost for drivers. Set enabled = false to avoid creating the thread and all of its waypoint work.

Keybinds

Config.Keybinds = {
    indicator_keybinds = {
        right_indicator_keybind = 'RIGHT',
        left_indicator_keybind = 'LEFT',
        hazard_indicator_keybind = 'UP'
    },
    ui_keybinds = {
        focus_ui = { enabled = true, key = 'F4' },
        customize = { enabled = false, key = 'F5' },
        music = { enabled = false, key = 'F6' },
        carcontrol = { enabled = false, key = 'F7' },
        settings = { enabled = false, key = 'F9' }
    }
}

These are ox_lib keybind defaults. Each UI entry has an independent enabled switch and configurable key. Players can remap registered keybinds through FiveM settings. Disabled or unavailable control-panel tabs do not register their tab-specific bind. The original string form, such as focus_ui = 'F4', remains supported for existing configurations.

Fuel integration

The speedometer expects a number from Config.GetVehicleFuelLevel:

Config.GetVehicleFuelLevel = function(vehicle)
    if not vehicle then return 0.0 end
    return GetVehicleFuelLevel(vehicle) or 0.0
end

Replace the function when a fuel resource owns the value:

Config.GetVehicleFuelLevel = function(vehicle)
    return exports['my-fuel']:GetFuel(vehicle) or 0.0
end

Keep this getter fast because it runs in the vehicle update path.

Statuses and accounts

Config.EnabledValues = {
    health = true,
    armor = true,
    hunger = true,
    thirst = true,
    stamina = true,
    stress = true
}

Config.Accounts = {
    cash = true,
    bank = true,
    dirty = false
}

Set supported entries to false to remove them. Do not add arbitrary status/account keys; the frontend settings schema is strict.

Control-panel modules

Config.ControlPanel controls both navigation visibility and whether corresponding client/server work is enabled.

Config.ControlPanel = {
    enableControlPanel = true,

    customize = {
        enabled = true,
        color_picker = true,
        status_selector = true,
        shape_selector = true,
        player_info_selector = {
            enabled = true,
            current_status = true,
            show_player_data_bg = true
        },
        speedometer_selector = true
    },

    music = {
        enabled = true,
        play = true,
        playlists = true,
        music_settings = true,
        onlyLocalMusic = false,
        dynamicSounds = true,
        refreshSoundPosition = 750,
        maxDistancePhone = 30.0,
        maxDistanceCar = 60.0
    },

    carControl = {
        enabled = true,
        mode = "owner",
        neon = true
    },

    settings = {
        enabled = true,
        display = {
            enabled = true,
            speed_unit = true,
            active_weapon = true,
            cinematic_mode = true,
            show_hud_bg = true,
            hud_16_9 = true,
            vehicle_preview = true
        },
        audio = {
            enabled = true,
            music_enabled = true,
            sounds_enabled = true
        },
        performance_settings = true,
        edit_mode = true,
        panel_theme = {
            enabled = true,
            center_control_panel = true
        }
    }
}

The omitted settingsShare group is documented on Settings Sharing.

Music behavior

• enabled = false disables all music features, including server-side dynamic audio.
• onlyLocalMusic = true keeps headphones playback in the frontend and disables phone/car modes, playlist sharing, and server 3D-audio work.
• dynamicSounds = false leaves local playback available but prevents server-distributed phone/car sound.
• refreshSoundPosition has a minimum runtime value of 50 ms.
• maxDistancePhone and maxDistanceCar are world-unit distance limits.
• Music mode is session-only and initializes as headphones mode; it is not stored in saved/default settings.
• Saved playlists live in the player's NUI storage rather than the Settings Share database. The current frontend limit is 20 saved playlists with 50 tracks per playlist.
• Playlist share codes are server-memory only, limited to one active code per player, and expire when replaced, removed, the owner disconnects, or the resource/server restarts.
• A YouTube playlist URL can add its resolved tracks in one operation; individual supported HTTPS music links can be added directly.

Car control behavior

The tab is available only while in a vehicle. Runtime vehicle types are normalized to car, motorcycle, bike, boat, plane, or helicopter. neon = false disables neon mode independently.

carControl.mode supports two values:

• "owner" allows only the vehicle's current FiveM network owner to use car controls. This is network ownership, which FiveM may migrate between clients; it is not framework or database vehicle ownership.
• "realistic" gives the driver access to every control. Any occupant may switch seats, while passengers in the first three passenger seats may operate only the door and window beside their current seat.

Unknown mode values fail closed to "owner". The client provides immediate feedback, and the server independently verifies the configured mode, requesting player, occupied vehicle, seat, action, value, and network owner before relaying a control. Vehicle capability, installed-neon, available door/window, seat, and driver-permission checks still apply after the UI is visible.

Default player settings

shared/settingsConfig.lua mirrors the complete frontend settings schema. Existing saved settings continue to apply unless settings are locked or the user resets them.

The settings object also contains:

• speedometer_color index per speedometer
• icon index, RGB color, opacity, icon RGB color, and icon opacity per status
• active_weapon, hud_16_9, show_vehicle_preview, center_control_panel, and player-data toggles
• Dynamic Bar widget configuration/priorities
• status, component, speedometer, and map layouts
• UI/music enable and volume values
• HUD/player-data background visibility

Layout helper

Every configured layout is generated with:

local function layout(options)
    if type(options) == 'boolean' then
        options = { visible = options }
    end

    options = options or {}

    return {
        x = options.x or 0,
        y = options.y or 0,
        scale = options.scale or 1,
        rotation = options.rotation or 0,
        locked = options.locked == true,
        visible = options.visible ~= false,
        canChangeVisibility = options.canChangeVisibility ~= false
    }
end

canChangeVisibility is a server default policy and is not stored as a player preference. Set visible = true, canChangeVisibility = false to force an element visible. The map ignores rotation.

Do not remove layout keys. Settings Share and saved-setting validation require the complete schema.

Framework and state sources

DynamicHUD consumes normalized player data from orbit-lib, common framework events, and replicated state bags. Use Events and State Bags for exact integration names.

Death-state values are:

For custom medical resources, set server-owned state:

Player(source).state:set('hud:deathState', 3, true)

For inventory visibility, prefer a replicated invOpen player state. Alternatively call the server toggleHud export from open/close handlers.

Weapons and ammo

Config.AmmoInfo = {
    getAmmoFrom = 'inventory' -- inventory or reserve
}

Config.Weapons[`weapon_customrifle`] = {
    name = 'weapon_customrifle',
    label = 'Custom Rifle',
    ammotype = 'ammo-rifle'
}

Use getAmmoFrom = 'inventory' for item-based ammo and reserve for GTA native reserve ammo.

Cars config

shared/cars.lua is marked as a possible future vehicle-intro configuration and is not currently consumed. Do not populate it expecting HUD behavior; vehicle type and car-control state come from runtime natives and the car-control implementation.

Settings Share server config

Database limits, upload cooldowns, moderation permissions, and FiveManage thumbnail uploads live in server/config.lua. See Settings Sharing for the full matrix and security model.