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

# Pepper HUD

A HUD every player sets up the way they like: with **Pepper HUD** players pick a style, choose a color and move elements – all live in-game with `/hud`. Clean, modern and clutter-free, plus a speedometer with seatbelt and cruise control.

{% hint style="info" %}
🧪 **Tested on our dev server:** Of course we test all scripts continuously on our own dev server “Pepper Scripts”.
{% endhint %}

{% hint style="success" %}
**Get Pepper HUD:** [pepper-scripts.tebex.store](https://pepper-scripts.tebex.store/)
{% endhint %}

### Features

* **3 switchable styles** – rings, bars and pills
* **In-game `/hud` menu:** style, accent color, color mode, size, opacity, toggle every element
* Drag elements anywhere with the mouse, saved per player
* Health, armor, hunger, thirst, stamina, oxygen, voice chat (pma-voice & SaltyChat) incl. radio
* Cash, bank, dirty money with plus/minus animation, job, player ID, time
* Compass with street and area, ammo display
* **Speedometer** with RPM, gear, fuel, engine health, lights and lock state (km/h or mph)
* **Seatbelt** with ejection on crashes and **cruise control**
* **Cinematic mode** and square or round minimap
* Show only when needed (e.g. armor only when you have some)
* Very lightweight – only sends changed values to the UI
* German & English, config, locales and framework bridge open

### At a glance

|                  |                                                                  |
| ---------------- | ---------------------------------------------------------------- |
| **Version**      | 1.0.0                                                            |
| **Framework**    | ESX Legacy (with esx\_status) **or** QBCore                      |
| **OneSync**      | not required                                                     |
| **Optional**     | pma-voice or SaltyChat (detected automatically), any fuel script |
| **Not required** | database, ox\_lib                                                |
| **Performance**  | approx. 0.02 ms idle / 0.05 ms in a vehicle (guide value)        |
| **Distribution** | Cfx.re Asset Escrow (`config/`, `locales/`, `bridge/` open)      |

### Installation

#### Requirements

| Requirement        | Version                                                   |
| ------------------ | --------------------------------------------------------- |
| FiveM server build | 7290+ (OneSync not required)                              |
| Framework          | ESX Legacy (hunger/thirst via `esx_status`) **or** QBCore |
| Optional           | pma-voice or SaltyChat, any fuel script                   |

No database and no ox\_lib needed.

#### Steps

{% stepper %}
{% step %}
**Download**

Download `pepper_hud` from the [Cfx.re Portal → Granted Assets](https://portal.cfx.re/assets/granted-assets).
{% endstep %}

{% step %}
**Copy**

Extract it to `resources/[pepper]/pepper_hud`.
{% endstep %}

{% step %}
**server.cfg**

Start it **after** your framework:

```cfg
ensure es_extended   # or qb-core
ensure pepper_hud
```

{% endstep %}

{% step %}
**Disable other HUDs**

Disable other HUDs such as `esx_hud`, `qb-hud` or `ps-hud` – otherwise two HUDs overlap.
{% endstep %}

{% step %}
**QBCore only**

If `qb-smallresources` uses its own seatbelt/cruise control, disable it there **or** set `Config.Seatbelt.enabled` / `Config.Cruise.enabled` to `false`.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
English texts: set `Config.Locale = 'en'` in `config/config.lua`.
{% endhint %}

### Configuration

Everything is in `config/config.lua` (open). These are **server defaults** – players can change many of them for themselves via `/hud` (saved locally on their PC, per server). New players start with `Config.Defaults`.

#### General

| Option              | Default  | Description                                                 |
| ------------------- | -------- | ----------------------------------------------------------- |
| `Config.Locale`     | `'de'`   | Language: `'de'` or `'en'` (more via `locales/<code>.json`) |
| `Config.Framework`  | `'auto'` | `'auto'`, `'esx'` or `'qbcore'`                             |
| `Config.Debug`      | `false`  | Debug output                                                |
| `Config.Voice`      | `'auto'` | `'auto'`, `'pma-voice'`, `'saltychat'` or `'none'`          |
| `Config.Clock`      | `'real'` | Clock: `'real'` (player's time) or `'game'` (game time)     |
| `Config.ServerName` | `''`     | Optional server name at the top right (empty = off)         |

#### Currency (`Config.Currency`)

| Option     | Default    | Description                               |
| ---------- | ---------- | ----------------------------------------- |
| `symbol`   | `'$'`      | Currency symbol                           |
| `position` | `'before'` | `'before'` → $1,250 · `'after'` → 1.250 $ |
| `locale`   | `'en-US'`  | Number format (e.g. `'de-DE'`)            |

#### Commands & keys

| Option                                              | Default              | Description    |
| --------------------------------------------------- | -------------------- | -------------- |
| `Config.Commands.menu`                              | `'hud'`              | Settings menu  |
| `Config.Commands.cinema`                            | `'cinema'`           | Cinematic mode |
| `Config.Commands.seatbelt` / `Config.Keys.seatbelt` | `'seatbelt'` / `'B'` | Seatbelt       |
| `Config.Commands.cruise` / `Config.Keys.cruise`     | `'cruise'` / `'Y'`   | Cruise control |
| `Config.Keys.cinema`                                | `''`                 | No default key |

#### Seatbelt (`Config.Seatbelt`)

| Option        | Default | Description                                                              |
| ------------- | ------- | ------------------------------------------------------------------------ |
| `enabled`     | `true`  | `false` if you use another seatbelt script                               |
| `ejectSpeed`  | `90`    | km/h – from this speed players without a seatbelt are ejected in a crash |
| `ejectDamage` | `20`    | Damage when ejected (`0` = none)                                         |
| `lockExit`    | `true`  | Buckled players can't exit before unbuckling                             |
| `warnSpeed`   | `20`    | km/h – the seatbelt icon flashes from here if unbuckled                  |
| `sounds`      | `true`  | Click sound when buckling                                                |

#### Cruise control & minimap

| Option                          | Default | Description                                                                         |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `Config.Cruise.enabled`         | `true`  | Cruise control on/off                                                               |
| `Config.Cruise.minSpeed`        | `30`    | km/h – minimum speed to engage                                                      |
| `Config.Minimap.managed`        | `true`  | `false` = the HUD doesn't change the minimap at all (if another script controls it) |
| `Config.Minimap.hideHealthBars` | `true`  | Hides the GTA health/armor bars below the minimap                                   |

#### Menu permissions (`Config.Menu`)

| Option        | Default | Description                  |
| ------------- | ------- | ---------------------------- |
| `enabled`     | `true`  | `/hud` menu on/off           |
| `allowStyle`  | `true`  | Players may change the style |
| `allowColors` | `true`  | Players may change colors    |
| `allowLayout` | `true`  | Players may move elements    |

#### Defaults for new players (`Config.Defaults`)

| Option                 | Default        | Description                              |
| ---------------------- | -------------- | ---------------------------------------- |
| `style`                | `'rings'`      | `'rings'`, `'bars'` or `'pills'`         |
| `accent`               | `'#e5484d'`    | Accent color (hex)                       |
| `colorMode`            | `'colored'`    | `'colored'`, `'accent'` or `'mono'`      |
| `scale`                | `1.0`          | Size 0.7–1.4                             |
| `opacity`              | `1.0`          | Opacity 0.4–1.0                          |
| `speedUnit`            | `'kmh'`        | `'kmh'` or `'mph'`                       |
| `minimapShape`         | `'square'`     | `'square'` or `'circle'`                 |
| `minimapOnlyInVehicle` | `false`        | Show the minimap only in vehicles        |
| `show`                 | all on         | Visible elements                         |
| `dynamic`              | armor, stamina | Elements shown only when needed          |
| `cinemaBars`           | `12`           | Height of the cinematic bars in % (5–20) |

#### Fuel

`Config.GetFuel` returns the fuel level (0–100). By default it reads the `fuel` state bag (ox\_fuel) or the GTA value (LegacyFuel, cdn-fuel, ps-fuel …). For other fuel scripts, adjust the return line, for example:

```lua
return exports['LegacyFuel']:GetFuel(vehicle)
```

#### Other options

| Option                  | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| `Config.Colors`         | Colors of the status displays in `colored` mode        |
| `Config.AccentPresets`  | Colors offered in the menu's color picker              |
| `Config.Intervals`      | Update intervals: on foot `250` ms, in vehicle `60` ms |
| `Config.HideDefaultHud` | GTA default HUD elements that are hidden               |

#### Custom status or money systems

The bridge files `bridge/client/esx.lua` and `bridge/client/qbcore.lua` are open. There you can connect your own status or money systems.

### Usage

#### The /hud menu

Type `/hud` to open the settings menu with a live preview.

| Setting        | Options                                  |
| -------------- | ---------------------------------------- |
| Style          | Rings, bars, pills                       |
| Accent color   | Presets or your own color                |
| Color mode     | Colored, accent, white                   |
| Size & opacity | Freely adjustable                        |
| Elements       | Toggle every element, "only when needed" |
| Vehicle        | km/h or mph, minimap square or round     |
| Sounds         | On / off                                 |

Settings are saved **per player** on their PC (per server).

#### Moving elements

In the layout mode of the menu, drag elements anywhere with the mouse. **Reset** restores the default layout.

#### What the HUD shows

| Area        | Content                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------- |
| Status      | Health, armor, hunger, thirst, stamina, oxygen (under water only), voice range, talking and radio   |
| Info        | Cash, bank, dirty money (ESX) with plus/minus animation, job + rank, player ID, time                |
| Orientation | Compass (follows the camera), street/crossing and area                                              |
| Weapon      | Ammo in magazine / reserve                                                                          |
| Speedometer | Speed, RPM, gear, fuel, engine health, lights/high beam, lock state, altitude in helicopters/planes |

#### Seatbelt

Press `B` to buckle up. Without a seatbelt you can be ejected in a crash above the configured speed; while buckled you can only exit after unbuckling. A warning icon flashes when you drive unbuckled.

#### Cruise control

Press `Y` to hold the current speed. Braking or the handbrake ends cruise control.

#### Cinematic mode

`/cinema` hides the HUD and minimap and shows black bars (height adjustable).

{% hint style="info" %}
Players can change the keys in the pause menu → Settings → Key Bindings → FiveM.
{% endhint %}

### Commands & Exports

#### Commands & keys

| Command     | Default key | Function              |
| ----------- | ----------- | --------------------- |
| `/hud`      | –           | Settings menu         |
| `/cinema`   | –           | Cinematic mode on/off |
| `/seatbelt` | `B`         | Seatbelt on/off       |
| `/cruise`   | `Y`         | Cruise control on/off |

Command names can be changed in `Config.Commands`.

#### Exports (client)

| Export             | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `setVisible(bool)` | Hide (`false`) or show (`true`) the HUD – e.g. for phone or camera |
| `isVisible()`      | Is the HUD visible?                                                |
| `isSeatbeltOn()`   | Is the seatbelt buckled?                                           |
| `isCruiseActive()` | Is cruise control active?                                          |
| `setCinema(bool)`  | Cinematic mode on/off                                              |
| `openMenu()`       | Open the `/hud` menu                                               |

Example:

```lua
exports.pepper_hud:setVisible(false)
```

#### Seatbelt state

| Source                       | Description                                           |
| ---------------------------- | ----------------------------------------------------- |
| Event `pepper_hud:seatbelt`  | Client event on every seatbelt change, parameter `on` |
| `LocalPlayer.state.seatbelt` | Current seatbelt state as a state bag                 |

### FAQ

| Problem                                  | Solution                                                                                                   |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Two HUDs on screen                       | Disable other HUDs (`esx_hud`, `qb-hud`, `ps-hud` …).                                                      |
| Two seatbelts / cruise controls (QBCore) | Disable them in `qb-smallresources` or set `Config.Seatbelt.enabled` / `Config.Cruise.enabled` to `false`. |
| Hunger/thirst stay empty (ESX)           | `esx_status` is required for hunger and thirst.                                                            |
| Fuel always shows 0 or 100               | Adjust `Config.GetFuel` for your fuel script (see **Configuration**).                                      |
| Minimap looks wrong                      | Another script controls the minimap – set `Config.Minimap.managed = false`.                                |
| Players can't change the style           | Check `Config.Menu` (`allowStyle`, `allowColors`, `allowLayout`).                                          |

<details>

<summary>Where are player settings saved?</summary>

Locally on the player's PC, per server. No database is needed.

</details>

<details>

<summary>Which voice systems are supported?</summary>

pma-voice and SaltyChat – both are detected automatically (`Config.Voice = 'auto'`).

</details>

<details>

<summary>How do I hide the HUD for my phone or camera script?</summary>

Call the client export `setVisible(false)` and `setVisible(true)` afterwards – see **Commands & Exports**.

</details>

### Changelog

#### 1.0.0 – 2026-09-27

**Initial release**

* 3 styles (rings, bars, pills)
* `/hud` menu with live preview and movable elements
* Speedometer, seatbelt, cruise control and cinematic mode
* Round or square minimap
* ESX Legacy and QBCore