# HUD — documentation

> Status bars on the minimap, money and job in the corner, a vehicle cluster that works in cars, helicopters and boats.

- URL: https://xexstudio.com/docs/hud
- Version: 1.0.1
- Product page: https://xexstudio.com/scripts/hud
A HUD that stays out of the way: status bars anchored to the minimap, a money and job panel, and a vehicle cluster
with seatbelt, cruise control and replicated turn signals. Three layouts and per-indicator visibility, chosen by each
player from an in-game menu and remembered on their PC. ESX, QBCore and Qbox.

## Requirements

- [ox_lib](https://github.com/overextended/ox_lib)
- One framework: **ESX** (with `esx_status`), **QBCore** or **Qbox**
- Optional: a fuel resource (ox_fuel, LegacyFuel, ps-fuel, cdn-fuel, okokGasStation, lj-fuel, Renewed-Fuel) and a
  society bank (esx_society, qb-banking, Renewed-Banking or qb-management) for the boss balance

## Install

1. Stop any other HUD (`qbx_hud`, `qb-hud`, `esx_hud`, `trew_hud_ui`, ...). Two HUDs draw over each other.
2. Drop `xex_hud` into your resources folder.
3. Add to `server.cfg` after your framework and ox_lib:
   ```cfg
   ensure xex_hud
   ```
4. Set the language with `setr ox:locale en` (or `es`).
5. Put your logo in `ui/img/` and point `Config.UI.logo` to it, or use a URL. Leave it empty to hide the logo.

## What players see

| Area | Content |
| --- | --- |
| Status (above or beside the minimap) | Health, armour, hunger, thirst, stress and sleep when the framework reports them; oxygen while diving |
| Critical capsules | Hunger or thirst under 5 % (configurable) with a soft screen tint and camera shake |
| Above the status block | Street, zone and compass heading |
| Top-right panel | Logo, job and grade, server id, cash, bank, dirty money (ESX) and the society balance for bosses |
| Bottom-right | Voice chip: talking state, range (whisper, normal, shout) and radio, with pma-voice out of the box |
| Vehicle cluster | Speed, rpm arc, gear, fuel, engine health, seatbelt, lights, turn signals, cruise control and altitude in aircraft |

`/hud` opens the settings menu: layout (Compact, Balanced, Classic), each indicator visible or hidden, the money
panel, the vehicle cluster, the street line and the voice chip. `/togglehud` hides everything. Both are remembered per player. Keys for the seatbelt
(K), cruise control (U) and turn signals (arrows) can be changed by each player in Settings > Key Bindings > FiveM.

The HUD puts GTA's own minimap at its default place and size (`Config.Minimap` can move it), undoing any position
another resource left behind, and anchors the status block to that box with the player's safe zone and aspect ratio,
so it lines up at any resolution and drops to the corner when the radar is hidden. The size stays the game's: its
map mask only fits that size (square-map HUDs replace the mask texture to stretch it). With `manage = false` it
leaves the minimap alone and assumes the default one.

pma-voice's own range box is turned off through its `voice_enableUi` convar (`Config.Voice.hideVoiceResourceUi`),
because the HUD shows the range in its voice chip. Players already connected see it go at their next range change.

## Configure

Everything lives in `config.lua`:

| Setting | What it does |
| --- | --- |
| `Config.Framework` | `auto`, or force `esx` / `qb` / `qbox` |
| `Config.Commands` | Command names for the settings menu and the toggle (`false` disables one) |
| `Config.UI` | Accent colour, logo, which money accounts and job details to show, currency prefix and number format |
| `Config.Status` | Update interval, which indicators exist, critical threshold, shakes, sleep notices, available layouts and the default one |
| `Config.Minimap` | Position and size of the minimap the HUD anchors to |
| `Config.Location` | Street, zone and heading line and how often it is checked |
| `Config.Voice` | Voice chip and the labels of the three ranges |
| `Config.HideGameHud` | GTA elements this HUD replaces (cash, vehicle name, area and street names) |
| `Config.Vehicle` | Speed unit, fuel source, seatbelt (block exit, eject on crash), cruise control, engine health, turn signals, sounds, default keys and car classes |

Texts are in `locales/*.json`. Colours of the bars are CSS variables at the top of `ui/style.css`.

### Needs per framework

| Framework | Hunger / thirst | Stress | Sleep |
| --- | --- | --- | --- |
| ESX | `esx_status` | `esx_status` if a `stress` status exists | `esx_status` if a `sleep` status exists (100 = exhausted) |
| QBCore / Qbox | `metadata.hunger` / `metadata.thirst` | `metadata.stress` | not reported, bar hidden |

An indicator the framework never reports is simply not drawn. Set `Config.Status.stress` or `sleep` to `false` to
hide one on purpose.

## For developers

Exports (client):

```lua
exports.xex_hud:setVisible(false)   -- hide temporarily (pause menu, cinematic, character creator); true restores
exports.xex_hud:isVisible()          -- true when the HUD is on screen
exports.xex_hud:isEnabled()          -- the player's own on/off preference
exports.xex_hud:setEnabled(true)     -- change that preference
exports.xex_hud:openSettings()       -- open the settings menu from your own menu
```

Events (client):

- `xex_hud:setVisible` (`true` / `false`): same as the export, for resources that prefer events.
- `xex_hud:visibilityChanged` (`visible`): fired whenever the HUD appears or disappears.

Vehicle turn signals are stored in the vehicle state bag as `xex_hud:indicators` (`off`, `left`, `right`, `both`), set
only by the entity owner and validated on the server.

The open `bridge/client.lua` reads needs, money, job, death, fuel and voice (pma-voice: proximity from the player
state bag, talking from mumble); `bridge/server.lua` resolves the society balance. Adapt them for a custom core,
bank or voice resource (saltychat, mumble-voip).

## Performance

Status values are sent to the NUI only when something changes (once a second at most). The vehicle loop runs every
100 ms while driving with the engine on and every 500 ms otherwise. There is no per-frame loop except while the
seatbelt is fastened and `blockExit` is on, which needs `DisableControlAction` each frame.

resmon figures are measured on a clean server before each release and listed on the product page.

## Security

Nothing in this resource gives money, items or licenses. The society balance is resolved on the server from the
player's real job, and turn signals are only accepted from the vehicle owner.