esx_hud

esx_hud is the default heads-up display for ESX Legacy. It shows health, armor, hunger, thirst, stamina and oxygen bars, cash and bank balance, the job label, the current weapon with ammo, voice range, and a vehicle speedometer with fuel, damage, indicators and persistent mileage. Use it as-is or as a reference for building your own HUD.

OverviewCopy Anchor Link

The UI ships prebuilt in web/dist. You only need Node.js if you change the React source in web/src and rebuild it.

InstallationCopy Anchor Link

ensure oxmysql
ensure esx_lib
ensure es_extended
ensure esx_status
ensure esx_hud

ConfigurationCopy Anchor Link

All options live in shared/config.lua. The locale comes from the esx:locale convar (default en).

Config.DisableCopy Anchor Link

Set a key to true to turn a feature off.

Config.DefaultCopy Anchor Link

Config.ColorsCopy Anchor Link

Three color groups are passed straight to the UI as CSS values:

• Info: money-text-color (#0aad20), bank-text-color (#666666), job-text-color (#fb9b04)
• Status: healthBar, armorBar, drinkBar, foodBar, staminaBar, oxygenBar
• Speedo: about 25 keys such as segment-color, speedo-progress-color, fuel-icon-color and speedo-background-color

Players can also change colors and units in-game through /hudsettings. Those changes only affect their own client.

Commands and keybindsCopy Anchor Link

The keybinds are registered through xLib.addKeybind, so players can rebind them in the FiveM key settings. They are not registered when VehicleHandlers or Vehicle is disabled. Indicators are ignored in aircraft.

Client exportsCopy Anchor Link

HudToggleCopy Anchor Link

exports.esx_hud:HudToggle(state)

The same function is registered as the net event esx_hud:HudToggle, so the server can call it with TriggerClientEvent('esx_hud:HudToggle', playerId, false).

exports.esx_hud:HudToggle(false)
-- play your cutscene
exports.esx_hud:HudToggle(true)

SeatbeltState and CruiseControlStateCopy Anchor Link

exports.esx_hud:SeatbeltState(state)
exports.esx_hud:CruiseControlState(state)

Both take a boolean and only update the icons. esx_cruisecontrol calls SeatbeltState through its Config.HudResource setting. If you use a different seatbelt script, call these exports from it.

GetCurrentMileageCopy Anchor Link

local mileage, kmh, loaded = exports.esx_hud:GetCurrentMileage()

Returns the mileage of the vehicle the player is driving, whether it is in km (kmh), and whether the value was already loaded from the server. Before it is loaded the first value is nil. Only available when Config.Disable.Vehicle is false.

Server exportsCopy Anchor Link

Mileage is cached on the server per plate (trimmed and uppercased). Only vehicles that exist in owned_vehicles are cached as "owned"; unowned vehicles get a random value that is never saved.

GetMileageCopy Anchor Link

local miles = exports.esx_hud:GetMileage(plate)

Returns the cached mileage in miles (rounded to two decimals) for an owned vehicle, or nil if the plate is not cached yet.

GetMileagesCopy Anchor Link

local map = exports.esx_hud:GetMileages({ 'ABC 123', 'XYZ 999' })
-- map['ABC 123'] = 1520.4

Takes an array of plates and returns a table keyed by plate. Plates without a cached value are left out. esx_garage uses this to show mileage in its menu.

EventsCopy Anchor Link

esx_hud listens to esx_status:onTick for hunger and thirst, esx:setAccountMoney for money, esx:setJob for the job, esx:pauseMenuActive to hide itself in the pause menu, and esx:enteredVehicle / esx:exitedVehicle from es_extended.

Saving mileageCopy Anchor Link

The server writes cached mileage of owned vehicles to owned_vehicles.mileage:

• every 5 minutes
• when esx_hud stops
• 10 seconds before a txAdmin scheduled restart, and on txAdmin shutdown

The value is always stored in miles. With Kmh = true the client shows it multiplied by 1.61.

Integration tipsCopy Anchor Link

• Voice: pma-voice and saltychat are detected automatically. For any other voice resource, edit client/voice.lua and send xLib.nui.send({ type = "VOICE_RANGE", value = index }).
• Fuel: LegacyFuel is read through its export. Other fuel scripts work if they set the native fuel level.
• Status bars: hunger and thirst come from the hunger and thirst statuses of esx_status. Custom statuses are not displayed.
• Other HUDs: if you replace esx_hud, keep esx_cruisecontrol happy by pointing its Config.HudResource at your resource or removing the export call.

Common issuesCopy Anchor Link

• HUD is blank or missing: web/dist is missing (you cloned the source without the build). Download the release, or run npm install and npm run build in web.
• "Setup your custom voice resource" in the console: neither pma-voice nor saltychat is started. Set Config.Disable.Voice = true or add your own voice handler.
• Mileage stays at 0 after restart: the schema migration failed (check the console) or the vehicle is not in owned_vehicles.
• Indicators do nothing: another resource uses the arrow keys, or VehicleHandlers is disabled. Players can rebind under Settings, Key Bindings, FiveM.

RelatedCopy Anchor Link

• esx_status
• esx_cruisecontrol
• esx_garage
• esx_lib
• Client events

Frequently asked questions