Configuration

All server-owned settings live in config.lua. Restart rb_hud after changing the file unless a section below says otherwise.

Core settings

Locales

RB HUD uses the ox_lib locale selected in server.cfg:

setr ox:locale en

English is included at locales/en.json. To add another language, copy that file to locales/<ISO-code>.json, translate the values without changing the keys or %s placeholders, and set ox:locale to the new code. Notifications, command help, profile errors, compass abbreviations, HUD instrument labels, and HUD Studio use the selected locale.

Framework selection

With framework = 'auto', RB HUD chooses the first started resource in this order:

1. Qbox (qbx_core)
2. QB-Core (qb-core)
3. ESX (es_extended)
4. Ox Core (ox_core)

If more than one framework resource is running, set the value explicitly.

return {
    framework = 'qbox',
    -- ...
}

The resource-name aliases qbx_core, qb-core, es_extended, and ox_core are accepted, but the shorter names shown in the table are preferred. ESX also requires esx_status to start before RB HUD.

Standalone mode

framework = 'standalone',

Standalone mode does not load a framework integration. Hunger, thirst, stress, their status effects, stress events, /cash, and /bank are disabled. The corresponding HUD indicators stay hidden, including during HUD Studio preview. All framework-independent HUD features remain available. Select standalone explicitly; 'auto' still reports an error when no supported framework is running so configuration mistakes are not silently hidden.

Minimap zoom

mapZoom is passed to GTA's precise radar zoom while the minimap is visible. The default is tuned for RB HUD's stock minimap layout.

mapZoom = 94.5,

Players can move the minimap through the HUD editor. Their X/Y offsets are saved locally with the rest of their HUD settings.

HUD editor command

enableEditorCommand = true,

Set this to false when another resource handles editor access. RB HUD will then skip registering /edithud; the editMode export remains available so the other resource can open and close HUD Studio.

Speed and distance units

speedUnit = 'mph',

• 'mph' displays road speed as MPH and waypoint distance in mi.
• 'kmh' displays road speed as KM/H and waypoint distance in km.

The speedMin and speedMax values under stressSpeeds use the selected road speed unit. Aircraft airspeed remains in knots because its instrument is labelled KIAS.

Fuel calculation

useTankSizeBasedFuel = false,

• false clamps the native GetVehicleFuelLevel value directly to 0–100.
• true divides the native fuel value by the vehicle's fPetrolTankVolume handling value and converts it to a percentage.

Leave this disabled when your fuel resource already writes a percentage. Turn it on when fuel is stored in tank-volume units.

Optional server logo

The logo is hidden by default:

logo = {
    image = false,
},

Supported formats are PNG, WebP, JPG, and JPEG. Remote URLs, parent-directory traversal, spaces, and unsupported extensions are rejected.

Source build

1. Place the image in web/static/images/, for example web/static/images/server-logo.webp.

2. Configure the build-relative path:

   logo = {
       image = 'images/server-logo.webp',
   },

3. Rebuild the NUI:

   cd web
   bun install
   bun run build

Prebuilt resource

If you are not rebuilding the NUI, place the image directly in web/dist/images/ and use the same images/server-logo.webp configuration path. Restart rb_hud after adding it.

The image renders at a maximum width of 160 pixels in the top-left and does not interfere with minimap positioning or the HUD editor.

Stress screen effects

stressEffects maps stress ranges to the duration of each blur pulse.

stressEffects = {
    { min = 50, max = 60, intensity = 1500 },
    { min = 60, max = 70, intensity = 2000 },
    { min = 70, max = 80, intensity = 2500 },
    { min = 80, max = 90, intensity = 2700 },
    { min = 90, max = 100, intensity = 3000 },
},

Vehicle stress

useVehicleStress = true,
stressSpeeds = {
    {
        speedMin = 155,
        speedMax = 200,
        chance = 0.05,
        timeout = 45000,
        stressGain = { min = 1, max = 2 },
    },
},

Set useVehicleStress = false to disable all speed-based stress.

Weapon stress

Weapon entries use FiveM hash literals:

stressWeapons = {
    `weapon_petrolcan`,
    `weapon_fireextinguisher`,
    `weapon_flashlight`,
},

Hunger and thirst effects

RB HUD treats hunger and thirst as fullness values: 100 is full and 0 is empty. lowStatusEffects controls the dizzy effect when either value becomes low.

Set lowStatusEffects = false to skip the low-status effect thread entirely.

Player-owned settings

The following preferences are changed through HUD Studio or exports and saved per player in the versioned rb_hud_profiles client KVP:

• Map mode: Only in Vehicle, Always On, or Always Off
• Compass mode: Only in Vehicle, Always On, or Always Off
• Compass style: Default or Bar
• Minimap X/Y offsets
• Position, scale, and visibility for player, vehicle, aircraft, compass, waypoint, and weapon HUD classes

Run /edithud or call the editMode export to open HUD Studio. Players can save up to 12 named profiles. Every profile is a complete snapshot containing all six HUD classes, minimap offsets, and display preferences.

Existing single-layout rb_hud_settings data is migrated into the Default profile automatically. RB HUD continues mirroring the active profile to that legacy key for compatibility. The Default profile cannot be renamed or deleted.