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

# What Players Start With

What a brand new player sees before they touch anything — and which file to edit to change it.

A new player joins and the HUD looks a certain way: lime accent, square minimap, mph, halo status bars. Those starting values live in **`shared/defaults.lua`**.

{% hint style="success" %}
**Want everyone to start with a circular map and km/h?**

`shared/config.lua`

```lua
DashCfg.units = { speed = 'kmh', distance = 'm' }
DashCfg.minimap = { shape = 'circle' }
```

That is it. Both of those are inherited by `defaults.lua` automatically.
{% endhint %}

## The one thing to understand

There are two files, and **which one you edit depends on the setting**.

<table><thead><tr><th width="220">Kind of setting</th><th>Edit this file</th></tr></thead><tbody><tr><td>Units, minimap shape, minimap zoom, on-foot and in-vehicle map, north blip, dim screen — <strong>8 settings</strong></td><td><code>shared/config.lua</code></td></tr><tr><td>Everything else — <strong>48 settings</strong></td><td><code>shared/defaults.lua</code></td></tr></tbody></table>

Why? Because those 8 already exist in `config.lua`, and `defaults.lua` simply copies them:

```lua
minimap = {
    shape = DashCfg.minimap.shape,
    zoom = DashCfg.minimap.zoom,
},
```

**Changing them in `defaults.lua` would do nothing** — the next line up in `config.lua` overwrites it. So change them where they actually live.

{% hint style="warning" %}
This is the mistake people make: they set `shape = 'circle'` in `defaults.lua`, restart, and nothing happens. Set it in `config.lua` instead.
{% endhint %}

## The 8 that live in config.lua

| Default                | Set it here                 |
| ---------------------- | --------------------------- |
| `general.speedUnit`    | `DashCfg.units.speed`       |
| `general.distanceUnit` | `DashCfg.units.distance`    |
| `minimap.shape`        | `DashCfg.minimap.shape`     |
| `minimap.onFoot`       | `DashCfg.minimap.onFoot`    |
| `minimap.inVehicle`    | `DashCfg.minimap.inVehicle` |
| `minimap.northBlip`    | `DashCfg.minimap.northBlip` |
| `minimap.zoom`         | `DashCfg.minimap.zoom`      |
| `controls.dimScreen`   | `DashCfg.rig.dimScreen`     |

## The 48 that live in defaults.lua

Everything below is edited in `shared/defaults.lua` and nowhere else.

### General

```lua
general = {
    performance = 'balanced',
    scale = 100,
    opacity = 100,
    ignoreAspectLimit = false,
    realTimeClock = false,
},
```

| Setting             | What it does                              | Values                                         |
| ------------------- | ----------------------------------------- | ---------------------------------------------- |
| `performance`       | How often the HUD updates                 | `ultra` · `balanced` · `performance` · `saver` |
| `scale`             | Overall size                              | `70` to `130`                                  |
| `opacity`           | Overall transparency                      | `30` to `100`                                  |
| `ignoreAspectLimit` | Use the full width of an ultrawide screen | `true` · `false`                               |
| `realTimeClock`     | Show real time instead of in-game time    | `true` · `false`                               |

### Compass

```lua
compass = {
    style = 'ruler',
    followsCamera = true,
    showCrossing = true,
    showPostal = true,
    onFoot = true,
},
```

| Setting         | What it does                                | Values            |
| --------------- | ------------------------------------------- | ----------------- |
| `style`         | Compass appearance                          | `ruler` · `chips` |
| `followsCamera` | Follow where the camera looks, not the body | `true` · `false`  |
| `showCrossing`  | Show the cross-street name                  | `true` · `false`  |
| `showPostal`    | Show the nearest postal code                | `true` · `false`  |
| `onFoot`        | Show the compass while walking              | `true` · `false`  |

### Status bars

```lua
vitals = {
    showLogo = true,
    logoSize = 70,
    statStyle = 'halo',
    ringSize = 46,
    ranges = { ... },
    colours = { ... },
},
```

| Setting     | What it does          | Values                                                   |
| ----------- | --------------------- | -------------------------------------------------------- |
| `showLogo`  | Show your server logo | `true` · `false`                                         |
| `logoSize`  | Logo size             | `30` to `160`                                            |
| `statStyle` | Bar appearance        | `halo` · `hex` · `badge` · `ledger` · `wave` · `pitline` |
| `ringSize`  | Bar size              | `30` to `70`                                             |

**`ranges`** decides when each bar is on screen, as `{ from, to }`:

```lua
ranges = {
    health = { 0, 100 },
    oxygen = { 0, 99 },
    stress = { 10, 100 },
    stamina = { 0, 95 },
},
```

`health = { 0, 100 }` is always visible. `oxygen = { 0, 99 }` hides at full breath. `stress = { 10, 100 }` hides until stress passes 10.

**`colours`** sets each bar's fill and icon:

```lua
colours = {
    health = { progress = '#6cd444', icon = '#c3f0ae' },
    armour = { progress = '#35a7f0', icon = '#b0dbf9' },
},
```

| Channel    | Colours                    |
| ---------- | -------------------------- |
| `progress` | The filled part of the bar |
| `icon`     | The icon on top of it      |

### Vehicles

```lua
vehicle = {
    layout = 'racing',
    bikeLayout = 'runway',
    speedLimitStyle = 'us',
    flashSpeedLimit = true,
    showCadence = true,
    showPulse = true,
    showHorizon = true,
    showHeading = true,
    showTrim = true,
    showWaypoint = true,
    showFuel = true,
    showEngine = true,
    showAltitude = true,
    showClimb = true,
    showGear = true,
},
```

| Setting           | What it does                 | Values                                   |
| ----------------- | ---------------------------- | ---------------------------------------- |
| `layout`          | Car speedometer style        | `racing` · `sprint` · `corner` · `sport` |
| `bikeLayout`      | Motorcycle style             | `runway` · `corner` · `sport` · `racing` |
| `speedLimitStyle` | Speed limit sign design      | `us` · `eu` · `off`                      |
| `flashSpeedLimit` | Flash the sign when speeding | `true` · `false`                         |
| `showCadence`     | Bicycle pedal cadence        | `true` · `false`                         |
| `showPulse`       | Bicycle heart rate           | `true` · `false`                         |
| `showHorizon`     | Aircraft artificial horizon  | `true` · `false`                         |
| `showHeading`     | Boat heading                 | `true` · `false`                         |
| `showTrim`        | Boat trim                    | `true` · `false`                         |
| `showWaypoint`    | Distance to waypoint         | `true` · `false`                         |
| `showFuel`        | Fuel gauge                   | `true` · `false`                         |
| `showEngine`      | Engine health gauge          | `true` · `false`                         |
| `showAltitude`    | Aircraft altitude            | `true` · `false`                         |
| `showClimb`       | Aircraft climb rate          | `true` · `false`                         |
| `showGear`        | Aircraft landing gear        | `true` · `false`                         |

### Sound

```lua
sound = {
    master = true,
    volume = 40,
    signalTick = true,
    beltOn = true,
    beltOff = true,
    beltAlarm = true,
},
```

| Setting              | What it does              | Values           |
| -------------------- | ------------------------- | ---------------- |
| `master`             | All HUD sound             | `true` · `false` |
| `volume`             | How loud                  | `0` to `100`     |
| `signalTick`         | Indicator tick            | `true` · `false` |
| `beltOn` / `beltOff` | Buckle and unbuckle       | `true` · `false` |
| `beltAlarm`          | Driving unbuckled warning | `true` · `false` |

### Money, identity and weapon

```lua
money = {
    showCash = true,
    showBank = true,
},

identity = {
    showVoice = true,
    showId = true,
    showClock = true,
    showJob = true,
    showGang = true,
},

weapon = {
    show = true,
},
```

Each one is `true` or `false`, and each one shows or hides that chip.

There is one more key inside `identity`:

```lua
identity = {
    extras = {},
},
```

**Chips you added yourself get their own toggle in the settings menu**, and the player's answer is stored here. Leave it as `{}` and every custom chip starts switched on. Name one to start it switched off:

```lua
extras = { crew = false },
```

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

### Layout

```lua
layout = {
    minimap_square = { dx = 2 },
    minimap_circle = { dx = 2 },
},
```

Where elements sit, per minimap shape. **You normally never edit this by hand** — use the in-game layout editor, drag things where you want them, and read the values back out.

## Defaults are a starting point, not a rule

A player can change any of these in the settings menu, and their choice is saved to their own machine. `defaults.lua` only decides what they see on day one.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Stop them changing it</strong></td><td>Lock a setting so it stays on your default and greys out.</td><td><a href="/devmosaic/resources/devmosaic-dm-hud/policy-and-locks.md">Policy And Locks</a></td></tr><tr><td><strong>See what they can change</strong></td><td>Every option in the settings menu, as a player sees it.</td><td><a href="/devmosaic/resources/devmosaic-dm-hud/player-settings.md">What Players Can Change</a></td></tr></tbody></table>

{% hint style="info" %}
**Changed a default, but existing players still see the old one?** Their saved choice wins. They can hit **Restore defaults** in the settings menu to pick up your new values.
{% endhint %}