Skip to content

Examples and troubleshooting

All examples change entries in pausemenu/config.lua. Restart the resource after editing (restart pausemenu).

QBX or QBCore server with a multicharacter screen

Section titled “QBX or QBCore server with a multicharacter screen”

Count only players who have finished character selection, and refresh the count more often:

Config.Framework = 'auto'
Config.ServerName = 'Los Santos Stories'
Config.ShowPlayerCount = true
Config.PlayerCountSource = 'framework'
Config.PlayerCountInterval = 15

With 'framework', players on the loading screen or in character selection are not included in the number. The count updates on the interval, not at the moment a player spawns.

Config.Framework = 'standalone'
Config.Discord = {
enabled = false,
token = '',
cacheTime = 24 * 60 * 60,
avatarSize = 128,
}
Config.DefaultAvatar = 'https://example.com/images/default-avatar.png'

Every player sees Config.DefaultAvatar. Name is the FiveM player name, and money is shown as 0. See Hooks and integration.

Hide the Battle Pass card, send Report to a Discord ticket channel, and rename Donate:

Config.Buttons.battlepass.active = false
Config.Buttons.report = {
active = true,
name = 'Support',
subtitle = 'Open a ticket',
icon = 'ticket',
action = { type = 'link', value = 'https://discord.gg/yourserver' },
}
Config.Buttons.donate.name = 'Store'
Config.Buttons.donate.subtitle = 'Support the server'

A 'link' action does not call a hook, so PauseMenu.Framework.Report() is not used while this is set.

You can also edit the existing entries in place, inside the Config.Buttons table in config.lua.

Section titled “Events with a link and events with your own script”
Config.Events = {
{
title = 'Street Race Night',
subtitle = 'Downtown circuit',
startDate = '14-11-2026',
image = 'https://example.com/images/race-night.jpg',
url = 'https://discord.gg/yourserver', -- opens in the browser
},
{
title = 'Cartel War',
subtitle = 'Faction takeover event',
startDate = '21-11-2026',
image = '',
url = '', -- runs PauseMenu.Framework.Event()
},
}

The first event opens a link. The second runs the Event hook in framework/open.lua. See Events without a link.

Config.UIScale = 1.3
Config.Camera = {
enabled = true,
swingDuration = 1300,
offset = { x = 0.3, y = 2.4, z = 0.2 },
fov = 42.0,
aimOffset = { x = 0.40, y = 0.0, z = 0.2 },
}

A larger menu leaves a different gap beside it. The 0.40 above is only a starting point. Change aimOffset.x in small steps (0.05) and reopen the menu until the character is centred in the gap. A higher x moves the character toward the right of the screen.

Config.Locale = 'fr'
Config.ServerName = 'Los Santos Stories'
Config.Buttons.report.name = 'Signaler'
Config.Buttons.report.subtitle = 'Signaler un joueur'
Config.Buttons.donate.name = 'Boutique'
Config.Buttons.donate.subtitle = 'Soutenir le serveur'

The locale file translates the fixed labels. Button names and subtitles must be translated in the config.

Config.Playtime = {
identifierType = 'license',
logInterval = 10,
}

A lower interval means less played time is missed if the resource is restarted while players are online.

Because this resource replaces the pause menu, it sees every ESC press. The Config.Esc options stop it from opening behind a UI the player just closed. All cases below use the options described in Configuration.

Situation What happens What to do
Player opens ox_inventory, then presses ESC to close it The default settings keep the pause menu closed. invOpen and invBusy block it while the inventory is open, and focusGrace covers the moment after it closes. Nothing.
The pause menu still pops up right after closing an inventory or another UI The UI releases focus later than focusGrace allows. Raise focusGrace in steps of 100 (for example 500, then 600).
Another UI that uses NUI focus is open respectNuiFocus = true keeps the pause menu closed. Nothing.
A resource on your server holds NUI focus all the time, and the menu never opens respectNuiFocus is blocking every ESC press. Set respectNuiFocus = false. Use blockStates for the UIs that still need to block the menu.
A custom UI that does not use NUI focus is open The menu cannot see it. Publish a statebag key from that UI and add it to blockStates. See Telling the menu that your UI is open.
The menu opens and closes again on one ESC press The press is being read twice. Raise closeGrace (for example 400 or 500).
The pause menu is already open and another UI opens The open guards are not applied once the menu is open, so ESC can still close the pause menu. Nothing.
Player opens the native map or settings from the Kivo menu The Rockstar screen handles ESC until it closes. The Kivo menu then takes ESC back. Nothing. For custom hooks, see the native handoff section of Hooks and integration.

Example: server where a HUD keeps NUI focus

Section titled “Example: server where a HUD keeps NUI focus”
Config.Esc = {
respectNuiFocus = false,
focusGrace = 500,
blockStates = { 'invOpen', 'invBusy', 'myPhoneOpen' },
closeGrace = 300,
nativeOpenTimeout = 1500,
}

With respectNuiFocus = false, the menu no longer checks NUI focus at all. Make sure every UI that should block the menu publishes a key listed in blockStates.

  • Nested folder. The resource folder must contain fxmanifest.lua directly. resources/pausemenu/pausemenu/ does not work. See Installation.
  • Start order. Start pausemenu after the framework. If it starts first, 'auto' detection reports standalone and the menu shows default player data. Restarting pausemenu once the framework is running fixes it right away. The lasting fix is the order in server.cfg.
  • More than one framework running. If several framework resources are running at once (for example a compatibility layer next to the real one), set Config.Framework to the one you actually use.
  • Exit tab. It closes the menu. It does not disconnect the player from the server.
  • Vehicles. In a vehicle, the camera uses Config.VehicleCamera and no emote plays. Config.Camera.enabled = false turns the camera off in both cases.
  • Emote list. An empty Config.Emotes list means no emote plays. A bad animation name means the player keeps standing as they were.
  • Camera disabled. With Config.Camera.enabled = false the menu opens over the normal gameplay view.
  • Expired events. Events whose date has passed show “Live now” until you remove them from Config.Events.
  • Wrong date format. A date like 2026-11-14 or 14/11/2026 is not understood. The card shows that text as it is, instead of a countdown. Use 14-11-2026.
  • Event images. Use a direct link to an image file. Big images are resized in the game before display. If the image cannot be loaded, the default event image is shown.
  • Empty links. A tab or button with an empty link does nothing when clicked.
  • Inactive cards. active = false shows the card darker and not clickable. It does not remove it from the layout.
  • Money display. Amounts are rounded down to whole numbers and always shown with a $ sign.
  • Player count maximum. The maximum slots number comes from sv_maxClients in server.cfg.
  • Discord token in two places. If both the server.cfg convar and Config.Discord.token are set, the convar wins.
  • Discord avatar did not update. Avatars are cached for Config.Discord.cacheTime seconds (24 hours by default). A player who changes their Discord picture sees the new one after the cache time passes.
  • Changing the playtime identifier. Totals are stored per identifier, so switching Config.Playtime.identifierType makes players start from a new total.
  • Restarting during play. Restarting pausemenu while players are online can drop the time played since the last playtime save. Time is saved every Config.Playtime.logInterval minutes and when a player leaves.
  • ESX gang. ESX has no gang, so the Gang line always shows the “No Gang” text.
  • Custom native menu hooks. A hook that opens a Rockstar frontend menu without calling PauseMenu.ExpectNativeMenu() first is not treated as a handoff, and the native screen may close again straight away. Use PauseMenu.OpenNativeFrontend, or call PauseMenu.ExpectNativeMenu() right before your own ActivateFrontendMenu call.
Problem Likely cause Fix
ESC still shows the normal GTA pause menu pausemenu is not running, or another resource also manages the pause menu. Run ensure pausemenu, check the console for errors, and stop any other pause menu resource.
Console says the resource was not found or fxmanifest.lua is missing Wrong folder layout. Make sure fxmanifest.lua is directly inside the folder you ensure. See Installation.
ESC does nothing at all Another resource holds NUI focus, or a blockStates key is stuck on true. Test with respectNuiFocus = false. Check that your own UIs reset their statebag key when they close.
Menu opens behind or right after an inventory closes UI releases focus later than focusGrace. Raise focusGrace. Make sure blockStates contains the keys your inventory publishes.
Map or Settings screen closes immediately, or ESC is unresponsive for a moment after clicking it A custom hook opens a Rockstar menu without PauseMenu.ExpectNativeMenu(), or announced a native menu that never appeared. Call PauseMenu.ExpectNativeMenu() right before your native call, or use PauseMenu.OpenNativeFrontend. If no native screen appears, control returns on its own after nativeOpenTimeout ms.
Report or Battle Pass only shows a “Hook me up” message The default hooks are still in open.lua. Edit the functions in pausemenu/framework/open.lua. See Hooks and integration.
Name, money, job show defaults on a framework server Framework was not running when pausemenu started, or two frameworks are running. Start pausemenu after the framework, or set Config.Framework. Check the console line that names the detected framework.
No Discord avatar No bot token, bot not in your Discord server, no linked Discord identifier, avatars turned off, or the player has no profile picture. Check each point under Discord avatars. Set the token with set pausemenu_discord_token "..." in server.cfg.
Player count looks too high Config.PlayerCountSource is 'native' and counts players still loading. Use 'framework'.
Player count does not update after character selection Refresh interval is 0 or very long. Set Config.PlayerCountInterval to a positive number, for example 15.
Playtime restarted from zero Config.Playtime.identifierType was changed. Set it back to the previous value.
Event shows “Live now” or a raw date The date has passed, or it is not written as DD-MM-YYYY. Update or remove the event, and check the format.
New language does not appear The file was added but not refreshed, the Locales['xx'] code does not match Config.Locale, or the file has a syntax error. Run refresh and restart pausemenu. Check that the file name, locale code and Config.Locale agree. Check the console for Lua errors.
Characters appear cut off, or sit in the wrong place Camera offsets do not suit your UI scale or the player’s vehicle. Adjust Config.Camera.offset and aimOffset, or the Config.VehicleCamera values.
Config edits have no effect The resource has not been restarted. Run restart pausemenu.
  1. ensure pausemenu is below the framework in server.cfg.
  2. Config.ServerName, Config.Links and Config.Events are set to your own values.
  3. The Report and Battle Pass cards are either connected in framework/open.lua or set to active = false.
  4. You tested ESC with your inventory, phone and any other full screen UI.
  5. If you use Discord avatars, the token is set and a player with Discord running sees their picture.
  6. Old events are removed from Config.Events.