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

# F.A.Q

<details>

<summary>Which frameworks are supported?</summary>

QB-Core and ESX are supported. The script auto-detects the framework by checking if `es_extended` or `qb-core` is running. You can also force it manually by adding `framework = 'esx'` or `framework = 'qb'` to `shared/cfg.lua`.

</details>

<details>

<summary>What are the installation requirements?</summary>

Drop the resource into your server, ensure the folder name matches what you use in exports (e.g. `izzy-hudv5`), add `ensure izzy-hudv5` to your `server.cfg`, and make sure `baseevents` and `/assetpacks` are available — both are listed as dependencies in `fxmanifest.lua`. QB or ESX must already be running on the server.

</details>

<details>

<summary>Which files can I edit?</summary>

These files are open (not escrow-protected): `shared/cfg.lua`, `shared/utils.lua`, `shared/shared.lua`, `client/progress.lua`, `client/seatbelt.lua`, and `client/stress.lua`. The main HUD logic lives in escrow-protected files (`client.lua`, `server.lua`, and the React NUI build).

</details>

<details>

<summary>How do I open the HUD settings panel?</summary>

Use the `/hud` command by default (`cfg.settingsCommand`). From there you can change status style, speedometer, map style, colors, sizes, and more. Settings are saved per player.

</details>

<details>

<summary>How do I change the default HUD look?</summary>

Edit `cfg.defaultSettings` in `shared/cfg.lua`. You can set status type (`modern` / `classic`), status style, car HUD style, top info style, speed unit (`kmh` / `mph`), map style (`circle` / `square`), map visibility (`always` / `onlyInVehicle`), and HUD sizes. Players can also customize most options in-game via `/hud`.

</details>

<details>

<summary>How do I show or hide the HUD from another script?</summary>

Use the `setDisplay` export or trigger the client event:

From the server: `TriggerClientEvent('izzy-hudv5:client:setDisplay', source, false)`.

```lua
exports['izzy-hudv5']:setDisplay(false) -- hide
exports['izzy-hudv5']:setDisplay(true)  -- show

TriggerEvent('izzy-hudv5:client:setDisplay', false)
```

</details>

<details>

<summary>How do I send a notification from another script?</summary>

Use the `addNotification` export:

Types: `success`, `error`, `inform`. Duration is in milliseconds. Position is controlled by `cfg.notifyPosition` and colors by `cfg.notifyColors` in `shared/cfg.lua`.

You can also trigger: `TriggerEvent('izzy-hudv5:client:notification', 'success', 'Message', 5000)`.

```lua
exports['izzy-hudv5']:addNotification('success', 'Title', 'Your message here', 5000)
```

</details>

<details>

<summary>How do I replace QB-Core Notify and Progressbar?</summary>

Copy the override examples from `README.md` into your QB core file. They redirect `QBCore.Functions.Notify` and `QBCore.Functions.Progressbar` to the izzy-hudv5 exports so all QB scripts use the HUD notification and progress bar automatically.

</details>

<details>

<summary>How does the progress bar work?</summary>

Call `exports['izzy-hudv5']:Progress(action, finishCallback)` with a table containing `duration`, `label`, `description`, `canCancel`, `controlDisables`, `animation`, and optional `prop` / `propTwo`. Variants `ProgressWithStartEvent`, `ProgressWithTickEvent`, and `ProgressWithStartAndTick` add start/tick callbacks. Use `exports['izzy-hudv5']:isDoingSomething()` to check if a progress is already running — only one can run at a time.

</details>

<details>

<summary>How do I cancel an active progress bar?</summary>

Press X (default key from `cfg.cancelProgress.key`), run `/cancel`, or trigger `TriggerEvent('progressbar:client:cancel')`. The script also listens to standard `progressbar:client:*` events for qb-progressbar compatibility.

</details>

<details>

<summary>How does the stress system work?</summary>

When `cfg.useStress = true`, stress increases from speeding (different thresholds with/without seatbelt) and from shooting (based on `cfg.StressChance`). At higher stress levels, screen blur effects trigger based on `cfg.Intensity` and `cfg.EffectInterval`. LEO and ambulance jobs are whitelisted by default in `cfg.WhitelistedJobs`. Stress is stored in player metadata (QB) or synced via server events (ESX).

</details>

<details>

<summary>How do I add or remove stress manually?</summary>

Trigger these client events:

Adjust values and whitelist tables in `shared/cfg.lua` and `client/stress.lua` as needed.

```lua
TriggerEvent('izzy-hudv5:client:gainStress', 3)
TriggerEvent('izzy-hudv5:client:relieveStress', 2)
TriggerEvent('izzy-hudv5:client:setStress', 50)
```

</details>

<details>

<summary>How does the seatbelt system work?</summary>

Press B (default) or run `/toggleseatbelt` while in a vehicle. Bikes, cycles, and boats are excluded. Without a seatbelt, high-speed crashes can eject the player and cause extra damage. A warning sound plays when driving without a belt if `cfg.seatbeltWarnSound = true`. Seatbelt buckle/unbuckle sounds use InteractSound (`carbuckle`, `carunbuckle`, `beltalarm`).

There is no seatbelt export in v5 — the global variable `seatbeltOn` is used internally.

</details>

<details>

<summary>What is car mode and how do I use it?</summary>

Car mode is a v5 feature controlled by `cfg.useCarMode`. When enabled, use `/carmod` (`cfg.carModCommand`) to switch between normal and drift driving modes from the HUD car settings panel.

</details>

<details>

<summary>Which fuel scripts are supported?</summary>

Fuel level is read automatically from LegacyFuel, cdn-fuel, or ox\_fuel if those resources are started. If none are running, fuel defaults to `100`.

</details>

<details>

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

pma-voice and saltychat are supported. Mic status and voice range on the HUD update based on whichever resource is active. Voice range mappings are configured in `cfg.voiceRanges` in `shared/cfg.lua`.

</details>

<details>

<summary>How do I use the music player?</summary>

Run `/music` by default (`cfg.musicCommand`). Set `cfg.useMusicPlayer = false` to disable it. Use `/clearRadio` (`cfg.clearRadioCommand`) to clear the active radio/music.

</details>

<details>

<summary>How do I change server name, description, and top info?</summary>

Edit `cfg.serverName`, `cfg.serverDesc`, and the `cfg.topInfos` table in `shared/cfg.lua`. Top info blocks include player count, time, job, full name, cash, and bank.

</details>

<details>

<summary>How do I change the language / locale?</summary>

Set `cfg.locale` in `shared/cfg.lua` (default: `'en'`). Translations live in `cfg.locales`. Add a new locale key and copy the `'en'` table structure to translate all UI strings.

</details>

<details>

<summary>Why is my minimap border misaligned?</summary>

Adjust `cfg.minimapScale` in `shared/cfg.lua` (default: `1000`). If you use a colored/custom map, you may need to increase this value. Players can also fine-tune layout from the HUD settings panel.

</details>

<details>

<summary>What exports are available?</summary>

Client exports: `setDisplay`, `addNotification`, `Progress`, `ProgressWithStartEvent`, `ProgressWithTickEvent`, `ProgressWithStartAndTick`, and `isDoingSomething`. v5 does not include v7-style exports such as `hideHUD`, `ToggleSpeedometer`, `getSeatbeltState`, or `hudIsReady`.

</details>

<details>

<summary>What event prefix does v5 use?</summary>

All custom events use the `izzy-hudv5:` prefix (e.g. `izzy-hudv5:client:setDisplay`, `izzy-hudv5:client:gainStress`). Always match this prefix and your resource folder name in exports.

</details>

<details>

<summary>The HUD is not showing — what should I check?</summary>

Make sure the resource is started (`ensure izzy-hudv5`), QB/ESX is loaded, `baseevents` and `/assetpacks` are present, and you have not hidden the HUD with `setDisplay(false)`. Check F8 console for errors. If notifications or progress work but the HUD UI does not, verify `web/dist/` files exist and the player has fully loaded their character.

</details>

<details>

<summary>Can I disable debug mode?</summary>

Yes. Set `cfg.debug = false` in `shared/cfg.lua`. It defaults to `true` in the shipped config.

</details>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://izzyshop-1.gitbook.io/izzyshop-docs/hud-resources/hud-v5/f.a.q.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.