HUD
Configuration
config.lua and config_server.lua, the in-game editor, server layout, minimap and crash effect.
The visual layout is not configured in files: use the in-game editor (/hud). config.lua (replicated to clients, no secrets) and config_server.lua (server only) control behaviour.
#config.lua
| Key | Default | What it does |
|---|---|---|
Config.Locale | 'it' | 'it' / 'en' (default language, each player can change it in the editor) |
Config.Framework | 'auto' | 'auto' (qbox, qbcore, esx, standalone) or forced |
Config.Logo, Config.ServerName | Top-right logo, fallback text when the logo is empty | |
Config.TimeSource | 'real' | 'real' (server time) or 'game' (GTA clock) |
Config.Timezone | 'Europe/Rome' | IANA zone (DST computed by the server) |
Config.TimeResyncMinutes | 10 | How often the client resyncs its clock |
Config.Editor | enabled = true, command = 'hud', key = 'F7' | Editor command and default key (rebindable in Settings > Key Bindings > FiveM) |
Config.Commands | see below | Command names and keys |
Config.Features | see below | Feature toggles |
Config.Tick | onFoot 300, vehicle 100, nav 500, slow 2000 | Loop rates in ms |
Config.Integrations | all 'auto' | fuel, status, voice, seatbelt: 'auto', an adapter name, or false |
Config.CrashEffect | see below | Effect after a serious crash |
Config.Seatbelt | ejection = true, ejectKmh = 70, blockExit = true | Built-in seatbelt |
Config.Stress | enabled = true, shooting = 1, speedingKmh = 160, ... | Built-in stress |
Config.Minimap | see below | Minimap shape, masks, calibration |
Config.HideNativeComponents | wanted stars, weapon and ammo, money, zone / street / vehicle names, weapon stats | GTA base HUD components hidden; crosshair and weapon wheel stay |
#Commands
Config.Commands = {
toggle = 'togglehud', -- show / hide the HUD
cinematic = 'cinematic', cinematicKey = '',
carControl = 'carcontrol', carControlKey = '',
seatbelt = 'seatbelt', seatbeltKey = 'B',
cruise = 'cruise', cruiseKey = '',
limiter = 'limiter', limiterKey = '',
}#Features
Config.Features = {
cinematic = true,
streamerMode = true, -- the option appears in the editor (hides ID, cash, bank, street)
carControl = true,
hideWhenPaused = true, -- hide the HUD while the pause menu is open
hideWhenDead = false,
hideNativeHud = true, -- the only per-frame thread; stops when false
}#Integrations
Config.Integrations.fuel: 'auto' | 'ox_fuel' | 'LegacyFuel' | 'cdn-fuel' | 'native'. status: 'auto' | 'esx_status' | 'qb' | 'exports' | false (false = hunger / thirst hidden). voice: 'auto' | 'pma-voice' | 'saltychat' | false.
For another fuel, voice or seatbelt script add an adapter in adapters/ (format described in adapters/init.lua) and list it in fxmanifest.lua.
#config_server.lua
| Key | Default | What it does |
|---|---|---|
Config.DbSync | false | Sync layouts to a database (needs oxmysql started before the HUD). false: layouts live only in the player's KVP |
Config.AdminGroups | { 'admin', 'superadmin' } | HUD admin groups. {} = ACE only. A wrong group name grants access to nobody |
Config.ServerDefault.locked | commented out | true = non-admins cannot edit the HUD |
Config.RateLimit | see file | Network event limits per event (window in seconds, max per window) |
Config.LogRejected | true | Log rejected events (validation, rate limit, permissions) |
#Changing the logo
Put the file (for example logo.png or logo.svg) in web/public/ and rebuild (npm run build), or copy it straight into web/dist/. Then set Config.Logo = 'logo.png'. With Config.Logo = '' the Config.ServerName text is shown.
#Editor (/hud)
/hud (default key F7). The layout saves itself (your PC's KVP, 1 s debounce). Startup precedence: KVP > DB (if DbSync) > server default > built-in default.
The tabbed menu has: Move elements (full-screen drag and drop canvas), Status icons, Vehicle, Minimap, Style, Info and text, Presets, Share. Esc goes back (on Home it closes); hold Space to see the HUD without the window. Undo / redo with Ctrl+Z / Ctrl+Y. Status and vehicle icons are groups that drag as one block; missing icons collapse with no gaps.
#Server layout (admins)
In /hud > Share > Server admins can:
- Publish current layout as the server layout.
- Paste a
GHUD1.z....code and Publish code (your own layout does not change; the server revalidates size and schema). - Remove server layout.
Every publication has a version (timestamp, stored in data/server_default.json + .ts). Players who join, or are online at that moment, and have not received that version yet get it automatically: it replaces their layout once; afterwards they can edit it and their edit stays until the next publication (the publisher keeps their own). With DbSync the received version follows the player to other PCs.
With Config.ServerDefault.locked = true, non-admin players cannot edit the HUD: /hud shows a message, personal saves are rejected by the server and they always see the server layout (or the factory one). Admins can always edit and publish.
#Minimap
Shapes: rect (vanilla), square, circle. Visibility: always / vehicle only / never. The native health and armor bars are hidden and the minimap is reapplied after pause, resolution and safe-zone changes.
-- Config.Minimap keys
enabled -- true / false
masks -- 'ytd' (bundled .ytd in stream/, default) or 'runtime' (PNGs in assets/minimap/); each falls back to the other
lockBigmap -- true (default) locks the expanded radar (Z key), which would break the custom geometry
calibration -- per-shape fine tuning, written by handsquare and circle use the bundled masks stream/ghud_squaremap.ytd and stream/ghud_circlemap.ytd. If neither the .ytd nor the PNG fallback loads, the shape falls back to rect with a one-time console warning. Texture replacement is global and can conflict with other custom minimaps.
#Crash effect
After a serious crash in a vehicle (never for light bumps) a realistic effect plays: camera shake, tint and blur that fade out, muffled audio, a short blackout in the worst cases and a staggering walk if you leave the vehicle. Every key of Config.CrashEffect is optional:
| Key | Default | Effect |
|---|---|---|
enabled | true | false = no effect and no detection thread |
minSpeedLossKmh | 60 | Sudden speed loss that counts as a serious crash |
cooldownSeconds | 20 | Minimum pause between two effects |
blackout | true | Short black screen in the worst cases (never with the seatbelt on) |
staggerOnFoot | true | Staggering walk if you step out during the effect |
seatbeltReduces | true | Seatbelt reduces intensity and duration |
sound | true | Muffled audio |
excludedClasses | { 14, 15, 16 } | Boats, helicopters, planes |
#Presets and sharing
4 ready-made presets plus up to 10 personal presets (KVP). Export produces a GHUD1.z.... code; Import pastes it (CRC check; never executed nor sent to the server until you save).
#Development and build (optional)
cd web
npm i && npm run build # tsc + vite -> web/dist (committed)
npm test