# Configuration (/docs/orbit-studios-resources/orbit-dynamichud-v2/configuration)



# Configuration [#configuration]

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

<Callout type="warn" title="Use supported config files">
  Configure the resource through the files listed here. Do not modify compiled NUI files or protected runtime files.
</Callout>

## File map [#file-map]

<Files>
  <Folder name="orbit-dynamichud-v2">
    <Folder name="shared">
      <File name="config.lua" />

      <File name="settingsConfig.lua" />

      <File name="weapons.lua" />

      <File name="cars.lua" />
    </Folder>

    <Folder name="server">
      <File name="config.lua" />

      <File name="handlers.lua" />
    </Folder>

    <Folder name="locales">
      <File name="en.json" />

      <File name="de.json" />

      <File name="es.json" />

      <File name="fr.json" />

      <File name="sv.json" />

      <File name="tr.json" />
    </Folder>
  </Folder>
</Files>

| File                        | Purpose                                                                                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shared/config.lua`         | Runtime behavior, onboarding mode, commands, keybinds, Dynamic Bar policy, modules, account/status availability, phone offsets, and performance intervals. |
| `shared/settingsConfig.lua` | Authoritative/default player settings and component layouts.                                                                                               |
| `shared/weapons.lua`        | Weapon labels, item names, ammo sources, and ammo metadata.                                                                                                |
| `shared/cars.lua`           | Reserved future vehicle-intro config; currently unused.                                                                                                    |
| `server/config.lua`         | Restricted commands, Settings Share limits, moderation ACE, throttling, and thumbnail service.                                                             |
| `server/handlers.lua`       | Framework, inventory, medical, and custom integration glue.                                                                                                |
| `locales/*.json`            | UI text and localized command names/descriptions.                                                                                                          |

## Core settings [#core-settings]

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
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
```

| Setting                                    | Values/default            | Description                                                                                                                                      |
| ------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Config.Debug`                             | `false`                   | Enables development diagnostics. Keep false in production.                                                                                       |
| `Config.MoneyText`                         | `"$"`                     | Text displayed next to cash/account values.                                                                                                      |
| `Config.HeadingType`                       | `"camera"` or `"heading"` | Use camera rotation or entity heading for the compass.                                                                                           |
| `Config.WaypointNavigation.enabled`        | `true`                    | Enables GPS distance, direction, and waypoint-color updates. When false, the waypoint thread is never created.                                   |
| `Config.WaypointNavigation.idleInterval`   | `500`                     | Milliseconds between lightweight availability checks when no driver waypoint is active. Runtime minimum: `100`.                                  |
| `Config.WaypointNavigation.updateInterval` | `60`                      | Milliseconds between route updates for a driver with an active waypoint. Runtime minimum: `30`.                                                  |
| `Config.Onboarding.enabled`                | `true`                    | Master switch for onboarding, its event, and its command.                                                                                        |
| `Config.Onboarding.trigger`                | `"auto"` or `"manual"`    | Automatically show an incomplete first run after a logged-in, uninterrupted five-second UI availability check, or wait for an integration event. |
| `Config.DriverPermissionAsPassenger`       | `false`                   | Gives passengers driver-style vehicle access where supported.                                                                                    |
| `Config.SettingsLocked`                    | `false`                   | Forces saved settings to follow `Config.DefaultSettings` and blocks user changes/imports.                                                        |
| `Config.CinematicHeight`                   | `0.1`                     | Cinematic bar height sent to the NUI.                                                                                                            |

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](/docs/orbit-studios-resources/orbit-dynamichud-v2/onboarding) for automatic/manual behavior, trigger examples, command semantics, and integration scenarios.

## Commands [#commands]

Client commands are independently switchable:

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
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](/docs/orbit-studios-resources/orbit-dynamichud-v2/commands) for every command and parameter.

## Phone offset [#phone-offset]

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
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](/docs/orbit-studios-resources/orbit-dynamichud-v2/events#phone-open-and-close-events).

## Dynamic Bar and widgets [#dynamic-bar-and-widgets]

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
Config.DynamicBar = {
    mode = 'free',
    hourFormat = '24',
    postCodes = false
}
```

| `mode`       | Result                                                        |
| ------------ | ------------------------------------------------------------- |
| `disabled`   | Hide both Dynamic Bar and widgets and stop their update work. |
| `free`       | Let users choose `dynamicbar` or `widgets`.                   |
| `dynamicbar` | Force the Dynamic Bar.                                        |
| `widgets`    | Force widgets.                                                |

`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`:

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/settingsConfig.lua"
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 [#performance-and-map]

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
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 [#keybinds]

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
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 [#fuel-integration]

The speedometer expects a number from `Config.GetVehicleFuelLevel`:

```lua title="Native fuel example"
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:

```lua title="Custom fuel example"
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 [#statuses-and-accounts]

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
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 [#control-panel-modules]

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

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/config.lua"
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](/docs/orbit-studios-resources/orbit-dynamichud-v2/settings-sharing).

### Music behavior [#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 [#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 [#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.

| Setting                  | Supported values/default                                                               |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `preset`                 | `performance`, `balanced`, `ultra`; default `balanced`                                 |
| `unit`                   | `kmh`, `mph`; default `kmh`                                                            |
| `shape`                  | `square`, `circle`, `hexagon`; default `square`                                        |
| `hud`                    | `waveseries`, `serenity`, `proseries`, `proecho`, `bubblegum`, `simple`                |
| `speedometer`            | `Apex`, `ARCD_LINE`, `ARCD_ARC`, `Eclipse`, `Heat`, `PRO`, `ZoxOne`, `Glide`, `Motion` |
| `control_panel_theme`    | `default`, `monochrome-dark`, `monochrome-light`                                       |
| `center_control_panel`   | `false`; place the control panel at screen center when enabled                         |
| `dynamicbar_mode`        | `dynamicbar` or `widgets` when server policy is `free`                                 |
| `player_data.variant`    | `cinder_edge`, `cinder_flow`, `specter`, `gridline`                                    |
| `player_data.color_mode` | `colored`, `monotone`                                                                  |

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 [#layout-helper]

Every configured layout is generated with:

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/settingsConfig.lua"
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 [#framework-and-state-sources]

DynamicHUD 2.0 consumes normalized player data from `orbit-lib`, common framework events, and replicated state bags. Use [Events and State Bags](/docs/orbit-studios-resources/orbit-dynamichud-v2/events) for exact integration names.

Death-state values are:

| Value | Meaning    |
| ----: | ---------- |
|   `1` | Alive      |
|   `2` | Last stand |
|   `3` | Dead       |

For custom medical resources, set server-owned state:

```lua title="resources/[custom]/server/main.lua"
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 [#weapons-and-ammo]

```lua title="resources/[orbit]/orbit-dynamichud-v2/shared/weapons.lua"
Config.AmmoInfo = {
    getAmmoFrom = 'inventory' -- inventory or reserve
}

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

| Field      | Description                                                                     |
| ---------- | ------------------------------------------------------------------------------- |
| `name`     | Inventory item name.                                                            |
| `label`    | Displayed weapon name. The unarmed label is not localized automatically.        |
| `ammotype` | Inventory ammo item or native ammo type. Use `nil` when no ammo should display. |

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

## Cars config [#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 [#settings-share-server-config]

Database limits, upload cooldowns, moderation permissions, and FiveManage thumbnail uploads live in `server/config.lua`. See [Settings Sharing](/docs/orbit-studios-resources/orbit-dynamichud-v2/settings-sharing) for the full matrix and security model.