Configuration

Everything is in shared/config.lua. The file is shared (client and server), so keep secrets out of it.

Overview

Option	Default	Description
Config.Debug	false	Verbose logs and the hud_demo command
Config.Framework	'auto'	'qbx', 'qb', 'esx', 'standalone', or auto-detect (qbx → qb → esx → standalone)
Config.Voice	'auto'	'pma-voice', 'saltychat', 'yaca', 'none', or auto-detect
Config.Locale	'en'	NUI language (en, de)
Config.Units	'kmh'	'kmh' or 'mph'
Config.Server	{ name = 'Nimbus RP', logo = 'N' }	Top-bar server chip. logo is a single character or an image URL (nui:// or https://)
Config.Theme	{ brand = nil, strength = 'accent' }	See Theming
Config.Scale	1.0	HUD scale on top of the automatic viewport-height scaling (1 = designed for 1920×1080)
Config.StreamerMode	false	Hide the server id
Config.MaxToasts	4	Toasts visible at once
Config.Components	all on, hotbar off	Which zones render (see below)
Config.Status	{ 'health', 'armor', 'hunger', 'thirst', 'stamina', 'stress', 'oxygen' }	Order and selection of status tiles. oxygen only shows under water
Config.LowThreshold	20	Percent at or below which tiles turn "low" (stress is inverted, armour never alarms)
Config.Intervals	see below	Poll intervals in ms
Config.Clock24h	true	09:14 vs 9:14 AM
Config.CompassFollowsCamera	true	The compass follows the gameplay camera (true) or the ped/vehicle (false)
Config.Minimap	see below	Native minimap placement under the glass frame
Config.HideNativeComponents	{ 3, 4, 6, 7, 8, 9, 13 }	GTA HUD components hidden every frame
Config.Seatbelt	see below	Built-in seatbelt
Config.Vehicle	{ fuel = 'auto', maxSpeed = nil }	Fuel getter and a fixed speedometer maximum
Config.Hotbar	{ autoHide = 0 }	Hide the hotbar this many ms after each SetHotbar (0 = always visible)
Config.NotifyKeys	{ accept = 'Y', decline = 'N' }	Keys that answer actionable toasts
Config.CaptureFrameworkNotify	false	Also show framework notify events as toasts. See Integration
Config.Progress	{ cancelKey = 'X' }	Default progress cancel key
Config.JobIcons	police, ambulance, mechanic, …	Font Awesome icon per job name, plus default
Config.Commands	{ toggle = 'hud', theme = 'hudtheme' }	Command names

Components

Config.Components = {
  topBar = true, money = true, job = true, players = true, weather = true,
  status = true, voice = true, street = true, compass = true, minimapFrame = true,
  vehicle = true, weapon = true, hotbar = false, notifications = true,
}

money and job are switched off automatically in standalone mode. hunger, thirst and stress are removed from Config.Status when the framework can't provide them.

Intervals

Config.Intervals = {
  player = 500,     -- health, armor, stamina, oxygen, heading on foot
  vehicle = 100,    -- speed, rpm, gear, fuel ... while in a vehicle
  weapon = 200,     -- ammo while armed
  voice = 200,      -- talking indicator + voice range
  location = 1000,  -- street / zone
  world = 5000,     -- clock, weather, player count, screen resolution
}

Minimap

Config.Minimap = {
  enabled = true,
  x = 28, y = 794, w = 300, h = 190, -- NUI frame rect in px @1080p from the top-left
  mode = 'always',                   -- or 'vehicle': radar only while in a vehicle
  hideHealthArmour = true,           -- hide GTA's health/armour bars under the minimap
  hideNorthBlip = true,              -- the NUI compass replaces the 'N' blip
  clipSquare = true,                 -- rectangular clip instead of the round 'bigmap' style
  native = nil,
}

The rect is scaled by screen height only (not by Config.Scale), so it keeps matching the native radar. The NUI draws a 5 px glass ring inside the rect, voice and street 10 px above it, and the status tray 10 px below it.

Ultrawide and custom safezones

The conversion from the NUI rect to native minimap coordinates assumes a centred 16:9 layout and a (1 - safezone) / 2 margin. If the radar doesn't line up, set Config.Debug = true to print the computed values, then set them by hand:

native = {
  minimap = { -0.0045, 0.002, 0.150, 0.188888 }, -- posX, posY, sizeX, sizeY
  mask = { ... },
  blur = { ... },
}

The native minimap is clipped by the radarmasksm texture, so it can't follow the frame's rounded corners. The glass ring hides most of the corners.

Seatbelt

Config.Seatbelt = {
  enabled = true,
  key = 'B',
  eject = true,       -- throw unbuckled occupants through the windscreen on hard crashes
  ejectSpeed = 90,    -- minimum speed before the crash (Config.Units)
  ejectDelta = 45,    -- minimum speed lost within one vehicle tick (Config.Units)
  ejectDamage = 20,   -- health removed on ejection
}

While buckled, players can't exit the vehicle. Ejection is approximated from a speed drop between two 100 ms vehicle ticks.

Vehicle

Config.Vehicle = {
  fuel = 'auto',   -- 'auto' | 'ox_fuel' | 'LegacyFuel' | 'cdn-fuel' | 'ps-fuel' | 'native'
  maxSpeed = nil,  -- fixed arc maximum (Config.Units), nil = from the vehicle's estimated top speed
}

Hidden native components

3/4 cash, 6 vehicle name, 7 area name, 8 vehicle class, 9 street name, 13 cash change. 2 (weapon icon) and 20 (weapon wheel stats) are added automatically when Config.Components.weapon is on.

Key mappings

Players can rebind these under Settings → Key Bindings → FiveM:

Command	Default	Action
hudseatbelt	B (Config.Seatbelt.key)	Toggle seatbelt
hudaccept	Y (Config.NotifyKeys.accept)	Accept the newest actionable toast
huddecline	N (Config.NotifyKeys.decline)	Decline the newest actionable toast
hudcancel	X (Config.Progress.cancelKey)	Cancel the running progress bar