Configuration
Configure orbit-dynamichud shared config, default HUD settings, server commands, handlers, death state, and weapon data.
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.
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.
File Map
Prop
Type
Shared Config
resources/[orbit]/orbit-dynamichud/shared/config.lua controls the global HUD behavior.
Prop
Type
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.2Do 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
DynamicHUD listens for common framework events and state bags, but the exact source depends on your framework and supporting resources.
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.
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)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.
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)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.
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.
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.
Player(source)?.state:set("hud:deathState", 1, true)Default Player Settings
resources/[orbit]/orbit-dynamichud/shared/settingsConfig.lua defines the default settings used before a player customizes the HUD.
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.
Prop
Type
Server Commands
resources/[orbit]/orbit-dynamichud/server/config.lua enables or disables helper commands and controls who can run them.
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
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
The default file includes ox_inventory handlers that hide the HUD while the inventory is open.
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
DynamicHUD uses numeric death states:
| Value | Meaning |
|---|---|
1 | Alive |
2 | Last stand |
3 | Dead |
The default QBCore hospital handlers translate booleans into these values.
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.
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.
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
resources/[orbit]/orbit-dynamichud/shared/weapons.lua controls the weapon label and ammo data shown by the HUD.
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"
}
}Prop
Type
Add custom weapons by adding another hash entry with the same shape.
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.