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

# Usage guide

## Opening the editor

Press **F7** or type `/hud`. The **/hud tabbed menu** opens in the centre of the screen with these pages:

| Page              | What you do there                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Move elements** | Full-screen drag & drop canvas: move and resize widgets, grid and snap guides, multi-select.                                             |
| **Status icons**  | The status icon group.                                                                                                                   |
| **Vehicle**       | The vehicle widgets and icon group.                                                                                                      |
| **Minimap**       | Shape (rect / square / circle), position, size, visibility.                                                                              |
| **Style**         | Look of the HUD (shape, colors, gradient, glow, thresholds, auto-hide) and globals (theme, font, units, language, color-blind palettes). |
| **Info and text** | Information and text widgets.                                                                                                            |
| **Presets**       | Ready-made presets and your personal presets.                                                                                            |
| **Share**         | Export / import a layout code; **Server** section for admins.                                                                            |

**Esc** goes back (on Home it closes). Hold **Space** to see the HUD without the window. **Ctrl+Z / Ctrl+Y** undo and redo.

![Editor](https://1353659712-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fuk94SHXuZJLnC6a5RA5k%2Fuploads%2Fgit-blob-6c4bab3c40963ae56c15ade9c0e4748dfab24c59%2Fhud-editor.webp?alt=media)

## Profiles and groups

* Separate **on-foot** and **in-vehicle** profiles.
* Status and vehicle icons are **groups**: they drag as one block, and missing icons collapse with no gaps (default style: rings).
* The logo is a plain image; the ID shows only the number on a semi-transparent pill; compass degrees are off by default.

## Saving

The layout saves itself (on your PC as KVP, 1 second after the last change). At startup the layout is chosen with this precedence:

**KVP > DB (if `Config.DbSync`) > server default > built-in default**

With `Config.DbSync = true` your layout follows you to another PC. Layouts from v1 are migrated automatically.

## Presets and sharing

![Presets](https://1353659712-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fuk94SHXuZJLnC6a5RA5k%2Fuploads%2Fgit-blob-ee025aa4fe546148acaf8136cb7c74de7a3b6fc0%2Fhud-presets.webp?alt=media)

* 24 ready-made presets plus up to **10 personal presets** (stored as KVP).
* **Export** produces a `GHUD1.z....` code to copy.
* **Import** pastes a code. It is CRC-checked, never executed and never sent to the server until you save.

## Server layout (admins)

HUD admins (see [Commands, keybinds & permissions](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/commands-and-permissions.md)) see **/hud > Share > Server**:

* **Publish current layout** as the server layout;
* paste a `GHUD1.z....` code and **Publish code** (your own layout does not change; the server revalidates size and schema);
* **Remove server layout**.

Every publication has a version (timestamp, stored in `data/server_default.json` + `.ts`). Players who join, or are online at that moment, and have not received that version yet get it automatically: it replaces their layout **once**. Afterwards they can edit it, and their edit stays until the next publication (the publisher keeps their own). With `DbSync` the received version follows the player to other PCs. Publications and removals are written to the server log.

## Minimap

* Shapes: **rect** (vanilla), **square**, **circle**. Position and size come from the layout.
* Visibility: always / vehicle only / never.
* Native health/armor bars are hidden; the minimap is reapplied after pause, resolution and safe-zone changes.
* The border is drawn by the NUI on the effective minimap rectangle.
* Square and circle use the bundled masks (`stream/ghud_squaremap.ytd`, `stream/ghud_circlemap.ytd`). If a `.ytd` does not load within 5 seconds, the runtime texture built from the PNGs in `assets/minimap/` is used. If neither loads, the shape falls back to `rect` with a one-time console warning. Nothing to produce or regenerate.
* The expanded radar (Z key) is locked by default (`Config.Minimap.lockBigmap`).

{% hint style="warning" %}
The minimap mask replacement is global: it can conflict with other custom minimap resources.
{% endhint %}

## Vehicle features

* **Seatbelt** (`/seatbelt`, **B**): with the built-in seatbelt the exit key (F) is blocked while fastened; without the seatbelt a hard crash above `ejectKmh` can throw you out (if `ejection = true`). A warning appears above `seatbeltWarnKmh` when unfastened.
* **Cruise control** (`/cruise`) and **speed limiter** (`/limiter`).
* **Car control** (`/carcontrol`): doors, windows, engine, lights, seats.
* **Crash effect** after a severe crash (see [Configuration](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/configuration.md)).

## Modes

* **Streamer mode** (option in the editor): hides ID, cash, bank, street.
* **Cinematic mode** (`/cinematic`): black bars, HUD hidden.
* `/togglehud` shows / hides the HUD.

## Performance check

Measure in game with `resmon 1`: target on-foot idle <= 0.02 ms, in vehicle <= 0.06 ms.


---

# 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://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/usage-guide.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.
