qb-hud Guide for QBCore

qb-hud is the QBCore heads-up display resource for player vitals and gameplay status. It shows health, armor, hunger, thirst, stress, cash, bank, vehicle state, compass data, harness state, and other roleplay indicators depending on your config.

Use qb-hud when you want the official QBCore HUD. Use the public QBCore HUD systems hub when you want to compare free and premium replacement HUDs.

What qb-hud Controls

HUD area	What to check
Player vitals	Health, armor, hunger, thirst, stress
Money display	Cash and bank popups
Vehicle HUD	Speed, fuel, engine health, seatbelt or harness states
Compass	Street names, heading, minimap alignment
Settings menu	Player-side HUD preferences stored on the client
Developer indicators	Dev mode and admin/debug display when enabled

Installation

Place the resource in your QBCore resource folder:


cd resources/[qb]
git clone https://github.com/qbcore-framework/qb-hud.git

Add it to server.cfg after qb-core:


ensure qb-core
ensure qb-hud

Restart the server, join with a test character, and confirm that health, armor, hunger, thirst, and vehicle indicators update while playing.

Configuration Checklist

Most servers only need to review these items:

Need	File or area
Disable or tune stress	`qb-hud/config.lua`
Adjust hunger/thirst behavior	QBCore core config and status events
Fix minimap or border alignment	GTA display safezone setting
Reset a player’s HUD settings	In-game HUD settings menu on that player’s client
Replace the whole HUD	Compare alternatives on QBCore HUD systems

The official QBCore HUD stores some player settings on the player’s machine. If one player’s layout is broken, reset it through that player’s in-game HUD settings before changing server files.

Common Fixes

HUD does not show

Confirm ensure qb-hud appears after ensure qb-core.
Check the server console for startup errors.
Check the client F8 console for UI errors.
Disable other HUD resources temporarily to rule out duplicate UI conflicts.

Hunger, thirst or stress looks wrong

Check whether the issue is display or data:

If values never change, inspect the status events and QBCore config.
If values change but display wrong, inspect qb-hud/config.lua.
If only one player is affected, reset that player’s HUD settings.

Minimap borders do not align

Reset the GTA display safezone to default, then reconnect. Safezone changes often make HUD and minimap borders look misaligned even when the resource is working.

Harness indicator appears unexpectedly

The harness indicator appears when the server uses the harness item and the player is in a vehicle. Check the player’s inventory and the HUD config before removing the UI element.

When to Use a Replacement HUD

Stay with qb-hud if you want the official QBCore baseline, simple maintenance, and predictable compatibility. Consider a replacement HUD when you need a custom visual style, more vehicle widgets, branded layouts, or a premium support channel.

Compare options on the QBCore HUD systems hub.