> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revoscripts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Commands, key bindings, the in-game menus and the built-in nitrous system, for players and staff.

This page is a guide to using Revo HUD in game. You can share it with your players.

## Commands

| Command | What it does |
| - | - |
| `/hud` | Opens the settings menu: themes, colors, styles, presets and what to show. |
| `/onboard` | Runs the short setup wizard again (look, accent color, map shape, status bars). |
| `/vehcontrols` | Opens the vehicle control panel (same as **F7**). |
| `/gearbox` | Switches the manual gearbox on or off. |
| `/bigmap` | Toggles the expanded minimap. |
| `/cinematic` | Toggles cinematic black bars with the HUD hidden. |
| `/hudmenu` | Another way to open `/hud`. |

> [!NOTE]
>
> Every command name can be changed in `config.lua`. The names above are the defaults.

## Key Bindings

| Key | Action |
| - | - |
| **F7** | Vehicle control panel |
| **B** | Seatbelt |
| **G** | Engine on or off |
| **Left Shift** (hold) | Nitrous boost, on cars with a kit |
| **Left Ctrl** (hold) | Nitrous purge |
| **Page Up** | Nitrous flow: stage 1, 2, 3 |
| **E** / **Q** | Shift up or down in manual (`/gearbox` switches manual on) |
| **N** | Boat anchor |

These are defaults. Players can change them in **Settings > Key Bindings > FiveM**, and the HUD's hint panel always shows the key they picked. In **/hud > Keybinds** there is an **Open FiveM Key Bindings** button that jumps straight to that page.

> [!NOTE]
>
> Cruise control and the manual gearbox toggle have no key by default. Set `Config.VehicleControls.cruiseControl.key` or `Config.ManualTransmission.toggleKey` in `config.lua` to give them one, or use the vehicle panel.

## The Settings Menu (/hud)

The menu is split into four sections:

| Section | Pages |
| - | - |
| **Setup** | General, Presets |
| **Interface** | Status Bars, Player Info, Minimap & Compass, Weapon HUD |
| **Vehicles** | Car, Aircraft, Boat, Bicycle, Train |
| **Extras** | Notifications, Crosshair, Speed Limit Sign, Keybinds |

* Every page opens with **Show** switches, so any element can be hidden in one click.
* Each element has a **Colors & Glow** drawer for its colors, glow and shadow, with a live preview.
* Style choices use real live previews of each component.
* **Edit Layout** and **Reset Defaults** sit at the bottom of the menu. **Reset Defaults** puts back the look your server set.

### Themes and Colors

Pick from nine themes: Revo Cyan, Blue, Ultraviolet, Vice, Red, Ember, Toxic, Emerald and White. Choose **Custom** to pick any color and the HUD builds a matching palette around it.

Turn off **Single Colour Mode** to set colors per element, then add glow and shadow to taste. Six fonts are available. Cash, bank and warning colors stay readable on every theme.

### Styles

Most parts of the HUD come in several complete styles. A style redraws the layout itself, and you can mix them however you like:

| Part | Styles |
| - | - |
| Player info, weapon HUD, street name, notifications, key hints | Sleek, Blocks, Chamfered, Aurora |
| Compass | Sleek, Blocks, Chamfered, Aurora, Simple |
| Status bars | Circle, Square, Hexagon, Diamond, Aurora, Minimal, Dot Matrix, Liquid Neon, Text Only, Rail, Blade, Gauge, Capsule, Meter |
| Car speedometer | Modern, Analogue, Neon Arc, Tactical, Minimal, Grid, Horizon, Column, Pulse, Matrix, Orbit, Crescent, Duet, Shard, Visor |
| Aircraft | Instrument Panel, Glass Cockpit, Compact Strip |
| Boat | Helm, Compact Strip |
| Bicycle | Computer, Minimal Strip |
| Train | Rail, Cab Dial |
| Speed limit sign | US, EU, AU, Minimal |
| Crosshair | 7 shapes |

**Aurora** is real frosted glass, which blurs the live game behind it.

### Presets

The **Presets** tab holds 17 ready-made HUDs and your own saved setups.

* **Try on** a preset live before keeping it.
* **Save this setup** to keep your own look as a preset.
* **Generate & Copy Share Code** turns your setup into a `REVO1-...` code, and **Import** loads a code from a friend, a server, or revoscripts.com.

## Edit Layout

**Edit Layout** turns the whole screen into a canvas.

* **Drag** any element to move it and **resize** it, or **hide** it.
* **Snap to grid**, **smart snapping** to neighbors and a **screen-edge guide** help you line things up.
* **Undo** and **Redo** step through your changes.
* **Right-click** an element for its options, including **3D tilt**, which turns panels to face the driver the way racing games angle theirs.
* **Safe Area** keeps the HUD grouped on ultrawide screens.

Positions scale by screen height, so a layout built on 1080p keeps its proportions on 1440p and 4K.

> [!NOTE]
>
> If you lock layout editing in `config.lua`, players cannot enter Edit Layout. Staff with the `revo_hud.admin` ACE can still edit.

## Vehicle Control Panel

Press **F7** (or type `/vehcontrols`) while in a vehicle.

> **Controls**
>
> A top-down car you can click: doors, hood, trunk, windows, roof, engine, handbrake, indicators, headlights, seatbelt and harness, cruise control, speed limiter and manual gearbox. Aircraft get landing gear and boats get an anchor. Vehicle extras, livery and moving to a free seat are included. Controls a vehicle does not have stay hidden.

> **Lights page**
>
> * **Underglow** in 12 colors or any color you pick, with six effects (Steady, Breathe, Pulse, RGB, RGB chase and Flash) at three speeds, and a choice of which sides glow.
> * **13 headlight colors.** These fit xenons for free.
> * **Cabin light.**
>
> Nearby players see all of it, effects included. You can require a neon kit for underglow with `Config.VehicleControls.ambience.requireNeonKit`.

> **Media tab**
>
> Paste a YouTube link and queue videos or whole playlists. Everyone in the car hears the same thing at the same moment, quieter with distance and muffled with the windows shut. You choose who controls it, and anyone can mute it for themselves. **Requires OneSync.**

> **Places tab**
>
> Save up to 20 named spots per player and set the GPS to one with a click. Your server can also add shared places that cannot be deleted.

## Driving Features

* **Seatbelt:** Press **B** to buckle. An unbelted driver gets reminders, and above `ejectSpeed` can go through the windscreen. A belt or a harness softens every crash.
* **Manual gearbox:** Type `/gearbox`, then shift with **E** and **Q**. Every gear tops out at a realistic speed, and holding the brake in a forward gear stops the car without reversing.
* **Cruise control and speed limiter:** Set from the vehicle panel. Cruise engages from 30 km/h by default. The cluster shows when the handbrake, cruise, limiter, harness or nitrous is engaged.
* **Drift counter:** A dial with a little car that turns with your slide shows your score, slide angle and a combo multiplier up to x5. Your best run is saved per character.
* **Nitrous:** See [Nitrous](#nitrous) below.
* **Speed limit sign:** Shows the limit for the area you are in, and warns when you go over.

## Nitrous

Nitrous is **built into Revo HUD**: kits, bottles, boost, purge and the gauge, with nothing else to install. It works the way players know it from the big mechanic scripts. All settings are in `Config.Nitro`, see [Configuration](/products/hud/configuration#nitrous).

### How It Works

* A car needs a **nitrous kit**. A player uses the kit item standing next to the car (bonnet up, about 8 seconds). It comes with a full bottle.
* **Hold Left Shift** to boost: more power, exhaust flames and tail-light trails. Everyone nearby sees the flames, trails and purge.
* **Page Up** steps the flow through three stages. Each stage pulls harder and empties the bottle sooner.
* Hold the boost too long and it **overheats**: a short lockout and some engine damage (`overheatDamage`, set it to `0` for none).
* **Hold Left Ctrl** to **purge**: nitrous vents out of the front of the car. It cools an overheated system three times faster.
* An empty bottle is swapped for a full one with the **bottle item**.

Kits and bottle levels are kept **by plate**, so they stay with the car across restarts and whoever drives it. When `ox_lib` is running, fitting uses its progress bar.

Keys are defaults and each player can rebind them in FiveM's key settings.

### How Cars Get a Kit

Choose with `Config.Nitro.fitting`:

| Value | Behavior |
| - | - |
| `'item'` | Players fit a kit with the `nitrous_kit` item. |
| `'all'` | Every car comes with a kit. No items needed. |
| `'export'` | Only your own scripts fit kits, using the [server exports](/products/hud/exports#nitrous-server). |

### How Bottles Refill

Choose with `Config.Nitro.refill`:

| Value | Behavior |
| - | - |
| `'item'` | The `nitrous_bottle` item swaps in a full bottle. |
| `'recharge'` | The bottle refills by itself a few seconds after use. |

> [!NOTE]
>
> If you set `fitting = 'all'` and `refill = 'recharge'`, you do not need to add any items at all.

### Add the Items

The HUD makes both items usable on its own. They just have to exist in your inventory. The item names can be changed with `kitItem` and `bottleItem` in `Config.Nitro`.

**ox\_inventory**

Open `ox_inventory/data/items.lua` and add (works with any framework):

```lua theme={null}
['nitrous_kit'] = { label = 'Nitrous kit', weight = 5000, stack = false, close = true, description = 'Fits a nitrous system to a car.' },
['nitrous_bottle'] = { label = 'Nitrous bottle', weight = 3000, close = true, description = 'A full bottle of nitrous.' },
```

> [!NOTE]
>
> On a server with **no framework**, add `server = { export = 'revo_hud.nitrous_kit' }` to the kit, and `server = { export = 'revo_hud.nitrous_bottle' }` to the bottle.

**QBCore (qb-inventory)**

Open `qb-core/shared/items.lua` and add:

```lua theme={null}
nitrous_kit    = { name = 'nitrous_kit', label = 'Nitrous kit', weight = 5000, type = 'item', image = 'nitrous_kit.png', unique = true, useable = true, shouldClose = true, description = 'Fits a nitrous system to a car.' },
nitrous_bottle = { name = 'nitrous_bottle', label = 'Nitrous bottle', weight = 3000, type = 'item', image = 'nitrous_bottle.png', unique = false, useable = true, shouldClose = true, description = 'A full bottle of nitrous.' },
```

Add your own `nitrous_kit.png` and `nitrous_bottle.png` images to your inventory's images folder.

**ESX (default inventory)**

Run this once in your database:

```sql theme={null}
INSERT INTO items (name, label, weight) VALUES ('nitrous_kit', 'Nitrous kit', 5), ('nitrous_bottle', 'Nitrous bottle', 3);
```

Then sell or craft the items however your server does: a shop, a mechanic job or a crafting bench.

> [!TIP]
>
> Restart your inventory after adding the items, then restart `revo_hud`. If nobody can fit nitrous, turn on `Config.Debug` and check the server console. It says whether the items were registered.

### Limit Who Can Use It

Nitrous takes the standard `audience` list, so you can limit it by job, vehicle class or model:

```lua theme={null}
Config.Nitro.audience = {
    exceptClasses = { 'motorcycles', 'cycles', 'boats', 'helicopters', 'planes', 'trains' },
    jobs          = { 'mechanic', 'racer' },   -- who may fit and use it
    exceptModels  = {},
}
```

Electric cars have no bottle to fit, so they get no gauge and no boost unless `allowElectric = true`.

### Using Another Nitrous Script

If you already run a different nitrous script, set `Config.Nitro.driveBoost = false`. The HUD then only shows the gauge, and your script feeds it:

```lua theme={null}
exports['revo_hud']:setNitro(75, false)   -- level 0-100, boosting
```

See [Exports](/products/hud/exports#nitrous-client).

### Tuning

| Option | Effect |
| - | - |
| `drainRate` | How fast the bottle empties while boosting (percent per second, stage 1). |
| `maxBurnTime` | Milliseconds of continuous boost before it overheats. `0` means never. |
| `cooldown` | Milliseconds locked out after an overheat. |
| `overheatDamage` | Engine damage on overheat. `0` for none. |
| `purgeDrain` | How fast a purge empties the bottle. |
| `rechargeRate`, `rechargeDelay` | How quickly the bottle refills with `refill = 'recharge'`. |
| `fitTime`, `refillTime` | How long fitting a kit or swapping a bottle takes. |
| `exhaustFlames`, `lightTrails`, `purgeSmoke`, `purgeColour` | The visual effects other players see. |
| `motionBlur`, `cameraShake`, `colorEffect` | What the driver's screen does while boosting. |

## Staff Commands

Staff with the `revo_hud.admin` ACE can use:

```bash theme={null}
/revohudadmin <id> <on|off>
```

This forces a player's HUD on or off. Staff can also still edit the HUD when you have locked editing for players.

> [!NOTE]
>
> `/revohudadmin` is a restricted command. It always works from the server console. To use it in game, staff need the `revo_hud.admin` ACE and FiveM's own command permission, for example `add_ace group.admin command.revohudadmin allow`.

> [!TIP]
>
> New to the HUD? Open `/hud`, go to **Presets**, and try a few on live. Then use **Edit Layout** to fine-tune the one you like.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.