GhiaccioScripts

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

KeyDefaultWhat 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.ServerNameTop-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.TimeResyncMinutes10How often the client resyncs its clock
Config.Editorenabled = true, command = 'hud', key = 'F7'Editor command and default key (rebindable in Settings > Key Bindings > FiveM)
Config.Commandssee belowCommand names and keys
Config.Featuressee belowFeature toggles
Config.TickonFoot 300, vehicle 100, nav 500, slow 2000Loop rates in ms
Config.Integrationsall 'auto'fuel, status, voice, seatbelt: 'auto', an adapter name, or false
Config.CrashEffectsee belowEffect after a serious crash
Config.Seatbeltejection = true, ejectKmh = 70, blockExit = trueBuilt-in seatbelt
Config.Stressenabled = true, shooting = 1, speedingKmh = 160, ...Built-in stress
Config.Minimapsee belowMinimap shape, masks, calibration
Config.HideNativeComponentswanted stars, weapon and ammo, money, zone / street / vehicle names, weapon statsGTA base HUD components hidden; crosshair and weapon wheel stay

#Commands

lua
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

lua
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

KeyDefaultWhat it does
Config.DbSyncfalseSync 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.lockedcommented outtrue = non-admins cannot edit the HUD
Config.RateLimitsee fileNetwork event limits per event (window in seconds, max per window)
Config.LogRejectedtrueLog rejected events (validation, rate limit, permissions)

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.

lua
-- 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 hand

square 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:

KeyDefaultEffect
enabledtruefalse = no effect and no detection thread
minSpeedLossKmh60Sudden speed loss that counts as a serious crash
cooldownSeconds20Minimum pause between two effects
blackouttrueShort black screen in the worst cases (never with the seatbelt on)
staggerOnFoottrueStaggering walk if you step out during the effect
seatbeltReducestrueSeatbelt reduces intensity and duration
soundtrueMuffled 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)

bash
cd web
npm i && npm run build     # tsc + vite -> web/dist (committed)
npm test