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.

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:

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:

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.

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.

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.

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 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.

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. 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, 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.