Updated 2026-10-11 · 3 min read
qb-hud: health, stress, speed and compass
qb-hud renders character status (health, armor, hunger, thirst and stress), map/compass, vehicle UI and speed information. This guide is pinned to upstream commit 65d102a.
Conceptual diagram; verify the behavior against your installed resource version.
Installation
- Start
qb-coreand the actual HUD-related providers used by your server, including fuel/vehicle-state resources. - Deploy
qb-hudwithclient.lua,server.lua,config.luaand the completehtml/asset set. The manifest loads the NUI entryhtml/index.html. - Disable a competing HUD or duplicate stress/seatbelt handler before testing.
- Join with a character, open the HUD menu and verify changes in health, hunger, thirst, compass and vehicle state.
Real configuration keys
The current config.lua defines:
| Key | Default | Meaning |
|---|---|---|
Config.OpenMenu | 'I' | HUD menu hotkey |
Config.StressChance | 0.1 | Stress chance from shooting |
Config.UseMPH | true | Speed units (requires matching CSS text if switching) |
Config.MinimumStress | 50 | Stress effect threshold |
Config.MinimumSpeedUnbuckled | 50 | Stress threshold without seatbelt |
Config.MinimumSpeed | 100 | Higher speed threshold with seatbelt |
Config.DisableStress | false | Disable stress effects |
Config.WhitelistedWeaponArmed / WhitelistedWeaponStress | Tables | Weapon exceptions |
Config.WhitelistedVehicles / WhitelistedJobs | Tables | Stress exceptions |
Config.Menu | Table | HUD/compass/vehicle toggles |
-- Edit the existing config, keeping NUI styles consistent with the unit text:
Config.OpenMenu = 'I'
Config.UseMPH = true
Config.DisableStress = falseChanging UseMPH to false affects the speed calculation, but the source comments explicitly warn that html/styles.css text also needs to be updated to display the correct unit.
Actual client events
The client.lua registers hud:client:UpdateNeeds for hunger/thirst and hud:client:UpdateStress for stress. Other events include hud:client:UpdateNitrous, UpdateHarness, ToggleShowSeatbelt, ShowAccounts, OnMoneyChange and LoadMap. Seatbelt events may originate from qb-smallresources.
The server.lua handles hud:server:GainStress and RelieveStress, plus the hud:server:getMenu callback. In this revision, the resource does not register a public set of qb-hud exports for arbitrary server/client stats. Use QBCore player state and the installed HUD integration, not unverified generic HUD exports.
Troubleshooting
| Symptom | First check |
|---|---|
| Status UI invisible | Full NUI assets, loaded character and client console |
| Hunger/thirst remain unchanged | QBCore player metadata and hud:client:UpdateNeeds |
| Stress resets or behaves oddly | DisableStress, stress events and competing resources |
| Speed units are incorrect | Config.UseMPH and CSS label |
| Seatbelt indicator appears unexpectedly | qb-smallresources seatbelt event integration |
| Compass/minimap overlaps | NUI menu state and resolution/anchor settings |
| Fuel gauge does not follow vehicle | Fuel resource interface and installed HUD version |
Update checklist
- Pin
qb-hud,qb-core, vehicle/fuel andqb-smallresourcesversions. - Test no HUD, stress, speed or seatbelt duplication with installed UI mods.
- Verify settings persistence and NUI behavior after reconnect or resource restart.
- Keep custom CSS/UI changes separate so upgrades don't overwrite them.
Alternative HUDs
If you need to replace the official HUD instead of configuring it, compare third-party options in RPScripts' FiveM HUD category. RPScripts and qbcore.net are operated by the same owner. Marketplace listings are commercial alternatives, not verified compatibility recommendations; check the installed QBCore version, dependencies and license before changing resources.
Sources
Repository · Config · Client · Server
Related: qb-fuel, performance basics.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
qb-fitbit status
Current status of qb-fitbit in QBCore: why the official docs still list it, which fitbit item/metadata remnants remain, and how to evaluate third-party replacements safely.
qb-phone
Verified qb-phone setup for QBCore: real mail export, current database tables, app configuration, phone controls and integration troubleshooting.
