Configuration
All settings are in pausemenu/config.lua. Text in the menu comes from pausemenu/locales/*.lua. Restart the resource after any change:
restart pausemenuJump to a section:
- General
- Player count
- ESC handling
- Event and image settings
- Links
- Buttons
- Camera
- Vehicle camera
- Emotes
- Discord avatars
- Playtime
- Events
- Locales and adding a language
General
Section titled “General”| 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.
What each framework value shows
Section titled “What each framework value shows”| 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.
Player count
Section titled “Player count”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. |
Choosing a player count source
Section titled “Choosing a player count source”| 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. KeepConfig.PlayerCountIntervalabove0when you use'framework'. - With
'native', the interval has little effect because joins and leaves already refresh the count.
ESC handling
Section titled “ESC handling”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 and Settings handoff
Section titled “The Map and Settings handoff”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.
Event and image settings
Section titled “Event and image settings”| 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.
Buttons
Section titled “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.
Button actions
Section titled “Button actions”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.
Camera
Section titled “Camera”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.
Vehicle camera
Section titled “Vehicle camera”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.
Emotes
Section titled “Emotes”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.
Discord avatars
Section titled “Discord avatars”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:
Config.Discord.enabledistrue.- The player has a Discord identifier linked to their FiveM session.
- A bot token is set (in
server.cfgorconfig.lua). - 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.
Playtime
Section titled “Playtime”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
identifierTypelater, 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
logIntervalif you restart the resource often.
Events
Section titled “Events”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 4hwhen more than a day is left,Starts in 5h 20mwhen under a day, andStarts in 12mwhen 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
startDateis not inDD-MM-YYYYform (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.EventIntervalmilliseconds. Players can also click the dots under the card. - Clicking the card acts on the slide currently showing.
Locales and adding a language
Section titled “Locales and adding a language”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
nameandsubtitleof each button inConfig.Buttons - The
titleandsubtitleof each event inConfig.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.
Add a language
Section titled “Add a language”-
Copy
pausemenu/locales/en.luato a new file in the same folder. Name it after the language code, for examplede.lua. -
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...} -
Translate the text on the right side of each
=. Do not rename the keys on the left. -
Save the file as UTF-8, so accents and special characters display correctly.
-
Set the language in
config.lua:Config.Locale = 'de' -
In the server console, run
refreshand thenrestart 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.
All locale keys
Section titled “All locale keys”| 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 |
