QBCore Frameworkqbcore.netCommunity docs
On this page

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.

qb-hud player status event and NUI update flow

Conceptual diagram; verify the behavior against your installed resource version.

Installation

  1. Start qb-core and the actual HUD-related providers used by your server, including fuel/vehicle-state resources.
  2. Deploy qb-hud with client.lua, server.lua, config.lua and the complete html/ asset set. The manifest loads the NUI entry html/index.html.
  3. Disable a competing HUD or duplicate stress/seatbelt handler before testing.
  4. 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:

KeyDefaultMeaning
Config.OpenMenu'I'HUD menu hotkey
Config.StressChance0.1Stress chance from shooting
Config.UseMPHtrueSpeed units (requires matching CSS text if switching)
Config.MinimumStress50Stress effect threshold
Config.MinimumSpeedUnbuckled50Stress threshold without seatbelt
Config.MinimumSpeed100Higher speed threshold with seatbelt
Config.DisableStressfalseDisable stress effects
Config.WhitelistedWeaponArmed / WhitelistedWeaponStressTablesWeapon exceptions
Config.WhitelistedVehicles / WhitelistedJobsTablesStress exceptions
Config.MenuTableHUD/compass/vehicle toggles
-- Edit the existing config, keeping NUI styles consistent with the unit text:
Config.OpenMenu = 'I'
Config.UseMPH = true
Config.DisableStress = false

Changing 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

SymptomFirst check
Status UI invisibleFull NUI assets, loaded character and client console
Hunger/thirst remain unchangedQBCore player metadata and hud:client:UpdateNeeds
Stress resets or behaves oddlyDisableStress, stress events and competing resources
Speed units are incorrectConfig.UseMPH and CSS label
Seatbelt indicator appears unexpectedlyqb-smallresources seatbelt event integration
Compass/minimap overlapsNUI menu state and resolution/anchor settings
Fuel gauge does not follow vehicleFuel resource interface and installed HUD version

Update checklist

  1. Pin qb-hud, qb-core, vehicle/fuel and qb-smallresources versions.
  2. Test no HUD, stress, speed or seatbelt duplication with installed UI mods.
  3. Verify settings persistence and NUI behavior after reconnect or resource restart.
  4. 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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website