# esx_pausemenu (/docs/addons/esx_pausemenu)

esx_pausemenu replaces the GTA V pause screen with a branded NUI menu for ESX Legacy. When a loaded player presses `ESC` or `P`, it shows their character name, job, cash, bank, play time, ping, location, server time and online player count, plus buttons for the map, game settings, news, Discord, rules and leaving the server.

## Overview [#overview]

| | |
| --- | --- |
| Resource | `esx_pausemenu` (version 1.0.0, added with ESX Legacy 1.16.0) |
| Side | Client NUI with one server callback |
| Dependencies | `esx_lib`, `es_extended` |
| Optional | [esx_scoreboard](/docs/addons/esx_scoreboard) for the online players button |
| Database | None |

The menu is plain HTML, CSS and JavaScript in `web/`, so there is no build step. It uses `xLib.colors` from [esx_lib](/docs/core/esx_lib), so it follows your ESX theme convars automatically.

## Installation [#installation]

```bash title="server.cfg"
ensure esx_lib
ensure es_extended
ensure esx_scoreboard  # optional
ensure esx_pausemenu
```

Then set your own links in `config.lua` (at least `Config.Links.discord` and `Config.Links.rules`) and restart the resource.

## How it works [#how-it-works]

1. A client loop disables controls `200` and `199` (the two pause inputs) every frame while the player is loaded.
2. When one of them is released, the client calls the server callback `esx_pausemenu:getData`.
3. The server returns player data and the client opens the NUI with blur, the theme, the clock and the street name.
4. **Map** and **Settings** close the NUI and open the native `FE_MENU_VERSION_MP_PAUSE` frontend. **Resume** or `ESC` closes it.

The menu does not open before `ESX.PlayerLoaded` is true, so the character selection screen keeps the normal pause behavior. It closes automatically on `esx:onPlayerLogout`.

## Configuration [#configuration]

All keys in `config.lua`:

| Key | Default | Description |
| --- | --- | --- |
| `Config.Locale` | `esx:locale` convar, then ESX config, then `"en"` | Language for UI text |
| `Config.Brand.kicker` | `"FIVEM ROLEPLAY"` | Small text above the title |
| `Config.Brand.title` | `"ESX LEGACY"` | Big title; also the server name fallback |
| `Config.Brand.tagline` | `"ROLEPLAY BEYOND LIMITS"` | Line under the title |
| `Config.Brand.city` | `"Los Santos"` | City shown in the location block |
| `Config.Brand.established` | `"2015"` | "Established" year |
| `Config.Brand.communityLine` | `"BUILT BY A COMMUNITY THAT CARES"` | Footer line |
| `Config.Links.discord` | `"https://discord.gg/esx-framework"` | Discord button; empty disables it |
| `Config.Links.rules` | `"https://esx-framework.org/"` | Rules button; empty disables it |
| `Config.Links.store` | `""` | Optional store link in the news dialog |
| `Config.News` | `{}` | List of `{ title, body, date }` entries |
| `Config.PeopleCommand` | `"scoreboard"` | Command run by the online players chip |
| `Config.Controls.pause` | `200` | ESC control id |
| `Config.Controls.pauseAlt` | `199` | P control id |
| `Config.ScreenBlurMs` | `180` | Blur fade duration in ms |
| `Config.Debug` | `false` | Print debug messages |

```lua title="config.lua"
Config.News = {
    { title = "Police recruitment open", body = "Apply on our Discord.", date = "20 OCT 2026" },
    { title = "Server restart times", body = "Daily at 06:00 and 18:00.", date = "01 OCT 2026" },
}
```

News text is shown as plain text, and the UI shows up to 20 entries.

The server name in the header comes from the `sv_projectName` convar, then `sv_hostname`, then `Config.Brand.title`. GTA color codes like `^1` are stripped.

## Callbacks, events and commands [#callbacks-events-and-commands]

### esx_pausemenu:getData (server callback) [#esx_pausemenugetdata-server-callback]

```lua
ESX.TriggerServerCallback('esx_pausemenu:getData', function(data) end)
```

Returns `nil` if the player is not loaded or the rate limit is hit (2 requests burst, refilling 1 every 750 ms). Otherwise it returns:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `number` | Server id |
| `name` | `string` | FiveM player name |
| `characterName` | `string` | `xPlayer.getName()` |
| `sex` | `string?` | `xPlayer.get('sex')` |
| `ping` | `number` | Player ping |
| `role`, `job` | `string` | Job label (localized "unemployed" for `unemployed`) |
| `jobName` | `string` | Job name |
| `bank`, `cash` | `number` | Account balances |
| `playTime` | `number` | `xPlayer.getPlayTime()` in seconds |
| `players`, `maxPlayers` | `number` | Online count and `sv_maxclients` |
| `serverName` | `string` | See above |

The callback only returns the caller's own data, so it is safe to leave exposed.

### esx_pausemenu:leaveServer (server net event) [#esx_pausemenuleaveserver-server-net-event]

Drops the player who triggers it with the localized `leave_reason`. A client can only kick itself, so this is not a security concern.

### /esx_pausemenu (client command) [#esx_pausemenu-client-command]

Toggles the menu. Use it to bind the menu to another key or to open it from another script with `ExecuteCommand('esx_pausemenu')`.

## Integration tips [#integration-tips]

- **HUDs:** the menu calls `HideHudAndRadarThisFrame()` while open, which only hides native GTA HUD elements. NUI HUDs such as [esx_hud](/docs/addons/esx_hud) react to `esx:pauseMenuActive`, which es_extended fires for the native pause menu only, so they stay underneath the full-screen NUI.
- **Theme:** change colors with the `esx:brand-color`, `esx:darkest-color` and related `setr` convars that esx_lib reads; no file edits needed.
- **Languages:** UI strings are the `ui_*` keys in `locales/*.lua` (en, fr, de, es, it, nl, pl). Missing languages fall back to English.
- **Other pause menus:** do not run esx_pausemenu together with another resource that disables controls 199 and 200, or both will fight over `ESC`.

## Common issues [#common-issues]

- **ESC opens the normal GTA menu:** the player is not loaded yet, the resource failed to start (check that esx_lib is started first), or the callback returned `nil`.
- **Menu flickers open and closed:** another script also opens the pause menu on ESC. Remove one of them.
- **Map closes immediately:** a third-party script calls `SetPauseMenuActive(false)` every frame.

## Related [#related]

- [esx_scoreboard](/docs/addons/esx_scoreboard)
- [esx_hud](/docs/addons/esx_hud)
- [esx_lib](/docs/core/esx_lib)
- [Callbacks guide](/docs/guides/callbacks)