Examples and troubleshooting
Config examples
Section titled “Config examples”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 = trueConfig.PlayerCountSource = 'framework'Config.PlayerCountInterval = 15With '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.
Standalone server without Discord avatars
Section titled “Standalone server without Discord avatars”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.
Turn the cards into your own shortcuts
Section titled “Turn the cards into your own shortcuts”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.
Events with a link and events with your own script
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.
Bigger menu with the character re-centred
Section titled “Bigger menu with the character re-centred”Config.UIScale = 1.3Config.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.
French server
Section titled “French server”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.
Faster playtime saving
Section titled “Faster playtime saving”Config.Playtime = { identifierType = 'license', logInterval = 10,}A lower interval means less played time is missed if the resource is restarted while players are online.
ESC and other UIs
Section titled “ESC and other UIs”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.
Edge cases
Section titled “Edge cases”- Nested folder. The resource folder must contain
fxmanifest.luadirectly.resources/pausemenu/pausemenu/does not work. See Installation. - Start order. Start
pausemenuafter the framework. If it starts first,'auto'detection reports standalone and the menu shows default player data. Restartingpausemenuonce the framework is running fixes it right away. The lasting fix is the order inserver.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.Frameworkto 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.VehicleCameraand no emote plays.Config.Camera.enabled = falseturns the camera off in both cases. - Emote list. An empty
Config.Emoteslist means no emote plays. A bad animation name means the player keeps standing as they were. - Camera disabled. With
Config.Camera.enabled = falsethe 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-14or14/11/2026is not understood. The card shows that text as it is, instead of a countdown. Use14-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 = falseshows 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_maxClientsinserver.cfg. - Discord token in two places. If both the
server.cfgconvar andConfig.Discord.tokenare set, the convar wins. - Discord avatar did not update. Avatars are cached for
Config.Discord.cacheTimeseconds (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.identifierTypemakes players start from a new total. - Restarting during play. Restarting
pausemenuwhile players are online can drop the time played since the last playtime save. Time is saved everyConfig.Playtime.logIntervalminutes 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. UsePauseMenu.OpenNativeFrontend, or callPauseMenu.ExpectNativeMenu()right before your ownActivateFrontendMenucall.
Troubleshooting
Section titled “Troubleshooting”| 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. |
Before going live
Section titled “Before going live”ensure pausemenuis below the framework inserver.cfg.Config.ServerName,Config.LinksandConfig.Eventsare set to your own values.- The Report and Battle Pass cards are either connected in
framework/open.luaor set toactive = false. - You tested ESC with your inventory, phone and any other full screen UI.
- If you use Discord avatars, the token is set and a player with Discord running sees their picture.
- Old events are removed from
Config.Events.
