# Features

This page describes every part of the HUD from the player's side: what it shows, where the data comes from, and what a player can change in `/settings`.
For the options you control as a server owner, see [Configuration](/free/hud/configuration).

The HUD appears about a second after the character has loaded, and hides itself while the pause menu is open (`KOJA.HideHudOnPauseMenu`).

## Status bars

Eight bars, each with its own colour:

| Bar | Source |
| --- | --- |
| Health | The player's health; 0 while dead |
| Armour | The player's armour |
| Hunger, Thirst | ESX: `esx_status`. QBCore and QBox: player metadata. ox_core: the `ox:statusTick` event |
| Stamina | Sprint stamina |
| Oxygen | Time left underwater |
| Voice | The pma-voice range, mapped by `KOJA.Microphone.Levels` |
| Stress | The HUD's own stress value — see [Stress](/free/hud/exports-and-events#stress) |

Players choose one of five styles — **Default**, **Circle**, **Echo**, **Minimal**, **Hexagon** — plus the colour of each bar, which bars are shown, the corner rounding and the size (**Small**, **Default**, **Big**).
Each bar can also be set to appear only above or below a value, so hunger and thirst stay out of the way until they matter.

## Speedometer

Shown while the player is in a vehicle.
Five styles: **Gauge** (the default), **Default**, **Compact**, **Minimal** and **PVP**, in km/h or mph.

Elements a player can switch on and off:

| Element | Shows |
| --- | --- |
| Gear | Current gear, `N` in neutral, `R` when reversing |
| Fuel | Fuel level, or battery for models listed in `data/electricmodels.lua` |
| Nitro | Nitro left in this vehicle |
| Seatbelt | Whether the belt is on |
| Engine | Whether the engine is running |
| RPM | Engine revs |
| Engine health | Engine condition, 0–100 |
| Lights | Headlights and high beams |
| Indicators | Turn signals |
| Cruise | Whether cruise control is on |

RPM, engine health, lights, indicators and cruise are off by default.

## Notifications

Up to six at a time, newest first, in three styles — **Default**, **Minimalistic**, **Modern** — top right or bottom left.
Notification text may contain simple HTML for emphasis, such as `<strong>` or a coloured `<span>`; anything else is stripped.
Other resources send them with [`sendNotify`](/free/hud/exports-and-events#sendnotify).

## Progress bar and text UI

The **progress bar** shows an icon, a label and a filling bar; it can play an animation, block keys and be cancelled with **X**.
The **text UI** is the "press E to…" prompt: a key, a small heading and a line of text.

Both are driven by other resources — see [Exports & Events](/free/hud/exports-and-events#progress-bar).

## Information panel

Cash and bank balance, job, server ID, a clock, the microphone (highlighted while talking, with the range shown as one to three bars), your Discord invite and your logo.
Each item can be hidden, and the panel's opacity changed.

The clock shows the player's own local time.
Cash and bank are read through koja-lib.
The Discord invite and logo URL are set in [`js.json`](/free/hud/player-settings#ui).

## Key hints

A list of keys and what they do, on the right or left of the screen.
It is a reminder only — you write it in [`js.json`](/free/hud/player-settings#ui) to match your server.

## Compass

A heading compass in three styles — **Bar**, **Minimal**, **Cardinal** — shown always, only in vehicles, only on foot, or never.
Turned off entirely with `KOJA.Compass.Enabled = false`.

## Weapon panel

The name of the weapon in hand, the ammo in the magazine and the ammo in reserve.
Off by default; players switch it on in **Settings → MAIN → Weapon Settings**.
Names come from `data/weapons.lua`.

## Killfeed

A list of recent kills — killer, weapon icon, victim, distance and a headshot marker — in three styles: **Default**, **Minimal**, **Modern**.
Entries disappear after six seconds.

Out of the box it records kills made by the player themself, and counts a **killstreak**: two or more kills within twelve seconds of each other, reset when the player dies.
Players can limit it to kills within a distance.
To show kills made by other players, send them from your own code — see [AddKillfeed](/free/hud/exports-and-events#addkillfeed).

## Status effects

A row of small icons for active effects — drunk, cold, buffed — each with an optional countdown ring.
Your resources add and remove them through [the status effects exports](/free/hud/exports-and-events#status-effects).
With `KOJA.StatusEffects.Builtin = true`, sprinting and swimming also show up.

## Warnings

- **Low health** — a red vignette when health drops to the threshold (20% by default).
- **Low fuel** — an alert in a vehicle when fuel drops to the threshold (15% by default).
- Both can beep once when they start.

Players change the thresholds or turn either warning off in **Settings → MAIN → Warnings**.

## Watermark

Your server's name at the top of the screen, enabled with `KOJA.Watermark`.
Three styles — **Default**, **Line**, **Bracket** — five fonts, and a size and colour of the player's choice.

## PVP mode

A switch in **Settings → MAIN → PVP Mode** for players who want a clean combat screen.
While it is on:

- the status bars, information panel, key hints and compass are hidden;
- the speedometer uses the compact **PVP** style;
- the killfeed is always shown;
- the watermark also shows the player's health and armour.

## Minimap

With `KOJA.MiniMap.Enabled = true` the round radar is replaced by a square minimap.
Players choose when it is shown — always, in a vehicle, on foot, never — and move and resize it in the layout editor (60%–190% of its normal size).

If you set `KOJA.NeedItemForMinimap`, it only shows while the player carries that item.

## Layout editor

**Settings → Edit layout** turns every element into a box the player can drag: status, speedometer, information panel, notifications, progress bar, text UI, key hints, compass, weapon panel, minimap, watermark, killfeed and status effects.
Example content is shown for anything not currently on screen, so empty elements can be placed too.
**Save layout** keeps the positions; **Reset positions** puts everything back.

## Key binds

**Settings → BINDS** has two lists:

- **Active binds** — the HUD's own actions (engine, seatbelt, cruise control, nitro, vehicle menu). A player can move any of them to another key; the original key is then released.
- **Custom binds** — any key to any chat command, without the slash. `F5` → `e sit` runs `/e sit`. The command runs as if the player typed it.

Players can also rebind the HUD's actions the usual FiveM way, in **Settings → Key Bindings → FiveM** in the GTA pause menu.

## Vehicle menu

Opened with **U** or `/vehicle` while driving.
It controls the engine, seatbelt, headlights, left and right turn signals, hazard lights, all four doors, the hood and the trunk.
It closes by itself when the player leaves the driver's seat.

## Engine

The driver switches the engine on and off with **B**.
With `KOJA.Engine.StartEngineOnEntering = false`, getting into a vehicle whose engine is off leaves it off: the vehicle will not accelerate or brake until the driver starts it.

## Seatbelt

**L** fastens and unfastens the belt.
With the belt on, the player cannot leave the vehicle with **F**.
Without it, a sudden crash above `KOJA.Seatbelt.MaxVehicleSpeedToRagdoll` (70 km/h by default) throws the player through the windscreen.
Leaving the vehicle always unfastens the belt.

## Cruise control

**T** holds the current speed, from 20 km/h upwards (`KOJA.CruiseMode.MinSpeed`).
It switches off when the driver brakes, leaves the seat, or the vehicle leaves the ground, with a notification saying why.

## Nitro

Nitro belongs to a vehicle, not a player, and only to vehicles in your owned-vehicles table.

1. **Install** — the player stands next to their own car (not inside it) and something calls [`SetNitro`](/free/hud/exports-and-events#setnitro), usually your inventory when the nitro item is used. After a five-second animation the tank is full and, if `KOJA.Nitro.Item` is set, one item is taken.
2. **Boost** — the driver presses **N**. The engine gets `KOJA.Nitro.NitroForce` more power, with exhaust backfire, light trails, motion blur and camera shake. Press **N** again to stop early.
3. **Save** — what is left is saved to the database when the boost ends and when the driver gets out, so it survives restarts and garage storage.

A car that already has nitro cannot be refilled until it is empty.
Only the owner can install nitro or load it.