> For the complete documentation index, see [llms.txt](https://zloma-scripts.gitbook.io/zloma-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zloma-scripts.gitbook.io/zloma-scripts/zloma_hud-free-escrow/installation.md).

# Installation

## Requirements

| Resource  | Version | Link                                              |
| --------- | ------- | ------------------------------------------------- |
| `ox_lib`  | Latest  | [GitHub](https://github.com/overextended/ox_lib)  |
| `oxmysql` | Latest  | [GitHub](https://github.com/overextended/oxmysql) |

Optional framework integrations:

| Resource      | Purpose                               |
| ------------- | ------------------------------------- |
| `es_extended` | ESX player/job/money/needs support    |
| `qb-core`     | QBCore player/job/money/needs support |
| `qbx_core`    | Qbox player/job/money/needs support   |

Optional feature integrations:

| Resource       | Purpose                                              |
| -------------- | ---------------------------------------------------- |
| `ox_inventory` | Stress tablet and tablet box items                   |
| `qb-inventory` | Stress tablet and tablet box items on QBCore servers |
| `pma-voice`    | Radio channel and radio talking indicator            |

***

## Step 1 - Place The Resource

```
resources/
  [zloma]/
    zloma_hud/
```

The resource folder must be named exactly:

```
zloma_hud
```

The script checks the resource name on startup.

***

## Step 2 - Start Order

Add this to `server.cfg`:

```cfg
ensure ox_lib
ensure oxmysql
ensure zloma_hud
```

If you use a framework, start it before `zloma_hud`:

```cfg
ensure ox_lib
ensure oxmysql
ensure es_extended
ensure zloma_hud
```

For QBCore:

```cfg
ensure ox_lib
ensure oxmysql
ensure qb-core
ensure qb-inventory
ensure zloma_hud
```

For Qbox:

```cfg
ensure ox_lib
ensure oxmysql
ensure qbx_core
ensure zloma_hud
```

***

## Step 3 - Configure Main Settings

Edit:

```
config/config.lua
```

Important first-start options:

* `Config.Framework`
* `Config.FuelSystem`
* `Config.Currency`
* `Config.SpeedUnit`
* `Config.OpenSettingsCommand`
* `Config.ToggleHudCommand`
* `Config.DefaultSettings`

Use `auto` for framework and fuel auto-detection unless you need to force a specific integration.

***

## Step 4 - Configure Stress

Edit:

```
config/stress_config.lua
```

The stress system can:

* persist stress in `zloma_hud_stress`
* gain stress from speeding and shooting
* apply blur, camera shake, fade, and ragdoll effects
* register an admin stress removal command
* support stress tablets and tablet boxes through `ox_inventory` or `qb-inventory`

If you already have another stress system, set:

```lua
Config.StressSystem.useCustomStress = true
```

Then bridge it in:

```
client/cl_customization.lua
server/sv_customization.lua
```

***

## Step 5 - Install Stress Items

Stress tablets are optional. They are only needed if you want players to reduce stress by using inventory items.

Default item names are configured in:

```
config/stress_config.lua
```

Default tablets:

| Type   | Item Name              | Default Effect         |
| ------ | ---------------------- | ---------------------- |
| Light  | `stress_tablet_light`  | Reduces stress by `15` |
| Medium | `stress_tablet_medium` | Reduces stress by `25` |
| Hard   | `stress_tablet_hard`   | Reduces stress by `35` |

Default boxes:

| Type       | Box Item                   | Gives                      |
| ---------- | -------------------------- | -------------------------- |
| Light Box  | `stress_tablet_box_light`  | `15x stress_tablet_light`  |
| Medium Box | `stress_tablet_box_medium` | `15x stress_tablet_medium` |
| Hard Box   | `stress_tablet_box_hard`   | `15x stress_tablet_hard`   |

If you change an item name in inventory, also change the matching value in `Config.StressConfig.items`.

### ox\_inventory

Add items to `ox_inventory/data/items.lua`.

```lua
["stress_tablet_light"] = {
    label = "Light Stress Tablet",
    weight = 10,
    stack = true,
    close = true,
    description = "Reduces stress slightly.",
    client = {
        export = "zloma_hud.useStressTabletLight"
    }
},

["stress_tablet_medium"] = {
    label = "Medium Stress Tablet",
    weight = 10,
    stack = true,
    close = true,
    description = "Reduces stress.",
    client = {
        export = "zloma_hud.useStressTabletMedium"
    }
},

["stress_tablet_hard"] = {
    label = "Hard Stress Tablet",
    weight = 10,
    stack = true,
    close = true,
    description = "Reduces a large amount of stress.",
    client = {
        export = "zloma_hud.useStressTabletHard"
    }
},

["stress_tablet_box_light"] = {
    label = "Light Stress Tablet Box",
    weight = 150,
    stack = true,
    close = true,
    description = "Box of light stress tablets.",
    client = {
        export = "zloma_hud.useStressTabletBoxLight"
    }
},

["stress_tablet_box_medium"] = {
    label = "Medium Stress Tablet Box",
    weight = 150,
    stack = true,
    close = true,
    description = "Box of medium stress tablets.",
    client = {
        export = "zloma_hud.useStressTabletBoxMedium"
    }
},

["stress_tablet_box_hard"] = {
    label = "Hard Stress Tablet Box",
    weight = 150,
    stack = true,
    close = true,
    description = "Box of hard stress tablets.",
    client = {
        export = "zloma_hud.useStressTabletBoxHard"
    }
},
```

For `ox_inventory`, the item export is required because ox calls the client export directly.

### qb-inventory

Add items to `qb-core/shared/items.lua`.

```lua
stress_tablet_light = {
    name = "stress_tablet_light",
    label = "Light Stress Tablet",
    weight = 10,
    type = "item",
    image = "stress_tablet_light.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = "Reduces stress slightly."
},

stress_tablet_medium = {
    name = "stress_tablet_medium",
    label = "Medium Stress Tablet",
    weight = 10,
    type = "item",
    image = "stress_tablet_medium.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = "Reduces stress."
},

stress_tablet_hard = {
    name = "stress_tablet_hard",
    label = "Hard Stress Tablet",
    weight = 10,
    type = "item",
    image = "stress_tablet_hard.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = "Reduces a large amount of stress."
},

stress_tablet_box_light = {
    name = "stress_tablet_box_light",
    label = "Light Stress Tablet Box",
    weight = 150,
    type = "item",
    image = "stress_tablet_box_light.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = "Box of light stress tablets."
},

stress_tablet_box_medium = {
    name = "stress_tablet_box_medium",
    label = "Medium Stress Tablet Box",
    weight = 150,
    type = "item",
    image = "stress_tablet_box_medium.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = "Box of medium stress tablets."
},

stress_tablet_box_hard = {
    name = "stress_tablet_box_hard",
    label = "Hard Stress Tablet Box",
    weight = 150,
    type = "item",
    image = "stress_tablet_box_hard.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = "Box of hard stress tablets."
},
```

For `qb-inventory`, zloma\_hud automatically registers the usable items on server start using `QBCore.Functions.CreateUseableItem`.

Make sure `qb-core` and `qb-inventory` start before `zloma_hud`.

### Changing Item Names

To rename a stress item:

1. Change the inventory item name.
2. Change the same name in `config/stress_config.lua`.
3. Restart the inventory resource and `zloma_hud`.

Example:

```lua
Config.StressConfig.items.tablets.light.itemName = "my_light_tablet"
Config.StressConfig.items.boxes.light.itemName = "my_light_tablet_box"
Config.StressConfig.items.boxes.light.giveItem = "my_light_tablet"
```

The `giveItem` value must match the tablet item that the box should give.

***

## Step 6 - Configure Mileage

Edit:

```
config/mileage_config.lua
```

By default, the script can auto-create a `mileage` column in your vehicle table.

Default vehicle tables:

| Framework | Table             |
| --------- | ----------------- |
| ESX       | `owned_vehicles`  |
| QBCore    | `player_vehicles` |
| Qbox      | `player_vehicles` |

If another script already handles mileage, set:

```lua
Config.VehicleMileage.useCustomMileage = true
```

Then bridge custom mileage functions in the customization files.

***

## Step 7 - Open HUD Settings In Game

Default command:

```
/hud
```

Players can edit:

* theme color
* car HUD style
* 3D perspective
* module visibility
* food/water/stress visibility modes
* layout position and scale

Default toggle command:

```
/togglehud
```

***

## Post-Install Check

After first startup, verify:

* the resource starts without name errors
* the HUD appears after player load
* `/hud` opens the settings menu
* minimap appears in the expected state
* seatbelt, cruise, vehicle controls, and speedometer update in vehicles
* stress and mileage SQL changes are created if enabled
* radio indicator appears when connected to a `pma-voice` radio channel


---

# 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:

```
GET https://zloma-scripts.gitbook.io/zloma-scripts/zloma_hud-free-escrow/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.