Features

gta6_hud follows the GTA VI look: no panels, thin bars that disappear when they carry no information, a rounded-rectangle minimap and a column of pills stacked above it while driving. This page walks through each element, what feeds it and when it is hidden.

Screen layout

Area	Elements
Bottom-left, above the minimap	Status bars (health, armour, stamina / oxygen, hunger, thirst, stress) and the chips row (voice, armed, parachute, developer mode)
Bottom-left, directly above the minimap (vehicle only)	Zone pill, navigation pill, vehicle tile. The status bars slide up by the measured height of this column
Right of the minimap (vehicle only)	Speed readout with unit, voice chip, altitude (aircraft), nitro and harness bars, cruise-control chip
Top centre (vehicle, or always if enabled)	Compass strip with street names and heading
Top-right	Weapon block (ammo and icon) with the money block underneath

All sizes are expressed in a unit of 1/1080 of the screen height, so the HUD scales with the resolution. Fonts: Inter for bars, speed and menu, Pricedown for money and ammo, Montserrat SemiBold for the zone and navigation pills.

Status bars

Six rows, each a 22-unit icon disc followed by a 220 × 10 unit bar.

Row	Source	Visible when	Turns red when
Health	GetEntityHealth(ped) - 100	Always on foot. In a vehicle: after losing health (for Config.VehicleHealthTimeout), at or below Config.VehicleHealthLow, while dead, always with Config.ShowFullHealthInVehicle, or always when the health switch in the menu is off	Health ≤ 25 or dead. A notch marks 25% on the bar
Armour	GetPedArmour	Armour above 0 (or always if the "armour" switch is off in the menu)	Never
Stamina / oxygen	100 - GetPlayerSprintStaminaRemaining, or GetPlayerUnderwaterTimeRemaining × 10 under water	Below 100 (or always if the "stamina" switch is off). The icon changes to an O₂ symbol under water	≤ 20
Hunger	Framework (see Framework Compatibility)	For Config.StatusTimeout after it drops, permanently at ≤ 30, with Config.ShowStatusAlways, or if the "hunger" switch is off	≤ 30
Thirst	Framework	Same rule as hunger	≤ 30
Stress	Framework (QBCore / QBox)	For Config.StatusTimeout after it rises, permanently at ≥ 75, with Config.ShowStatusAlways, or if the "stress" switch is off	≥ 75

When health, armour, stamina, hunger or thirst goes down, the icon disc pulses once and flashes red (700 ms). If another drop happens during the pulse, the animation is queued and played once more. Stamina falls on every tick while sprinting, so its icon keeps pulsing for as long as the sprint lasts.

While the player is dead the health bar shows 100% in the alert colour.

Chips row

Small 22-unit discs to the right of the status bars.

Chip	Shown when	Details
Voice	Always	A ring around the microphone shows the pma-voice proximity range (distance ÷ 6, capped at 100%). Yellow while talking, pink while transmitting on the radio. The icon switches to a headset when a radio channel is joined
Armed	The selected weapon is not WEAPON_UNARMED and not listed in Config.WhitelistedWeaponArmed	Melee weapons, throwables and tools are whitelisted by default, so the chip means "firearm"
Parachute	GetPedParachuteState is 1 or 2 (deploying or open)
Developer mode	After the qb-admin:client:ToggleDevmode event (/dev command)	QBCore and QBox only

In a vehicle the voice chip moves under the speed readout.

In a vehicle

The vehicle column appears when the player sits in anything except a bicycle. Bicycles count as "on foot".

Element	Source	Behaviour
Speed	GetEntitySpeed × 2.23694 (MPH) or × 3.6 (KM/H), rounded up	Animated towards the new value with a 220 ms exponential ease. Unit label from Config.UseMPH
Altitude	Entity height × 0.5, rounded up	Only in helicopters and planes
Seatbelt chip	Framework	Hidden in aircraft. Dim when buckled, red and pulsing when not. The hud:client:ToggleShowSeatbelt event hides the chip entirely
Engine chip	GetVehicleEngineHealth ÷ 10	Faded while healthy. Below 95% (or always when the "engine" switch is off) it brightens and a ring shows the health: mint, yellow at ≤ 75%, red at ≤ 45%
Fuel chip	LegacyFuel:GetFuel or GetVehicleFuelLevel, refreshed every 2 s and immediately after changing vehicle	Ring shows the level. Red and pulsing at ≤ 20%
Cruise-control chip	Framework	Mint icon while active
Nitro bar	hud:client:UpdateNitrous	Shown while the level is above 0 (or from 0 upwards with the "nitro" switch off). Glows while nitro is active
Harness bar	hud:client:UpdateHarness and the harness item / state bag	Shown while a harness is equipped. Bar = harness HP × 5, capped at 100%

The engine, fuel and seatbelt chips live inside the vehicle tile; speed, altitude, nitro, harness and cruise control live to the right of the minimap.

Vehicle tile

A two-tone tile the width of the minimap: the top part shows the make and model (from GetMakeNameFromVehicleModel and GetDisplayNameFromVehicleModel, both resolved through GetLabelText), the bottom part holds the engine, fuel and seatbelt chips.

For 3.5 seconds after entering a vehicle or whenever the vehicle name changes, the full tile is shown. Then the name strip folds up (0.8 s), the backgrounds and border fade out and only the three chips remain. The status bars follow the tile's height with the same easing, so nothing overlaps.

Zone pill

Directly above the minimap while driving. Shows the zone label from GetNameOfZone (resolved through GetLabelText), refreshed every 1.5 seconds. Long names wrap onto a second line and the pill grows. Hidden when the label is empty or Config.ShowZone is false.

Navigation pill

Above the zone pill, only while a waypoint is set (IsWaypointActive). A dedicated thread samples the route every 200 ms, independently of the HUD's power saving mode. The pill shows an instruction (from the nav_* locale keys), a manoeuvre icon in a teal square and, for turns only, a distance.

GenerateDirectionsToCoord has three quirks that the HUD works around:

• The first call returns zeros. The native is called twice in a row with a frame in between, and only the second result is used.
• The waypoint blip carries no height. Its coordinates are snapped to the nearest road with GetClosestVehicleNode before directions are requested.
• The distance measures the next junction, not the next manoeuvre. On a straight road every side street is a junction, so the value counts down to zero again and again. A distance is therefore shown only for real turns, and a non-positive reading is discarded: the previous value is kept and reduced by the distance actually driven until a valid reading arrives.

Direction code	Text key	Icon	Distance shown
1	recalc	recalculating	No
2	proceed	straight arrow	No
3	left	left turn	Yes
4	right	right turn	Yes
5	straight	straight arrow	No
6	sharpLeft	sharp left	Yes
7	sharpRight	sharp right	Yes
8	recalc	recalculating	No
9 (custom)	arrived	flag	No. Set when the player is within 25 m of the waypoint

A code of 0 from the native means "no new instruction" and keeps the previous one. The distance travels to the NUI in whole metres and is rounded once there, to 10 ft or 10 m with a minimum of one step, following Config.NavUnits.

Minimap

client/minimap.lua turns the radar off when the resource loads and then reacts to the hud:client:LoadMap event (fired after the settings are applied and after "Restore defaults"):

1. Requests the gta6_graphics texture dictionary (waits up to 5 s).
2. Replaces the radar mask radarmasksm with the rounded-rectangle mask from that dictionary.
3. Positions the minimap component at the bottom-left. The horizontal offset and the width are multiplied by 1.7777 / GetAspectRatio(false), so the map keeps the same pixel size relative to the screen height and stays under the NUI overlay, which is laid out in vh. At 16:9 the factor is 1 and the values are the original -0.0045, 0.002, 0.170, 0.188888.
4. Replaces HUD colour 142 with rgb(247, 115, 164), the GTA VI pink used for the route and the waypoint.
5. Toggles the big map on and off once to force a redraw.

A background loop keeps the big map off and calls SetRadarZoom(1000) every 500 ms, so the zoom does not jump when changing vehicles or entering interiors.

When the radar is displayed: in a vehicle, unless "hide minimap in vehicles" is on; on foot only if "show minimap outside vehicles" is on; never in cinematic mode. client/player.lua is the only place that calls DisplayRadar, and it asserts the state on every tick, so another resource cannot leave the radar in the wrong state.

Border: the menu can draw a 3-unit border around the map area. There is no shape switch; the minimap is the rounded rectangle from the streamed mask.

Compass

Enabled by Config.ShowCompass. A 240-unit strip at the top centre with a ruler of cardinal points (N in mint), a pink pointer and, underneath, the two street names from GetStreetNameAtCoord (refreshed every 1.5 s) with the heading in degrees between them.

• The heading follows the gameplay camera by default, or the player's entity heading if "compass follows camera" is off.
• Shown in vehicles. On foot it is shown only with "compass outside vehicles" on, and then the strip is always drawn but without street names.
• The strip, pointer, degrees and street names can each be switched off in the menu.
• "Compass in power saving mode" samples the heading every 50 ms instead of every frame.

Weapon block

Enabled by Config.CustomWeaponHud. Top-right, drawn in Pricedown: the clip count, the reserve count in muted white next to it, and the weapon icon below. Polled every 100 ms while a weapon is shown (250 ms otherwise) and only sent to the NUI when something changed.

Weapon	What is shown
Firearm with a magazine	Clip and reserve (total minus clip). The clip turns red at 0
Throwables and weapons without a magazine	A single count
Melee, unarmed, parachute, stun-gun and petrol-can groups (the last one covers the petrol can, the hazard can and the fire extinguisher)	Icon only
WEAPON_UNARMED or a hash in Config.WeaponHudHidden	Nothing
Weapon not in Config.WeaponIcons	Numbers without an icon

The native weapon and ammo component (HUD component 2) is hidden every frame while this feature is on. The block hides together with the rest of the HUD (pause menu, cinematic mode).

Money block

Below the weapon block, also in Pricedown. Bank above cash, each with an icon disc (purple bank, green wallet). The block is not permanent:

• A money change (hud:client:OnMoneyChange on QBCore / QBox, esx:setAccountMoney on ESX) shows both amounts for 2.5 s and a +$ / -$ delta line for 1.5 s.
• /cash and /bank (QBCore and QBox) show the requested amount for 3.5 s.

Cinematic mode

The menu's cinematic switch draws a black bar across the top and bottom tenth of the screen, hides the radar and hides the HUD elements. Switching it off restores the radar. A notification is sent on each switch if "cinematic notifications" is on.

Low fuel alert

Every 10 s, if "low fuel alert" is on and the player is in a non-bicycle vehicle with fuel at 20% or less, the HUD sends the low_fuel locale string as an error notification and waits 60 s before checking again.

Update rates

Loop	Interval
Player and vehicle data	500 ms in "power saving mode" (default) or 50 ms
Compass heading	50 ms in power saving mode (default) or every frame
Weapon	100 ms while shown, 250 ms otherwise
Zone name, street names	1.5 s
Navigation	200 ms, in its own thread
Fuel	2 s
Harness item scan (QBCore)	1 s while in a vehicle
Minimap zoom lock	500 ms

The NUI only receives a message when at least one value changed since the last tick.