> 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/configuration.md).

# Configuration

All main configuration lives in:

```
config/config.lua
config/stress_config.lua
config/mileage_config.lua
```

These files are open in escrow builds.

***

## General

| Option                       | Type    | Default     | Description                                 |
| ---------------------------- | ------- | ----------- | ------------------------------------------- |
| `Config.Debug`               | boolean | `false`     | Enables debug prints                        |
| `Config.Framework`           | string  | `auto`      | `auto`, `ESX`, `QBCore`, `Qbox`, or `none`  |
| `Config.FuelSystem`          | string  | `auto`      | Fuel integration mode                       |
| `Config.Currency`            | string  | `$`         | Currency symbol used in the server info HUD |
| `Config.SpeedUnit`           | string  | `kph`       | `kph` or `mph`                              |
| `Config.OpenSettingsCommand` | string  | `hud`       | Command to open HUD settings                |
| `Config.ToggleHudCommand`    | string  | `togglehud` | Command to show/hide HUD                    |

Supported fuel values:

```
auto, LegacyFuel, lc_fuel, ps-fuel, lj-fuel, cdn-fuel, ox_fuel, Renewed-Fuel, rcore_fuel, none
```

***

## HUD Settings Menu

```lua
Config.HudSettings = {
  enabled = true,
  allow = {
    editLayout = true,
    restoreDefaults = true,
    theme = true,
    carHudStyle = true,
    perspective3d = true,
    moduleVisibility = true,
    serverInfoParts = true,
    statusModes = true
  }
}
```

| Option             | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `editLayout`       | Allows drag and scale layout editor                  |
| `restoreDefaults`  | Allows restoring default settings                    |
| `theme`            | Allows color theme changes                           |
| `carHudStyle`      | Allows switching car HUD designs                     |
| `perspective3d`    | Allows 3D angle controls                             |
| `moduleVisibility` | Allows hiding HUD modules                            |
| `serverInfoParts`  | Allows hiding time, ping, or job                     |
| `radioHud`         | Allows players to show/hide the radio HUD            |
| `statusModes`      | Allows food/water/stress visibility behavior changes |

***

## Update Intervals

| Option                   | Default | Description                             |
| ------------------------ | ------- | --------------------------------------- |
| `Config.PlayerUpdateMs`  | `500`   | Player data update interval             |
| `Config.VehicleUpdateMs` | `100`   | Vehicle data update interval            |
| `Config.TalkingUpdateMs` | `150`   | Voice talking update interval           |
| `Config.UpdateRadarZoom` | `true`  | Reapply radar zoom while HUD is running |

Lower values feel more responsive but cost more client time.

***

## Minimap

```lua
Config.Minimap = {
  enabled = true,
  showOnFoot = false,
  style = "rounded",
  radarZoom = 1100,
  verticalOffset = -0.025
}
```

| Option           | Description                                               |
| ---------------- | --------------------------------------------------------- |
| `enabled`        | Enables custom minimap/radar display                      |
| `showOnFoot`     | Shows minimap while not in a vehicle                      |
| `style`          | Minimap style, currently shipped as rounded/custom assets |
| `radarZoom`      | Radar zoom level                                          |
| `verticalOffset` | Fine-tunes minimap vertical placement                     |

***

## Seatbelt

```lua
Config.Seatbelt = {
  enabled = true,
  key = "B",
  preventExit = true,
  driverOnly = false,
  disableInEmergency = false,
  ejectSpeedOffMph = 20.0,
  ejectSpeedOnMph = 500.0
}
```

| Option               | Description                                |
| -------------------- | ------------------------------------------ |
| `enabled`            | Enables seatbelt system                    |
| `key`                | Default keybind                            |
| `preventExit`        | Blocks exiting vehicle when seatbelt is on |
| `driverOnly`         | Restricts seatbelt logic to driver seat    |
| `disableInEmergency` | Disables system for emergency vehicles     |
| `ejectSpeedOffMph`   | Crash/ejection threshold without seatbelt  |
| `ejectSpeedOnMph`    | Crash/ejection threshold with seatbelt     |

***

## Cruise Control

```lua
Config.CruiseControl = {
  enabled = true,
  key = "J",
  minSpeedMph = 10.0
}
```

| Option        | Description                             |
| ------------- | --------------------------------------- |
| `enabled`     | Enables cruise control                  |
| `key`         | Default keybind                         |
| `minSpeedMph` | Minimum speed required to enable cruise |

***

## Vehicle Controls

```lua
Config.VehicleControl = {
  enabled = true,
  key = "M"
}
```

The vehicle controls menu can handle engine, headlights, seatbelt, cruise, doors, windows, hood, trunk, and seats.

***

## Radio HUD

```lua
Config.RadioHud = {
  enabled = true
}
```

| Option    | Description                                               |
| --------- | --------------------------------------------------------- |
| `enabled` | Globally enables or disables the radio UI for all players |

Player-level radio visibility is controlled by:

```lua
Config.DefaultSettings.radioOn = true
Config.HudSettings.allow.radioHud = true
```

If `Config.RadioHud.enabled = false`, the radio UI is fully disabled and players will not see the toggle in `/hud`.

If `Config.HudSettings.allow.radioHud = false`, the radio UI can still be enabled by default, but players cannot change it from the HUD settings menu.

***

## Weapon Durability

Weapon durability does not require a separate config option.

zloma\_hud automatically tries to read durability from supported inventory metadata:

| Inventory      | Source                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------- |
| `ox_inventory` | `exports.ox_inventory:getCurrentWeapon().metadata.durability`                                 |
| `qb-inventory` | QBCore item `info.quality`, `info.durability`, `metadata.durability`, or matching item fields |

The weapon HUD bar under the weapon name becomes a durability bar when a value is available.

If no supported metadata exists, the bar remains a simple theme accent.

***

## Default HUD Layout

`Config.DefaultSettings` controls first-start/default user layout.

```lua
layout = {
  compass = { x = 0, y = 0, scale = 1.30 },
  serverInfo = { x = 0, y = 35, scale = 1.0 },
  health = { x = 0, y = -10, scale = 1.15 },
  speedometer = { x = 0, y = 0, scale = 1.25 }
}
```

Each layout entry supports:

| Field   | Description                                       |
| ------- | ------------------------------------------------- |
| `x`     | Horizontal offset                                 |
| `y`     | Vertical offset                                   |
| `scale` | Base UI scale before automatic resolution scaling |

The frontend also applies automatic resolution-aware scaling. For example:

| Resolution  | Auto Scale   |
| ----------- | ------------ |
| `2560x1440` | `1.00`       |
| `1920x1080` | `0.90`       |
| `1680x1050` | About `0.87` |
| `1280x720`  | `0.55`       |

***

## Stress System

Enable or disable built-in stress:

```lua
Config.StressSystem = {
  enabled = true,
  useCustomStress = false
}
```

Main stress options are in `config/stress_config.lua`.

### Persistence

| Option           | Default            | Description                       |
| ---------------- | ------------------ | --------------------------------- |
| `enabled`        | `true`             | Save stress to database           |
| `autoRunSql`     | `true`             | Create stress table automatically |
| `table`          | `zloma_hud_stress` | Stress table name                 |
| `saveIntervalMs` | `60000`            | Autosave interval                 |
| `saveOnDrop`     | `true`             | Save when player disconnects      |
| `loadOnJoin`     | `true`             | Load stress on join               |

### Stress Gain

Stress can be gained from:

* speeding
* shooting

Both systems can be enabled/disabled and configured in `Config.StressConfig.gain`.

### Effects

Stress effects can include:

* camera shake
* screen blur
* screen fade
* ragdoll at max stress

Configured in `Config.StressConfig.effects`.

### Items

Stress tablet item names:

| Type   | Item                   |
| ------ | ---------------------- |
| Light  | `stress_tablet_light`  |
| Medium | `stress_tablet_medium` |
| Hard   | `stress_tablet_hard`   |

Tablet box item names:

| Type       | Item                       |
| ---------- | -------------------------- |
| Light Box  | `stress_tablet_box_light`  |
| Medium Box | `stress_tablet_box_medium` |
| Hard Box   | `stress_tablet_box_hard`   |

These require `ox_inventory` or `qb-inventory` item setup. See [Installation](/zloma-scripts/zloma_hud-free-escrow/installation.md#step-5---install-stress-items) for ready-to-use item definitions.

***

## Vehicle Mileage

Enable or disable built-in mileage:

```lua
Config.VehicleMileage = {
  enabled = true,
  useCustomMileage = false
}
```

Main mileage options are in `config/mileage_config.lua`.

| Option                  | Default      | Description                                 |
| ----------------------- | ------------ | ------------------------------------------- |
| `autoRunSql`            | `true`       | Adds `mileage` column automatically         |
| `unit`                  | `kilometers` | `kilometers` or `miles`                     |
| `updateTickMs`          | `1000`       | Client mileage update interval              |
| `serverUpdateThreshold` | `3.0`        | Distance threshold before syncing to server |
| `decimals`              | `1`          | Display decimals                            |
| `showOnHud`             | `true`       | Shows mileage in vehicle HUD                |

Ignored vehicle classes are configured in `Config.MileageConfig.ignoredVehicleClasses`.


---

# 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/configuration.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.