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

# Menu

> Set the key that opens the menu, the tab it opens on, and what every tab shares.

`configs/menu.jsonc` owns the menu as a whole: the key and controller button that open it, the tab
it opens on, and the things every tab shares while it is open. Each tab has its own file on top of
this one: the map's start with `map`, and the settings screen's is
[Settings](https://docs.elementlabs.net/products/3d-pause-menu/configuration/settings.md). Colours are in
[Appearance](https://docs.elementlabs.net/products/3d-pause-menu/configuration/ui.md).

How a configuration file is read and merged is described once, in [How configuration works](https://docs.elementlabs.net/configure/files.md).

## Settings

### Opening the menu

| Key | Default | Meaning |
| - | - | - |
| `open.command` | `"element_pausemenu"` | The internal name of the key binding. The menu registers it as the command `+<command>` and binds the key to it. |
| `open.key` | `"ESCAPE"` | The key bound for a player who has not chosen their own. |
| `open.padKey` | `"START"` | The controller button bound alongside the key. Empty registers no controller binding at all. |

The label players see for the binding in the FiveM key-mapping menu is the `controls.description`
text in the [language files](https://docs.elementlabs.net/products/3d-pause-menu/configuration/locales.md). The shipped English
label is `Open 3D Pause Menu`.

`open.key` accepts the key names FiveM uses, such as `M`, `F5`, `TAB` or `ESCAPE`. It is the key a
player gets the first time they join with the menu installed. FiveM then saves it with the player's
own bindings, so changing this value later reaches only players who have never joined; everyone else
keeps the key they have. `ESCAPE` is chosen so the menu takes the place of the pause menu. If your
server binds `ESCAPE` elsewhere, pick another key here.

`open.padKey` is bound in addition to `open.key`: the same command answers to both, so a player can
keep a hand on either device. It takes FiveM's own button names: `L1` `R1` `L2` `R2` `L3` `R3`, the
d-pad as `LUP` `LDOWN` `LLEFT` `LRIGHT`, the face buttons as `RUP` `RDOWN` `RLEFT` `RRIGHT`
(triangle, cross, square, circle), and `SELECT` `START` `TOUCH`. The binding is always a digital
button, so a trigger cannot be used.

The key-binding page inside the settings screen rebinds keyboard and mouse only, which is the game's
limit. A player who wants a different controller button changes it in the FiveM console with
`bind PAD_DIGITALBUTTON <button> "+<command>"`. `open.padKey`, like `open.key`, sets the button
players get the first time they join.

### Start tab

| Key | Default | Meaning |
| - | - | - |
| `startTab` | `"map"` | The tab the menu opens on: `"map"`, `"settings"`, or the `id` of a page another resource registered. |
| `startCamera` | `false` | Whether the camera flies up into the map before a `startTab` other than `"map"` is shown. |

With any tab other than the map, the menu behaves like the game's own pause menu: **Escape** at the
top of a page or of the settings closes the whole menu instead of returning to the map.

With `startCamera` off, the tab opens at once over the game, blurred behind it, and the camera flies
up only when the player picks the **Map** tab. With it on, the camera flies up first and the tab is
shown once it has arrived.

A tab that cannot be entered when the key is pressed, such as a page that is not registered or is
disabled, opens the map instead. Another resource can change both settings while the server runs:
see [Exports](https://docs.elementlabs.net/products/3d-pause-menu/reference/exports.md).

### Which map

| Key | Default | Meaning |
| - | - | - |
| `mapMode` | `"3d"` | The map behind the **Map** tab: `"3d"` for this menu's own, `"vanilla"` for the game's full-screen map. |

With `"vanilla"`, the rest of the menu stays: the settings screen and the pages other resources
register work as they do with the 3D map. Only the map changes:

* The **Map** tab shows the game's map at full screen, with this menu's tab bar over it in place of
  the game's tabs, so the player can go from the map to the settings or a page and back. The game's
  map answers its own controls: zoom, the legend, the waypoint.
* **Escape** on the map closes the menu.
* `startTab` works as with the 3D map: `"map"` opens on the game's map, and **Escape** at the top of
  a page or of the settings goes back to it. Any other tab opens on that tab, and **Escape** there
  closes the menu, as a pause menu does.

The markers other resources add with `AddBlip`, the postal numbers and custom views belong to the 3D
map and do not appear on the game's. Blips the game itself knows about do.

Another resource can choose the map per player with `SetMapMode`: see
[Exports](https://docs.elementlabs.net/products/3d-pause-menu/reference/exports.md).

### While the menu is open

| Key | Default | Meaning |
| - | - | - |
| `muteGameAudio` | `true` | Whether the game's own audio is silenced while the menu is open. The menu's own sounds still play. |
| `blur.enabled` | `true` | Whether the map is blurred behind the settings screen and behind a page, the way the pause menu blurs the world. A page can ask for its own. |
| `blur.fadeMs` | `250` | How long the blur takes to appear and to clear, in milliseconds. |

### Embedded pages

| Key | Default | Meaning |
| - | - | - |
| `pageEmbedHosts` | `[]` | Extra hosts a page may embed an interface from, matched whole. |

A page another resource registers can host its own interface instead of content the menu draws. Such
a page is loaded inside the menu, so its address is checked: the NUI origin of a resource on this
server (`cfx-nui-<resource>`) is always allowed, and anything else has to have its host listed here.
Adding a host you do not control lets that host decide what a player sees inside the menu, so treat
this as a security setting. See [Pages](https://docs.elementlabs.net/products/3d-pause-menu/reference/pages.md).

## Example

The game's own map behind the **Map** tab:

```jsonc theme={null}
{
  "namespace": "menu",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "mapMode": "vanilla"
  }
}
```

`ESCAPE` taken by another menu on the server, and the menu opening on the settings:

```jsonc theme={null}
{
  "namespace": "menu",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "open": {
      "key": "M",
      "padKey": "SELECT"
    },
    "startTab": "settings"
  }
}
```

Everything not listed keeps its shipped value.

## Applying changes

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

A change to `open.key` or `open.padKey` reaches only players who have never joined with the menu
installed. Everyone else keeps the key they have and can change it in the FiveM key-mapping menu.
Moving every player to a new key takes a new `open.command`, which also discards the bindings players
chose themselves.

## Limits

| Key | Stay within | Why |
| - | - | - |
| `open.command` | Set it once, before players bind it | FiveM keeps a binding against the command name, and a renamed command is a new one: every player's own binding is lost. |
| `blur.fadeMs` | Roughly `100` to `600` | Below that the blur snaps on, which reads as a glitch. Above it, the settings screen is legible before the map behind it has finished blurring. |
| `pageEmbedHosts` | Hosts you control | A listed host decides what appears inside the menu. |

## Related

* [Configuration](https://docs.elementlabs.net/products/3d-pause-menu/configuration/index.md)
* [Map](https://docs.elementlabs.net/products/3d-pause-menu/configuration/map.md)
* [How players use the menu](https://docs.elementlabs.net/products/3d-pause-menu/using-the-map.md)


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