# 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](https://github.com/qbcore-fivem/qb-hud/tree/65d102aeb0de7e2ab08319bc619e85d4c4f55334).

![qb-hud player status event and NUI update flow](/diagrams/hud.svg)

*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](https://github.com/qbcore-fivem/qb-hud/blob/65d102aeb0de7e2ab08319bc619e85d4c4f55334/fxmanifest.lua) 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`](https://github.com/qbcore-fivem/qb-hud/blob/65d102aeb0de7e2ab08319bc619e85d4c4f55334/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 |

~~~lua filename="config.lua"
-- 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`](https://github.com/qbcore-fivem/qb-hud/blob/65d102aeb0de7e2ab08319bc619e85d4c4f55334/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`](https://github.com/qbcore-fivem/qb-hud/blob/65d102aeb0de7e2ab08319bc619e85d4c4f55334/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

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](https://rpscripts.net/product-category/fivem-hud/). 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](https://github.com/qbcore-fivem/qb-hud/tree/65d102aeb0de7e2ab08319bc619e85d4c4f55334) · [Config](https://github.com/qbcore-fivem/qb-hud/blob/65d102aeb0de7e2ab08319bc619e85d4c4f55334/config.lua) · [Client](https://github.com/qbcore-fivem/qb-hud/blob/65d102aeb0de7e2ab08319bc619e85d4c4f55334/client.lua) · [Server](https://github.com/qbcore-fivem/qb-hud/blob/65d102aeb0de7e2ab08319bc619e85d4c4f55334/server.lua)

Related: [qb-fuel](/docs/resources/qb-fuel), [performance basics](/docs/performance/resmon-basics).
