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



# Configuration [#configuration]

`orbit-dynamichud` exposes several non-escrowed config files. Start with `shared/config.lua`, then review default player settings, server commands, framework handlers, and weapon metadata.

<Callout type="warn" title="Edit the public config files only">
  The HUD runtime is escrowed. Configure the resource through `shared/config.lua`, `shared/settingsConfig.lua`, `shared/weapons.lua`, `server/config.lua`, and `server/handlers.lua`.
</Callout>

## File Map [#file-map]

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

          <File name="settingsConfig.lua" />

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

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

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

<TypeTable
  type="{
  'shared/config.lua': {
    type: 'runtime config',
    description: 'Global HUD behavior, onboarding, performance presets, map behavior, keybinds, enabled status values, accounts, control panel modules, and cinematic mode.',
  },
  'shared/settingsConfig.lua': {
    type: 'default player settings',
    description: 'The first-load preset applied to players before they customize their HUD.',
  },
  'shared/weapons.lua': {
    type: 'weapon metadata',
    description: 'Weapon hash map, display labels, inventory item names, and ammo item/native ammo names.',
  },
  'server/config.lua': {
    type: 'server command config',
    description: 'Enables or disables admin/helper commands and controls ox_lib command restrictions.',
  },
  'server/handlers.lua': {
    type: 'integration handlers',
    description: 'Inventory open/close handlers, death-state handlers, and custom framework/resource event bridges.',
  },
}"
/>

## Shared Config [#shared-config]

`resources/[orbit]/orbit-dynamichud/shared/config.lua` controls the global HUD behavior.

<TypeTable
  type="{
  'Config.Debug': {
    type: 'boolean',
    default: 'false',
    description: 'Use true while developing or debugging. Keep false on production servers unless you are actively diagnosing an issue.',
  },
  'Config.ServerInfo.serverBgColor': {
    type: 'hex color',
    default: '&#x22;#FF00F2&#x22;',
    description: 'Control panel server background color. Use a 6-character hex code.',
  },
  'Config.HeadingType': {
    type: '&#x22;heading&#x22; | &#x22;camera&#x22;',
    default: '&#x22;camera&#x22;',
    description: 'Compass heading source. Use &#x22;camera&#x22; if you want the compass to follow camera angle instead of ped or vehicle heading.',
  },
  'Config.Onboarding': {
    type: 'boolean',
    default: 'true',
    description: 'Shows the onboarding flow when the player starts. The /onboarding command can still open it later.',
  },
  'Config.DriverPermissionAsPassenger': {
    type: 'boolean',
    default: 'false',
    description: 'Lets passengers see and use driver-style vehicle HUD features. This is marked temporary in the source config.',
  },
  'Config.DynamicBar': {
    type: '{ enable: boolean, hourFormat: &#x22;12&#x22; | &#x22;24&#x22;, postCodes: boolean }',
    description: 'Controls the bar below the minimap, including time format and post code display.',
  },
  'Config.PerformanceSettings': {
    type: '{ performance: number, balanced: number, ultra: number }',
    description: 'HUD refresh intervals in milliseconds. Lower values update more often but cost more client performance.',
  },
  'Config.CustomMap': {
    type: '{ usingCustomMap: boolean, radarZoom: number, waitTime: number }',
    description: 'Compatibility settings for custom postal/map themes that fight radar visibility or zoom.',
  },
  'Config.Keybinds': {
    type: 'table',
    description: 'Vehicle indicator keybinds and UI focus keybinds.',
  },
  'Config.GetVehicleFuelLevel': {
    type: 'function(vehicle): number',
    description: 'Fuel getter used by the speedometer. Replace this when your fuel resource does not use the native fuel value.',
  },
  'Config.EnabledValues': {
    type: 'table<boolean>',
    description: 'Toggles built-in status values: health, armor, hunger, thirst, stamina, and stress.',
  },
  'Config.Accounts': {
    type: 'table<boolean>',
    description: 'Toggles money accounts shown by the HUD: cash, bank, and dirty money.',
  },
  'Config.ControlPanel': {
    type: 'table',
    description: 'Enables or disables the control panel, customization tabs, music, car control, settings, and individual settings modules.',
  },
  'Config.SettingsLocked': {
    type: 'boolean',
    default: 'false',
    description: 'Locks settings when true.',
  },
  'Config.CinematicHeight': {
    type: 'number',
    default: '0.2',
    description: 'Height of the cinematic black bars.',
  },
}"
/>

```lua title="resources/[orbit]/orbit-dynamichud/shared/config.lua"
Config = Config or {}

Config.Debug = false

Config.ServerInfo = {
    serverBgColor = "#FF00F2"
}

Config.HeadingType = "camera"
Config.Onboarding = true
Config.DriverPermissionAsPassenger = false

Config.DynamicBar = {
    enable = true,
    hourFormat = "24",
    postCodes = false
}

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

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

Config.Keybinds = {
    indicator_keybinds = {
        right_indicator_keybind = "RIGHT",
        left_indicator_keybind = "LEFT",
        hazard_indicator_keybind = "UP"
    },
    ui_keybinds = {
        focus_ui = "F4"
    }
}

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

    return GetVehicleFuelLevel(veh) or 0.0
end

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

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

Config.SettingsLocked = false
Config.CinematicHeight = 0.2
```

Do not delete keys from `Config.EnabledValues`. Use `true` to show a supported value and `false` to hide it. The HUD does not support custom status keys in this table yet.

## Status Sources [#status-sources]

DynamicHUD listens for common framework events and state bags, but the exact source depends on your framework and supporting resources.

<Tabs groupId="framework" items="['ESX', 'QB', 'QBX', 'Standalone']">
  <Tab value="ESX">
    ESX money and status updates come from ESX events such as `esx:setAccountMoney`, `esx_status:onTick`, and spawn/death events. Keep the ESX death handlers in `server/handlers.lua` unless your ambulance resource uses different events.

    ```lua title="resources/[orbit]/orbit-dynamichud/server/handlers.lua"
    AddEventHandler("esx:onPlayerDeath", function(data)
        local src = source
        Player(src)?.state:set("hud:deathState", 3, true)
    end)

    AddEventHandler("playerSpawned", function(spawn)
        local src = source
        Player(src)?.state:set("hud:deathState", 1, true)
    end)
    ```
  </Tab>

  <Tab value="QB">
    QB status and money updates are read from common QBCore HUD events like `hud:client:UpdateNeeds`, `hud:client:UpdateStress`, and `hud:client:OnMoneyChange`. The default death handlers support `qb-ambulancejob` style hospital events.

    ```lua title="resources/[orbit]/orbit-dynamichud/server/handlers.lua"
    AddEventHandler("hospital:server:SetLaststandStatus", function(state)
        local src = source
        local state = state and 2 or 1
        Player(src)?.state:set("hud:deathState", state, true)
    end)

    AddEventHandler("hospital:server:SetDeathStatus", function(state)
        local src = source
        local state = state and 3 or 1
        Player(src)?.state:set("hud:deathState", state, true)
    end)
    ```
  </Tab>

  <Tab value="QBX">
    QBX/Qbox can use the same common HUD events for needs and stress. DynamicHUD also listens to the `qbx_medical:deathState` player state and mirrors it into `hud:deathState`.

    ```lua title="resources/[custom]/server/death-state.lua"
    Player(source)?.state:set("hud:deathState", 3, true)
    ```

    Use the numeric death-state values from the handlers section if your medical resource does not already publish a compatible state.
  </Tab>

  <Tab value="Standalone">
    Standalone servers must feed the HUD with the same events or state bags that the HUD expects. For death state, set `hud:deathState` on the player state. For stress, use `LocalPlayer.state.stress` through `orbit-dynamichud-stress` or your own resource.

    ```lua title="resources/[custom]/server/death-state.lua"
    Player(source)?.state:set("hud:deathState", 1, true)
    ```
  </Tab>
</Tabs>

## Default Player Settings [#default-player-settings]

`resources/[orbit]/orbit-dynamichud/shared/settingsConfig.lua` defines the default settings used before a player customizes the HUD.

```lua title="resources/[orbit]/orbit-dynamichud/shared/settingsConfig.lua"
local function layout(visible)
    return {
        x = 0,
        y = 0,
        scale = 1,
        locked = false,
        visible = visible ~= false
    }
end

Config.DefaultSettings = {
    resolution = {
        width = 1920,
        height = 1080
    },

    preset = "balanced",
    unit = "kmh",
    shape = "square",
    hud = "waveseries",
    speedometer = "Apex",

    icons = {
        health = 1,
        armor = 1,
        hunger = 1,
        thirst = 1,
        stamina = 1,
        stress = 1
    },

    component_layouts = {
        notification = layout(),
        dynamicbar = layout(),
        cash = layout(),
        bank = layout(),
        dirty_money = layout(),
        voice = layout(),
        weapon = layout(),
        job = layout(),
        gang = layout(),
        radio = layout(),
        compass = layout()
    },

    sounds_enabled = true,
    ui_volume = 50,
    music_enabled = true,
    show_hud_bg = true,
    show_player_data_bg = true,
    default = true
}
```

Existing players may keep saved preferences, so changing defaults does not always reset everyone immediately. Use this file to decide what a new player sees first.

<TypeTable
  type="{
  preset: {
    type: '&#x22;performance&#x22; | &#x22;balanced&#x22; | &#x22;ultra&#x22;',
    description: 'Initial performance preset. The actual refresh times come from Config.PerformanceSettings.',
  },
  unit: {
    type: '&#x22;kmh&#x22; | &#x22;mph&#x22;',
    description: 'Default speed unit.',
  },
  shape: {
    type: '&#x22;square&#x22; | &#x22;circle&#x22; | &#x22;hexagon&#x22;',
    description: 'Default status icon shape.',
  },
  hud: {
    type: '&#x22;waveseries&#x22; | &#x22;proseries&#x22; | &#x22;proecho&#x22; | &#x22;bubblegum&#x22;',
    description: 'Default HUD style.',
  },
  speedometer: {
    type: '&#x22;Apex&#x22; | &#x22;ARCD_LINE&#x22; | &#x22;ARCD_ARC&#x22; | &#x22;PRO&#x22; | &#x22;ZoxOne&#x22; | &#x22;Glide&#x22; | &#x22;Motion&#x22;',
    description: 'Default speedometer style.',
  },
  component_layouts: {
    type: 'table',
    description: 'Default x, y, scale, lock, and visibility data for movable HUD components.',
  },
}"
/>

## Server Commands [#server-commands]

`resources/[orbit]/orbit-dynamichud/server/config.lua` enables or disables helper commands and controls who can run them.

```lua title="resources/[orbit]/orbit-dynamichud/server/config.lua"
Config = Config or {}

Config.Commands = {
    cash = {
        enabled = true,
        allow = "group.admin"
    },
    bank = {
        enabled = true,
        allow = "group.admin"
    },
    setstress = {
        enabled = true,
        allow = "group.admin"
    }
}
```

`allow` is passed to `ox_lib` command restrictions. Use an empty string only when everyone should be able to run the command.

| Command      | Parameters                                          | What it does                                                                               |
| ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `/cash`      | Optional player ID: `/cash 12`                      | Shows your cash, or the target player's cash if an ID is provided.                         |
| `/bank`      | Optional player ID: `/bank 12`                      | Shows your bank money, or the target player's bank money if an ID is provided.             |
| `/setstress` | `/setstress <amount>` or `/setstress <id> <amount>` | Sets your stress, or the target player's stress. Values are clamped between `0` and `100`. |

## Handlers [#handlers]

Use `resources/[orbit]/orbit-dynamichud/server/handlers.lua` for integration glue. This is where you connect inventory visibility, death state, and any custom framework events.

### Inventory Open And Close [#inventory-open-and-close]

The default file includes `ox_inventory` handlers that hide the HUD while the inventory is open.

```lua title="resources/[orbit]/orbit-dynamichud/server/handlers.lua"
AddEventHandler("ox_inventory:openedInventory", function(source)
    TriggerClientEvent("orbit-dynamichud:client:toggleHud", source, false)
end)

AddEventHandler("ox_inventory:closedInventory", function(source)
    TriggerClientEvent("orbit-dynamichud:client:toggleHud", source, true)
end)
```

If you use a different inventory, replace the event names with your inventory's open and close events. Keep the `false` call on open and the `true` call on close.

### Death State [#death-state]

DynamicHUD uses numeric death states:

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

The default QBCore hospital handlers translate booleans into these values.

```lua title="resources/[orbit]/orbit-dynamichud/server/handlers.lua"
AddEventHandler("hospital:server:SetLaststandStatus", function(state)
    local src = source
    local state = state and 2 or 1
    Player(src)?.state:set("hud:deathState", state, true)
end)

AddEventHandler("hospital:server:SetDeathStatus", function(state)
    local src = source
    local state = state and 3 or 1
    Player(src)?.state:set("hud:deathState", state, true)
end)
```

The default ESX handlers set dead on death and alive on spawn.

```lua title="resources/[orbit]/orbit-dynamichud/server/handlers.lua"
AddEventHandler("esx:onPlayerDeath", function(data)
    local src = source
    Player(src)?.state:set("hud:deathState", 3, true)
end)

AddEventHandler("playerSpawned", function(spawn)
    local src = source
    Player(src)?.state:set("hud:deathState", 1, true)
end)
```

For a custom ambulance resource, set the same player state from that resource's server event.

```lua title="resources/[custom]/server/death-state.lua"
AddEventHandler("my_ambulance:server:setDeathState", function(target, state)
    Player(target)?.state:set("hud:deathState", state, true)
end)
```

Make sure `state` is `1`, `2`, or `3`. If the HUD always shows the wrong death state, this file is the first place to check.

## Weapons [#weapons]

`resources/[orbit]/orbit-dynamichud/shared/weapons.lua` controls the weapon label and ammo data shown by the HUD.

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

Config.Weapons = {
    [`weapon_unarmed`] = {
        name = "weapon_unarmed",
        label = "Fists",
        ammotype = nil
    },

    [`weapon_pistol`] = {
        name = "weapon_pistol",
        label = "Pistol",
        ammotype = "ammo-9"
    },

    [`weapon_assaultrifle`] = {
        name = "weapon_assaultrifle",
        label = "Assault Rifle",
        ammotype = "AMMO_RIFLE"
    }
}
```

<TypeTable
  type="{
  'Config.AmmoInfo.getAmmoFrom': {
    type: '&#x22;inventory&#x22; | &#x22;reserve&#x22;',
    description: 'Use &#x22;inventory&#x22; when ammo is an inventory item, such as ox_inventory ammo. Use &#x22;reserve&#x22; when you want GTA native reserve ammo behavior.',
  },
  'Config.Weapons[hash].name': {
    type: 'string',
    description: 'Inventory item name for the weapon.',
  },
  'Config.Weapons[hash].label': {
    type: 'string',
    description: 'Display label shown in the HUD. Change `weapon_unarmed` from &#x22;Fists&#x22; if you want another unarmed label.',
  },
  'Config.Weapons[hash].ammotype': {
    type: 'string | nil',
    description: 'Ammo item name or native ammo type. Use nil for melee weapons and weapons that should not show ammo.',
  },
}"
/>

Add custom weapons by adding another hash entry with the same shape.

```lua title="resources/[orbit]/orbit-dynamichud/shared/weapons.lua"
Config.Weapons[`weapon_customrifle`] = {
    name = "weapon_customrifle",
    label = "Custom Rifle",
    ammotype = "ammo-rifle"
}
```

If weapon ammo is wrong, check `Config.AmmoInfo.getAmmoFrom` first, then check that the `ammotype` matches your inventory ammo item name or native ammo type.

## Common Mistakes [#common-mistakes]

<Accordions>
  <Accordion title="Stress is enabled but not updating">
    Keep `Config.EnabledValues.stress = true`, install and start `orbit-dynamichud-stress`, then confirm `LocalPlayer.state.stress` is a number.
  </Accordion>

  <Accordion title="Inventory opens over the HUD">
    Add open and close handlers for your inventory in `server/handlers.lua`. The default file only includes `ox_inventory` events.
  </Accordion>

  <Accordion title="Death state stays alive after death">
    Your ambulance resource probably uses different events. Add a server handler that sets `Player(source)?.state:set("hud:deathState", 3, true)` on death and `1` on revive/spawn.
  </Accordion>

  <Accordion title="Weapon label or ammo is wrong">
    Update `shared/weapons.lua`. The weapon hash key, `name`, `label`, and `ammotype` must match the weapon and ammo system your server actually uses.
  </Accordion>
</Accordions>