> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementlabs.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Map labels

> The postal numbers and zone names drawn over the map, and how they are sized.

`configs/map-labels.jsonc` controls the labels drawn over the map: the postal numbers players read
out to say where they are, and the zone names that replace them once the camera is pulled back far
enough that a number would be a pixel tall.

Only one of the two is ever on screen. Which one is decided by how high the camera is above the
ground, and nothing else.

Every label knows the height of the ground under it, measured against the game's own heightmap when
the set was baked. A name over Vinewood Hills or Mount Chiliad sits on the hillside rather than at
sea level, which is what keeps it in the right place as you tilt the camera.

## Settings

### Both tiers

| Key | Default | Meaning |
| - | - | - |
| `enabled` | `true` | Whether labels are drawn at all. |
| `shadowColor` | `[0, 0, 0, 150]` | Red, green, blue and opacity of the drop shadow behind numbers and names. |

### Postal numbers

| Key | Default | Meaning |
| - | - | - |
| `postals.dataset` | `"ocrp"` | Which shipped postal set to use: `new`, `ocrp` or `oulsen`. |
| `postals.color` | `[255, 255, 255, 255]` | Red, green, blue and opacity of the numbers. |
| `postals.size` | `15` | How much ground a number covers, in metres. |
| `postals.minPixels` | `14` | The smallest a number is ever drawn on screen. |
| `postals.maxPixels` | `40` | The largest a number is ever drawn on screen. |
| `postals.font` | `"$Font2"` | Which game font to draw with. |
| `postals.shadowOffset` | `0.0` | Drop shadow behind each number, as a fraction of `postals.size`. `0` draws none. |
| `postals.outline` | `2.0` | Outline around each number, in screen pixels, in `shadowColor`. It keeps white numbers readable over pale ground. `0` draws none. |

The three sets are different conventions. `new` is the newer five-digit set, `ocrp` is the older
four-digit convention, and `oulsen` matches the satellite map of the same name. Changing the set
changes what players read out, so pick one before you open, and tell them which it is. These three
are the only choices: the numbers are compiled into the map itself rather than read from a file, so
there is no way to point it at a set of your own.

A number is painted on the map rather than laid over it: `postals.size` is measured on the ground,
so a number covers the same ground at every zoom and grows and shrinks with the imagery under it,
until it reaches one of the two limits. `postals.minPixels` keeps the numbers readable with a
district on screen; `postals.maxPixels` stops them filling the screen when the camera is low.

Numbers are kept a few number-heights apart, so pulling the camera back shows fewer of them rather
than a solid block. Each number that stays keeps its place as the camera pans, and zooming in only
adds numbers between the ones already shown. Raising `postals.minPixels` also thins them out.

| Setting | What you get |
| - | - |
| `minPixels: 0`, `maxPixels: 0` | The numbers scale with the map and nothing else, tiny when pulled back. |
| `minPixels` equal to `maxPixels` | The numbers hold one size on screen at every zoom. |

### Zone names

| Key | Default | Meaning |
| - | - | - |
| `zones.showAbove` | `3000.0` | Metres above the ground at which zone names replace postal numbers. |
| `zones.size` | `12` | How large a zone name is drawn, in screen pixels. |
| `zones.font` | `"$Font2"` | Which game font to draw them with. |
| `zones.color` | `[255, 255, 255, 240]` | Red, green, blue and opacity of the names. |
| `zones.spacing` | `0.5` | Extra pixels between glyphs. |
| `zones.shadowOffset` | `0.0` | Drop shadow behind each name, as a fraction of `zones.size`. `0` draws none. |
| `zones.outline` | `2.0` | Outline around each name, in screen pixels, in `shadowColor`. `0` draws none. |
| `zones.wrapChars` | `20` | Names longer than this are broken over two lines. `0` never breaks one. |

Only the major zones are drawn: the two dozen regions and districts a player navigates by, not every
named block in the city.

Zone names follow the player's language. A player running the game in Italian reads *Grande
boscaglia* where an English one reads *Great Chaparral*. A name too long for one line is broken where
the two halves come out closest in length, after it has been translated, so the break works in every
language. A name with no space in it is left on one line.

A zone name holds one size on screen at every zoom, because it has to be readable when the map is
pulled all the way back. Where two names would sit on top of each other the more prominent one is
kept and the other is dropped, which is why the labels around Vinewood and Downtown thin out as you
zoom out.

The camera has to come back a little below `zones.showAbove` before the numbers return, so a camera
resting on the line does not swap the labels over and over.

## Example

The five-digit convention, with numbers held at one size on screen and zone names taking over a
little later than they do by default:

```jsonc theme={null}
{
  "namespace": "map-labels",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "postals": {
      "dataset": "new",
      "minPixels": 20,
      "maxPixels": 20
    },
    "zones": {
      "showAbove": 1400.0
    }
  }
}
```

Labels off altogether, for a server that names places another way:

```jsonc theme={null}
{
  "namespace": "map-labels",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "enabled": false
  }
}
```

## Applying changes

```text theme={null}
restart element_3d_pausemenu
```

`enabled` and `postals.dataset` are the two a resource can also change while the server runs, with
`SetPostalsEnabled` and `SetPostalDataset`. The rest take a restart.

## Limits

| Key | Stay within | Why |
| - | - | - |
| `postals.dataset` | `new`, `ocrp` or `oulsen` | A name that is not one of them draws no postal numbers at all. |
| `postals.minPixels` / `postals.maxPixels` | Roughly `10` to `60`, with `minPixels` no larger than `maxPixels` | Below ten a number is unreadable; above sixty the numbers cover what is under them. Inverting the two leaves the map with no size it can honour. |
| `zones.showAbove` | Roughly `600` to `3000` | Below that, zone names replace the numbers while the player is still reading them. Above it, the numbers stay on screen long after they are a pixel tall. |

`postals.font` and `zones.font` are game font names, not files. A name the game does not have draws
with the default font rather than failing, so check the result in game after changing one.

## Related

* [Configuration](https://docs.elementlabs.net/products/3d-pause-menu/configuration/index.md)
* [How players use the menu](https://docs.elementlabs.net/products/3d-pause-menu/using-the-map.md)
* [Exports](https://docs.elementlabs.net/products/3d-pause-menu/reference/exports.md): turning labels on and choosing the set at runtime


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.