Skip to content

Configuration

All settings are in pausemenu/config.lua. Text in the menu comes from pausemenu/locales/*.lua. Restart the resource after any change:

restart pausemenu

Jump to a section:

Option Default Valid values What it does
Config.Framework 'auto' 'auto', 'esx', 'qb', 'qbx', 'standalone' Which framework supplies player data (name, money, job, gang). 'auto' detects ESX, QB or QBX. Set a fixed value if you run more than one of them or if detection picks the wrong one.
Config.ServerName 'Kivo Roleplay' Any text Server name shown in the menu.
Config.Locale 'en' The code of a file in locales/, such as 'en' or 'fr' Active language. If the code does not match a loaded locale, English is used.
Config.UIScale 1.05 A number Scale of the whole menu. The base layout is fairly small. 1.5 makes it clearly larger.
Config.MainColor '#FF619B' Six digit hex colour Main accent colour of the menu.
Config.SecondaryColor '#5FEABE' Six digit hex colour Secondary accent colour.

Use the full six digit form for colours, for example '#FF619B'. Three digit shorthand such as '#F69' is not supported.

Value Name Cash and bank Job Gang
'esx' ESX character name ESX money and bank accounts ESX job label Always the “No Gang” label (ESX has no gang)
'qb' and 'qbx' Character first and last name Cash and bank money Job label Gang label
'standalone' FiveM player name 0 Default job label Default gang label

When Config.Framework is 'auto', the server console prints the detected value at startup.

The player count bubble shows online players and the maximum slots in the menu header. The maximum comes from the sv_maxClients convar in your server.cfg.

Option Default Valid values What it does
Config.ShowPlayerCount true true, false Shows or hides the count bubble.
Config.PlayerCountSource 'native' 'native', 'framework' Where the number comes from. See below.
Config.PlayerCountInterval 30 Seconds, 0 or higher Seconds between automatic refreshes. 0 turns the refresh loop off.
Source What it counts Use it when
'native' Every connected client, including players still on the loading screen or in the multicharacter screen. You want the same number as the FiveM server list.
'framework' Only players your framework has loaded (ESX GetExtendedPlayers, QBCore GetQBPlayers, QBX GetQBPlayers). Players on the loading screen or in character selection are not counted. You want the number players usually mean by “online”.

Notes:

  • With 'framework' on a standalone server, the count falls back to the native count.
  • With 'framework', the count also falls back to the native count for a short time after the resource starts, until framework detection has finished.
  • The count refreshes immediately when someone joins or leaves. A player finishing character selection does not trigger a refresh, so 'framework' depends on the interval to notice it. Keep Config.PlayerCountInterval above 0 when you use 'framework'.
  • With 'native', the interval has little effect because joins and leaves already refresh the count.

Kivo Pausemenu replaces the native pause menu, so it receives every ESC press, including the press a player uses to close an inventory or another UI. The Config.Esc table decides when an ESC press is allowed to open the menu. The native pause menu stays suppressed in all cases. Only opening the Kivo menu is gated. ESC always closes the Kivo menu when it is open.

Config.Esc = {
respectNuiFocus = true,
focusGrace = 400,
blockStates = { 'invOpen', 'invBusy' },
closeGrace = 300,
nativeOpenTimeout = 1500,
}
Option Default Valid values What it does
respectNuiFocus true true, false The menu does not open while another resource holds NUI focus (the mouse cursor and keyboard are captured by another UI). NUI focus is shared by all resources. Set to false only if a resource on your server holds focus permanently, otherwise the menu would never open.
focusGrace 400 Milliseconds, 0 or higher ESC presses are ignored for this long after any resource releases NUI focus. This covers UIs that close on key release, such as ox_inventory. They release focus a frame or two after the press that closed them, and the game then passes that press to this menu. 0 turns this off.
blockStates { 'invOpen', 'invBusy' } List of text keys Keys on LocalPlayer.state that block opening while their value is truthy. The defaults are the keys that inventories publish. Add your own keys for other UIs.
closeGrace 300 Milliseconds ESC presses are ignored for this long after the Kivo menu closes. This stops the menu from opening and closing repeatedly on one key press.
nativeOpenTimeout 1500 Milliseconds Recovery time for custom Map or Settings hooks. If a hook says it will open a Rockstar frontend menu but none appears within this time, the Kivo menu takes back control of ESC.

See Examples and troubleshooting for worked cases.

The Map card, Map tab and Settings tab hand control to the Rockstar frontend (the native map or settings screen). While that screen is open, it alone handles ESC. When it closes, the Kivo menu takes ESC back. The default hooks in framework/open.lua do this for you. Details for custom hooks are in Hooks and integration.

Option Default Valid values What it does
Config.EventInterval 5000 Milliseconds How long each event slide stays before the carousel moves to the next. Only matters with two or more events.
Config.DefaultAvatar '' Image URL or empty Image shown when a player has no Discord avatar. Empty uses the bundled image.
Config.DefaultEventImage '' Image URL or empty Image shown for events without an image, or whose image fails to load. Empty uses the bundled image.
Config.Links = {
discord = 'https://discord.gg/yourserver',
donate = 'https://yourserver.tebex.io/',
tebex = 'https://yourserver.tebex.io/',
}
Key Default Used by
discord 'https://discord.gg/yourserver' The Discord tab, and any button whose link value is 'discord'.
donate 'https://yourserver.tebex.io/' Any button whose link value is 'donate'. By default, the Donate card.
tebex 'https://yourserver.tebex.io/' The Tebex tab, and any button whose link value is 'tebex'.

Links open in the player’s real web browser, not inside the game. Do not delete the table or its keys. An empty link means that clicking the tab does nothing.

The Discord and Tebex tabs always use Config.Links.discord and Config.Links.tebex. They are not part of Config.Buttons.

Config.Buttons configures the five action cards. The keys are fixed. You can change what each card shows and does, but you cannot add new cards.

Key Card Default action
report Small card Calls the Report hook
donate Small card Opens Config.Links.donate
discord Small card Opens Config.Links.discord
battlepass Medium card Calls the Battle Pass hook
map Large card Calls the Map hook

Each card has these fields:

Field Valid values What it does
active true, false false makes the card darker and not clickable. Any other value (or leaving it out) counts as active.
name Any text Card title. This text is not translated by the locale files.
subtitle Any text Smaller text under the title. This text is not translated by the locale files.
icon See the icon list below Icon on the card. An unknown name shows the Report icon.
action { type = ..., value = ... } What happens on click. See below.

Available icons: report, tebex, discord, map, ticket, calendar, user, cash, bank, job, gang, clock, settings, home, exit.

type value Result
'link' 'discord', 'donate', 'tebex' or a full URL Opens the link in the player’s browser. The menu stays open. If the value matches a key in Config.Links, that URL is used. Otherwise the value is used as the URL.
'framework' 'report', 'battlepass', 'map' or 'settings' Closes the menu, then runs the matching function in framework/open.lua.

A 'framework' button with any other value closes the menu and does nothing else.

Default configuration:

Config.Buttons = {
report = {
active = true,
name = 'Report',
subtitle = 'Report the players',
icon = 'report',
action = { type = 'framework', value = 'report' },
},
donate = {
active = true,
name = 'Donate',
subtitle = 'Make a donation',
icon = 'tebex',
action = { type = 'link', value = 'donate' },
},
discord = {
active = true,
name = 'Discord',
subtitle = 'Join the server',
icon = 'discord',
action = { type = 'link', value = 'discord' },
},
battlepass = {
active = true,
name = 'Battle Pass',
subtitle = 'Complete the tasks',
icon = 'ticket',
action = { type = 'framework', value = 'battlepass' },
},
map = {
active = true,
name = 'MAP',
subtitle = 'View Location',
icon = 'map',
action = { type = 'framework', value = 'map' },
},
}

The Map and Settings tabs always run the Map and Settings hooks. Changing Config.Buttons.map only changes the Map card.

When the menu opens on foot, the gameplay camera swings around to face the character. The final position is relative to the character.

Config.Camera = {
enabled = true,
swingDuration = 1300,
offset = { x = 0.3, y = 2.4, z = 0.2 },
fov = 42.0,
aimOffset = { x = 0.30, y = 0.0, z = 0.2 },
}
Option Default What it does
enabled true false turns off the camera swing, on foot and in vehicles. The menu still opens, and the player stays on the normal gameplay view.
swingDuration 1300 Milliseconds the swing from the gameplay camera takes.
offset x = 0.3, y = 2.4, z = 0.2 Final camera position relative to the character. x is right (positive) or left (negative), y is in front (positive) or behind (negative), z is up or down. A larger y pulls the camera back so the whole character fits without being cut off.
fov 42.0 Camera field of view in degrees. Lower values zoom in.
aimOffset x = 0.30, y = 0.0, z = 0.2 The point the camera looks at, relative to the character. A positive x pushes the character toward the right of the screen, into the empty gap beside the menu. Move x toward 0 to move the character further left.

If you change Config.UIScale, you may also want to adjust aimOffset.x so the character stays centred in the gap beside the menu.

When the player is in a vehicle, the camera films the vehicle from the front and no emote plays. The camera is attached to the vehicle, so it follows the car if it is still moving.

Config.VehicleCamera = {
offset = { x = 1.2, y = 4.5, z = 1.2 },
fov = 50.0,
aimOffset = { x = 0.0, y = 0.0, z = 0.5 },
}
Option Default What it does
offset x = 1.2, y = 4.5, z = 1.2 Camera position relative to the vehicle: front of the car and raised.
fov 50.0 Camera field of view in degrees.
aimOffset x = 0.0, y = 0.0, z = 0.5 The point the camera looks at, relative to the vehicle.

Large vehicles may need a bigger y in offset to fit in the frame.

Config.Emotes is a list of idle animations. One is picked at random each time the menu opens on foot. It plays looped until the menu closes.

Config.Emotes = {
{ dict = 'missbigscore2aig_3', anim = 'wait_for_van_c', chance = 45 },
{ dict = 'missmic_4premierejimwaitbef_prem', anim = 'wait_base', chance = 45 },
{ dict = 'missheistpaletoscoresetup', anim = 'trevor_impatient_wait_3', chance = 10 },
}
Field What it does
dict Animation dictionary name.
anim Animation name inside that dictionary.
chance Weight for the random pick. The weights do not have to add up to 100. An entry with 45 is picked as often as another with 45, and four and a half times as often as one with 10.

To add an emote, add another line with its own dict, anim and chance. To remove the emote, use an empty list (Config.Emotes = {}).

If an animation dictionary does not load within about one and a half seconds, the player simply stays in their current pose for that opening. Check the dictionary and animation names if one never plays.

Config.Discord = {
enabled = true,
token = '',
cacheTime = 24 * 60 * 60,
avatarSize = 128,
}
Option Default Valid values What it does
enabled true true, false Turns Discord avatars on or off. When off, everyone sees the default avatar.
token '' Raw bot token, without the word Bot Bot token used to look up avatars. Prefer the server.cfg line set pausemenu_discord_token "YOUR_BOT_TOKEN". If that convar is set, it is used instead of this value.
cacheTime 86400 (24 hours) Seconds How long a looked up avatar is reused before it is looked up again.
avatarSize 128 Power of two from 16 to 4096 Size in pixels of the avatar image requested from Discord.

An avatar is only shown when all of these are true:

  1. Config.Discord.enabled is true.
  2. The player has a Discord identifier linked to their FiveM session.
  3. A bot token is set (in server.cfg or config.lua).
  4. The bot has been invited to your Discord server.

If any of these is missing, or the player has not set a Discord profile picture, the menu shows Config.DefaultAvatar, or the bundled image if that is empty.

The menu shows each player’s total playtime on your server as days, hours and minutes, for example 1d 16h 2m. The resource tracks this itself. It does not need a database.

Config.Playtime = {
identifierType = 'license',
logInterval = 30,
}
Option Default Valid values What it does
identifierType 'license' 'license', 'discord', 'steam', 'fivem' Which player identifier is used to store a player’s total.
logInterval 30 Minutes How often the time played so far is added to each connected player’s saved total. Time is also added when a player leaves.

Notes:

  • Choose the identifier before players build up playtime, and then keep it. Totals are stored per identifier. If you change identifierType later, players start from a new total, because their old total is stored under the old identifier.
  • Choose an identifier that every player has. The default value is always present on a normal FiveM connection. 'discord' and 'steam' only exist when the player has them linked or running. A player without the chosen identifier type is tracked under another of their identifiers.
  • Time played since the last save cycle is not added if the resource is restarted while players are online. Lower logInterval if you restart the resource often.

Config.Events is the list shown in the events carousel. The sample config ships with two events. Replace them with your own.

Config.Events = {
{
title = 'Cartel War',
subtitle = 'Faction takeover event',
startDate = '28-06-2026',
image = '',
url = '',
},
{
title = 'Street Race Night',
subtitle = 'Downtown circuit',
startDate = '30-06-2026',
image = '',
url = 'https://discord.gg/yourserver',
},
}
Field Valid values What it does
title Any text Event name shown on the card.
subtitle Any text Short description.
startDate 'DD-MM-YYYY' Start date. The card shows “Starts in” followed by the time left.
image Image URL or empty Banner for the event. Large images are resized in the player’s game before display. Empty uses Config.DefaultEventImage, or the bundled image.
url Link or empty Opens in the player’s browser when the event is clicked. If empty, the Event hook in framework/open.lua runs instead.

How events behave:

  • The countdown reads Starts in 3d 4h when more than a day is left, Starts in 5h 20m when under a day, and Starts in 12m when under an hour.
  • The start date means midnight at the start of that day, on the player’s own computer. Players in other time zones see the countdown reach zero at different moments.
  • Once the date has passed, the card shows the “Live now” text. Events are never removed automatically. Delete old events from the config.
  • If startDate is not in DD-MM-YYYY form (two digit day, two digit month, four digit year, with hyphens), the card shows the raw text you typed instead of a countdown.
  • An empty list shows the “No events” text.
  • With two or more events, the carousel advances every Config.EventInterval milliseconds. Players can also click the dots under the card.
  • Clicking the card acts on the slide currently showing.

The menu text lives in pausemenu/locales/. English (en.lua) and French (fr.lua) are included. Set Config.Locale to the language code to switch.

Locale files only translate the fixed menu labels. These are not translated by the locale files and must be edited in config.lua if you want them in another language:

  • Config.ServerName
  • The name and subtitle of each button in Config.Buttons
  • The title and subtitle of each event in Config.Events

Job, gang and player names come from your framework.

Cash and bank amounts are always written with a $ sign and commas, for example $453,000. This is not changed by the locale.

  1. Copy pausemenu/locales/en.lua to a new file in the same folder. Name it after the language code, for example de.lua.

  2. Open the new file and change the key in the second line from Locales['en'] to your code:

    Locales = Locales or {}
    Locales['de'] = {
    pause = 'PAUSE',
    menu = 'Menu',
    close = 'Schliessen',
    -- ...translate the rest of the values...
    }
  3. Translate the text on the right side of each =. Do not rename the keys on the left.

  4. Save the file as UTF-8, so accents and special characters display correctly.

  5. Set the language in config.lua:

    Config.Locale = 'de'
  6. In the server console, run refresh and then restart pausemenu.

You do not need to register the file anywhere. The resource loads every file in locales/ that ends in .lua.

Any key you leave out falls back to the English text, so a partly translated file still works. If Config.Locale names a language that does not exist, English is used.

Key English text Where it appears
pause PAUSE Large title of the menu
menu Menu Small label next to the title
close Close Close button
tab_home Home Home tab
tab_map Map Map tab
tab_settings Settings Settings tab
tab_tebex Tebex Tebex tab
tab_discord Discord Discord tab
tab_exit Exit Exit tab (closes the menu)
personal Personal Heading of the player data panel
detail_information Detail Information Sub heading of the player data panel
financial Financial Heading of the money section
section_personal Personal Heading of the job, gang and playtime section
cash Cash Cash label
bank Bank Bank label
job Job Job label
gang Gang Gang label
playtime Playtime Playtime label
id ID Label before the player’s server ID
unemployed Unemployed Shown when the job text is empty
no_gang No Gang Shown when the gang text is empty
events Events Title of the events card
no_events No events Shown when Config.Events is empty
starts_in Starts in Before the countdown
live_now Live now Shown after an event’s start date