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

# Configuration

Every setting in shared/config.lua — what it does, and what you can set it to.

One file: `shared/config.lua`. Edit it, restart the resource, done.

{% hint style="success" %}
**The five lines most servers change**

```lua
DashCfg.locale = 'en'
DashCfg.currency = '$'
DashCfg.units = { speed = 'kmh', distance = 'm' }
DashCfg.logo = 'logo.png'
DashCfg.theme.accent = DashUI.cyan
```

{% endhint %}

## Language and money

```lua
DashCfg.locale = 'en'
DashCfg.currency = '$'
```

| Setting    | What it does                      | Values                                       |
| ---------- | --------------------------------- | -------------------------------------------- |
| `locale`   | Language for every word on screen | Any file name in `locale/` — 30 ship with it |
| `currency` | Symbol in front of cash and bank  | Any text: `$`, `€`, `£`, `R$`                |

## Units

```lua
DashCfg.units = {
    speed = 'mph',
    distance = 'ft',
}
```

| Setting    | What it does                 | Values        |
| ---------- | ---------------------------- | ------------- |
| `speed`    | Speedometer reading          | `mph` · `kmh` |
| `distance` | Waypoint and postal distance | `ft` · `m`    |

{% hint style="info" %}
Pick one system and keep it consistent — `mph` with `ft`, or `kmh` with `m`. Players can switch for themselves later unless you [lock it](/devmosaic/resources/devmosaic-dm-hud/policy-and-locks.md).
{% endhint %}

## Turning features off

```lua
DashCfg.modules = {
    vitals = true,
    identity = true,
    locate = true,
    minimap = true,
    vehicle = true,
    signals = true,
    restraint = true,
    cruise = true,
    rig = true,
    armament = true,
    waypoint = true,
    stress = true,
}
```

Set one to `false` and that feature stops running entirely — no ticks, no events, no cost. **This is different from hiding it**, which only makes it invisible. See [Policy and locks](/devmosaic/resources/devmosaic-dm-hud/policy-and-locks.md).

| Module      | Turns off                                                    |
| ----------- | ------------------------------------------------------------ |
| `vitals`    | Health, armour, hunger, thirst, oxygen, stamina, stress bars |
| `identity`  | Job, gang, ID, clock, cash, bank and voice chips             |
| `locate`    | Street names, postal codes, crossing names                   |
| `minimap`   | The map and its shaping                                      |
| `vehicle`   | Speedometer and all vehicle panels                           |
| `signals`   | Indicators and hazards                                       |
| `restraint` | Seatbelt, and being thrown through the windscreen            |
| `cruise`    | Cruise control                                               |
| `rig`       | The vehicle control panel                                    |
| `armament`  | The ammo counter                                             |
| `waypoint`  | Distance-to-waypoint chip                                    |
| `stress`    | Stress gain and the screen blur                              |

{% hint style="warning" %}
Turning off `restraint` also removes the eject-through-the-windscreen crash effect, not just the seatbelt icon.
{% endhint %}

## Keys

```lua
DashCfg.keys = {
    panel = 'F7',
    rig = 'F6',
    belt = 'B',
    cruise = 'J',
    signalLeft = 'LEFT',
    signalRight = 'RIGHT',
    hazards = 'UP',
}
```

| Key                          | Opens or toggles          | Default          |
| ---------------------------- | ------------------------- | ---------------- |
| `panel`                      | The settings menu         | `F7`             |
| `rig`                        | The vehicle control panel | `F6`             |
| `belt`                       | Seatbelt                  | `B`              |
| `cruise`                     | Cruise control            | `J`              |
| `signalLeft` / `signalRight` | Indicators                | `LEFT` / `RIGHT` |
| `hazards`                    | Hazard lights             | `UP`             |

Set any of them to `false` to leave it unbound. Do this when another script already owns that key.

```lua
cruise = false,
```

Players rebind these themselves in **GTA Settings → Key Bindings → FiveM**.

## Minimap

```lua
DashCfg.minimap = {
    shape = 'square',
    onFoot = true,
    inVehicle = true,
    northBlip = false,
    zoom = 1100,
    hideSatnav = true,
    lift = -3.5,
    ignoreSafeZone = true,
}
```

| Setting          | What it does                                                 | Values                     |
| ---------------- | ------------------------------------------------------------ | -------------------------- |
| `shape`          | Map outline                                                  | `square` · `circle`        |
| `onFoot`         | Show the map while walking                                   | `true` · `false`           |
| `inVehicle`      | Show the map while driving                                   | `true` · `false`           |
| `northBlip`      | The small N marker                                           | `true` · `false`           |
| `zoom`           | How far out the map sits                                     | `600` close, `1600` far    |
| `hideSatnav`     | Hide GTA's own sat-nav bar                                   | `true` · `false`           |
| `lift`           | Nudge the map up or down, in vh                              | Positive up, negative down |
| `ignoreSafeZone` | Keep the map put whatever the player's safe-zone slider says | `true` · `false`           |

{% hint style="info" %}
**Leave `ignoreSafeZone` as `true`.** The layout is measured against a 100% safe zone. Setting it `false` lets each player's slider push the map — and everything anchored to it — inward.
{% endhint %}

## When each status bar appears

```lua
DashCfg.vitals = {
    health = 100,
    armour = 95,
    hunger = 90,
    thirst = 90,
    stress = 40,
    oxygen = 99,
    stamina = 95,
}
```

**A bar appears once the value drops below the number.** Armour at `95` means the armour bar stays hidden until armour falls under 95.

| Value | Result                         |
| ----- | ------------------------------ |
| `100` | Always on screen               |
| `95`  | Appears once it drops below 95 |
| `0`   | Never appears                  |

Stress works the other way round: it appears once stress climbs *above* `40`.

## Vehicles

```lua
DashCfg.vehicle = {
    beltWarnAbove = 20,
    ejectAbove = 45,
    ejectRagdoll = 3,
    cruiseMinSpeed = 20,
}
```

| Setting          | What it does                                                  | Unit    |
| ---------------- | ------------------------------------------------------------- | ------- |
| `beltWarnAbove`  | Speed at which the unbuckled reminder starts                  | km/h    |
| `ejectAbove`     | Crash speed that throws an unbuckled driver through the glass | mph     |
| `ejectRagdoll`   | How long they lie on the ground afterwards                    | seconds |
| `cruiseMinSpeed` | Slowest speed cruise control will engage at                   | km/h    |

{% hint style="warning" %}
`ejectAbove` is in **mph** while the other two speeds are in **km/h**. That is the unit each one genuinely uses.
{% endhint %}

## Ammo counter

```lua
DashCfg.weapon = {
    lowCount = 6,
    lowPercent = 15,
    hideUnarmed = true,
    hideInVehicle = false,
    hideWhenEmpty = false,
    hideVanilla = true,
    iconOverrides = {},
}
```

| Setting         | What it does                          | Values           |
| --------------- | ------------------------------------- | ---------------- |
| `lowCount`      | Warn at this many rounds left         | A number         |
| `lowPercent`    | Warn at this share of a full magazine | A percentage     |
| `hideUnarmed`   | Hide the panel with fists out         | `true` · `false` |
| `hideInVehicle` | Hide it while driving                 | `true` · `false` |
| `hideWhenEmpty` | Hide it at zero rounds                | `true` · `false` |
| `hideVanilla`   | Hide it for melee and thrown weapons  | `true` · `false` |

**The warning trips on whichever comes first.** With the defaults, a pistol warns at 6 rounds and a 100-round MG warns at 15.

Force one weapon's icon:

```lua
iconOverrides = {
    ['WEAPON_MICROSMG'] = 'short',
},
```

## Stress

```lua
DashCfg.stress = {
    enabled = true,
    shootChance = 10,
    speedUnbuckled = 50,
    speedBuckled = 1000,
    blurAbove = 50,
    disableForLEO = false,
    whitelistedJobs = { 'police', 'police2' },
    whitelistedWeapons = { 'WEAPON_PETROLCAN' },
}
```

| Setting              | What it does                                    | Values           |
| -------------------- | ----------------------------------------------- | ---------------- |
| `enabled`            | Whether the HUD generates stress at all         | `true` · `false` |
| `shootChance`        | Chance of gaining stress per shot               | `0` to `100`     |
| `speedUnbuckled`     | Speed above which driving unbuckled adds stress | km/h             |
| `speedBuckled`       | Same, but buckled. `1000` means never           | km/h             |
| `blurAbove`          | Stress level where the screen starts blurring   | `0` to `100`     |
| `disableForLEO`      | Police never gain stress                        | `true` · `false` |
| `whitelistedJobs`    | These jobs never gain stress                    | Job names        |
| `whitelistedWeapons` | These weapons never add stress                  | Weapon names     |

{% hint style="info" %}
**Already running a stress script?** Set `enabled = false`. The HUD keeps drawing the stress bar — it just stops generating the value. Feed it yours with a [provider](#handing-a-feature-to-your-own-script).
{% endhint %}

## Vehicle control panel

```lua
DashCfg.rig = {
    allowPassengers = false,
    dimScreen = true,
}
```

| Setting           | What it does                                       | Values           |
| ----------------- | -------------------------------------------------- | ---------------- |
| `allowPassengers` | Let passengers open the panel, not just the driver | `true` · `false` |
| `dimScreen`       | Darken the game behind the panel                   | `true` · `false` |

Passengers who are allowed in get doors, windows and seats. Engine, locks and lights stay greyed out — those belong to the driver.

## Speed limit signs

```lua
DashCfg.zones = {
    ['Great Ocean Hwy'] = 80,
    ['Del Perro Fwy'] = 70,
    ['Vinewood Blvd'] = 35,
}
```

Street name on the left, limit on the right. **A street you do not list shows no sign at all.**

Write the name either way — `Palomino Fwy` and `Palomino Freeway` both match.

{% hint style="success" %}
**Finding street names the easy way:** set `DashCfg.debug = true`, drive around, and every street prints to the F8 console as you enter it. Copy the names straight in, then set debug back to `false`.
{% endhint %}

## Logo

```lua
DashCfg.logo = 'logo.png'
```

Any file in `media/`. Animated `.gif` and `.webp` both work.

{% hint style="warning" %}
An animated logo repaints every frame for every player. Keep it small, or use a still image.
{% endhint %}

## Colours

```lua
DashCfg.theme = {
    accent = DashUI.lime,
    surface = 'rgba(10,10,11,.86)',
    backdrop = 'rgba(0,0,0,.58)',
    cut = 10,
}
```

| Setting    | What it does                                                    |
| ---------- | --------------------------------------------------------------- |
| `accent`   | The colour of nearly everything. 100 presets in `shared/ui.lua` |
| `surface`  | Panel background                                                |
| `backdrop` | The dim behind an open panel                                    |
| `cut`      | Size of the clipped corner on panels, in pixels                 |

Full details on the [Colours and theme](/devmosaic/resources/devmosaic-dm-hud/ui-theme.md) page.

## Handing a feature to your own script

Already run a seatbelt, stress or cruise script? Point the HUD at it. **The HUD still draws the element — it just asks you for the value instead of working it out itself.**

```lua
DashCfg.providers = {
    seatbelt = {
        get = function() return exports['my-seatbelt']:IsBuckled() end,
        toggle = function() exports['my-seatbelt']:Toggle() end,
    },

    stress = {
        get = function() return exports['my-stress']:GetStress() end,
    },

    cruise = {
        get = function() return exports['my-cruise']:IsActive() end,
        toggle = function() exports['my-cruise']:Toggle() end,
    },
}
```

| Provider   | `get` returns          | `toggle` does          |
| ---------- | ---------------------- | ---------------------- |
| `seatbelt` | `true` when buckled    | Buckles and unbuckles  |
| `stress`   | A number, `0` to `100` | Not used               |
| `cruise`   | `true` when engaged    | Engages and disengages |

Leave a provider out to keep the built-in one.

## Your own bars and chips

```lua
DashCfg.extras = {
    vitals = {},
    chips = {},
}
```

See [Adding your own](/devmosaic/resources/devmosaic-dm-hud/extending.md) for the walkthrough.

## Locked settings

```lua
DashCfg.locked = {}
```

A shortcut into the same system as `shared/policy.lua`. See [Policy and locks](/devmosaic/resources/devmosaic-dm-hud/policy-and-locks.md).

## Layer order

```lua
DashCfg.nuiZIndex = 0
```

| Value           | Result                                           |
| --------------- | ------------------------------------------------ |
| `0`             | HUD sits under other scripts' menus. Recommended |
| A higher number | HUD draws over them                              |
| `false`         | Leave the layer alone entirely                   |

## Debug

```lua
DashCfg.debug = false
```

Prints street names, framework detection and provider results to the F8 console.

{% hint style="danger" %}
Ship with `false`. Debug output runs constantly and every player sees it in their own console.
{% endhint %}