> For the complete documentation index, see [llms.txt](https://ccfivem.gitbook.io/ccfivem-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ccfivem.gitbook.io/ccfivem-docs/player-and-ui/hud-cc_hud.md).

# HUD (cc\_hud)

A clean HUD with status rings, location bar, player card and speedometer. It never takes mouse focus and only sends changes.

**Frameworks:** ESX Legacy, QBCore, QBox

## Features

* Rings next to the minimap: health, armour, hunger, thirst, stress, stamina, oxygen and voice range
* Compass heading, street, district and time
* Player card: cash, bank balance, job and grade
* Speedometer with RPM arc, gear, fuel and engine bars, seatbelt, lights and indicators
* Indicators on the arrow keys (rebindable), synced to other players
* Hides itself depending on the situation: when dead, in the pause menu, vehicle previews and scripted cameras
* km/h or mph, saved per player
* Lightweight: no busy loop, only changes are sent

## What is shown when

* Health below 100 %, armour when worn, hunger/thirst below 80 %, stress from 20 % (red from 70 %), stamina while used, air underwater, voice range while talking.
* Anything with nothing to say hides (`Config.Hud.alwaysShow` reverses this). Missing data is hidden, never shown as a made-up zero.

## Data sources

* **Fuel, engine, seatbelt:** cc\_fuel/00%20Overview\.md), game values, or the `cc_hud:seatbelt` event
* **Hunger, thirst, stress:** cc\_status/00%20Overview\.md), else `esx_status`, else state bags `hunger`/`thirst`
* **Voice range:** pma-voice (`proximity`)
* **Cash/bank:** computed by the server, sent on change only

{% hint style="info" %}
The code is protected by Cfx asset escrow. `config/config.lua`, `config/ui.lua`, `locales/*.json` and `shared/cc_framework.lua` stay editable.
{% endhint %}

## Pages

* Installation
* Configuration
* API
* FAQ

## Installation

See also the general installation guide, dependencies and the framework bridge.

### Requirements

| Resource                               | Required | Notes                  |
| -------------------------------------- | -------- | ---------------------- |
| `es_extended`, `qb-core` or `qbx_core` | yes      | one framework          |
| `cc_fuel`                              | optional | fuel, engine, seatbelt |
| `cc_status`                            | optional | hunger, thirst, stress |
| `esx_status`                           | optional | hunger, thirst         |
| `pma-voice`                            | optional | voice range            |
| `cc_lib`                               | optional | notifications          |

No database needed. Without an optional resource, the matching display is hidden or falls back.

### 1. Copy the resource

Copy the folder to `resources/[crankchaos]/cc_hud`.

### 2. server.cfg

```cfg
ensure es_extended   # or qb-core / qbx_core
ensure cc_lib        # optional
ensure cc_fuel       # optional
ensure cc_status     # optional
ensure cc_hud
```

### 3. Permissions and SQL

None. No SQL, no database, no ACE – player settings are stored in the player's local KVP.

### 4. Disable other HUDs

Stop any other HUD resource to avoid overlapping displays.

### Framework notes

{% hint style="warning" %}
**QBCore / QBox without cc\_status:** hunger and thirst live in the player metadata. Mirror them to the state bags `hunger`/`thirst`, or install cc\_status/00%20Overview\.md) – otherwise those rings stay hidden.
{% endhint %}

## Configuration

`config/config.lua` holds the **server defaults**. What a player changes with `/hud` is stored in their own KVP and wins; `/hudreset` restores these defaults.

### General

```lua
Config.Hud = {
    enabled = true,
    unit = 'kmh',        -- 'kmh' or 'mph'
    scale = 1.15,
    alwaysShow = false,  -- true: never auto-hide elements
    ...
}
```

### Elements (`show`)

Turn single elements on or off:

```lua
show = {
    health = true, armour = true, hunger = true, thirst = true, stress = true,
    stamina = true, oxygen = true, voice = true, money = true, job = true,
    location = true, time = true, speed = true, rpm = true, gear = true,
    fuel = true, engine = true, seatbelt = true, indicators = true,
},
```

### Thresholds (`hide`, `warn`)

```lua
hide = { health = 100, hunger = 80, thirst = 80, stamina = 95, engine = 60, stress = 20 },
warn = { health = 30, armour = 25, hunger = 25, thirst = 25, fuel = 15, engine = 30, stress = 70 },
```

* `hide` – the element hides while the value is at or above this value (stress: below).
* `warn` – the element turns into its warning colour at this value.

### Position

```lua
position = {
    status  = { left = 1.6, bottom = 21.5 },
    money   = { right = 2.0, top = 2.0 },
    vehicle = { right = 2.0, bottom = 9.0 },
},
```

### Indicators

```lua
indicators = { enabled = true, leftKey = 'LEFT', rightKey = 'RIGHT' },
```

Default keys for new players; each player can rebind them in the FiveM key bindings.

### Update rates and sources

```lua
tick     = { foot = 250, vehicle = 150 },
status   = { source = 'auto', hungerKey = 'hunger', thirstKey = 'thirst', interval = 2000 },
voice    = { bag = 'proximity', showFor = 3000 },
money    = { interval = 5000, black = false },
seatbelt = { provider = 'cc_fuel', readFlag = true },
```

### Look (`config/ui.lua`)

```lua
Config.UI = { theme = 'default', primary = '#8B5CF6', radius = 'md', scale = 1.0, locale = 'de', animations = true, blur = false, sounds = true }
```

Set `locale = 'en'` for English texts (`locales/en.json`).

## Exports, Events & Commands

### Commands and keys

| Command / key                                                           | Effect                  | Who      |
| ----------------------------------------------------------------------- | ----------------------- | -------- |
| `/hud`                                                                  | toggle HUD              | everyone |
| `/hud on` · `/hud off`                                                  | force on/off            | everyone |
| `/hud kmh` · `/hud mph`                                                 | speed unit              | everyone |
| `/hudreset`                                                             | back to server defaults | everyone |
| Arrow left / right (`cc_hud_indicator_left` / `cc_hud_indicator_right`) | indicators              | driver   |

### Exports

None.

### Events

| Event             | Side   | Direction | Payload                                    |
| ----------------- | ------ | --------- | ------------------------------------------ |
| `cc_hud:seatbelt` | client | incoming  | `bool` – from third-party seatbelt scripts |
| `cc:moneyChanged` | server | incoming  | `src` – refreshes the money display        |

```lua
TriggerEvent('cc_hud:seatbelt', true)
```

### State bags

* Sets `Entity(veh).state.cc_indicators = { left, right }` (server only).
* Reads `ccStatus`, `hunger`, `thirst`, `proximity`.

## FAQ & Troubleshooting

**Hunger and thirst rings are missing.** They hide above 80 % by default (`Config.Hud.hide`). If they never appear: on QBCore/QBox without cc\_status/00%20Overview\.md), hunger/thirst live in metadata and must be mirrored to the `hunger`/`thirst` state bags.

**The stress ring never shows.** Stress is only available with cc\_status and appears from 20 %.

**No fuel gauge or seatbelt icon.** These come from cc\_fuel/00%20Overview\.md). Other seatbelt scripts can trigger `cc_hud:seatbelt`.

**No voice range ring.** Requires pma-voice; it only shows while talking.

**Black money is not shown.** Not supported – the bridge only knows `cash` and `bank`.

**The job name looks wrong.** The label is derived from the internal job name (`police` → `Police`).

**Players changed settings and want the defaults back.** `/hudreset` restores the server defaults from `config/config.lua`.

**Why no blurred glass background?** CSS `backdrop-filter` is disabled on purpose – it draws black rectangles on some FiveM builds.

**Is there a cruise control display?** No.

Still stuck? See Support.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ccfivem.gitbook.io/ccfivem-docs/player-and-ui/hud-cc_hud.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.