Installation

Requirements

• A recent FiveM server artifact (uses state bags and GlobalState)
• Node 18+ to build the NUI once

Optional, auto-detected:

Kind	Resources
Framework	qbx_core, qb-core, es_extended (+ esx_status for hunger and thirst)
Voice	pma-voice, saltychat, yaca-voice
Fuel	ox_fuel, LegacyFuel, cdn-fuel, ps-fuel (otherwise GetVehicleFuelLevel)

Steps

1. Put the resource in resources/ as np_hud.
2. Build the NUI:

   cd web && npm ci && npm run build

   This creates web/dist, which the manifest loads as ui_page.
3. Start it after the optional resources, because detection runs once at start:

   ensure qbx_core      # or qb-core / es_extended (+ esx_status)
   ensure pma-voice     # or saltychat / yaca-voice
   ensure ox_fuel       # optional
   ensure np_hud

4. Turn off the HUD your framework ships (qb-hud, ps-hud, esx_hud, …) and any other script that repositions the minimap.

Test it

Set Config.Debug = true and run /hud_demo in game. It shows every toast variant, a prompt and a progress bar.

Optional next steps

• Route your framework's notifications to np_hud: Integration → Framework notifications
• Set your server name, logo and brand colour: Configuration, Theming
• Using an inventory with a hotbar? Turn on Config.Components.hotbar and see Hotbar.

Troubleshooting

Symptom	Fix
No HUD at all	web/dist is missing. Build the NUI.
HUD stays hidden after spawning	The framework bridge waits for isLoaded(). Check that the framework starts before np_hud.
Money / job / hunger don't show	Running standalone. Check the framework start order, or set Config.Framework explicitly.
Minimap doesn't line up with the frame	Set Config.Debug = true to print the computed values, then set Config.Minimap.native by hand. See Configuration → Minimap.
Two seatbelt systems fight	Set Config.Seatbelt.enabled = false. See Integration → Seatbelt.