Hooks and integration
The open files of Kivo Pausemenu do not define any exports or events that other resources call. You connect the menu to other scripts in two ways:
- Hook functions in
pausemenu/framework/open.lua. The menu calls them when a player clicks a button. You write what they do. - Statebag keys listed in
Config.Esc.blockStates. Your own UIs set a key while they are open, and the menu will not open on top of them.
Everything in this page is client side.
How the hook file works
Section titled “How the hook file works”framework/open.lua is loaded first among the client files. It creates the PauseMenu.Framework table and fills it with functions. It is a normal Lua file. Edit it freely and restart the resource.
When a player clicks a button that uses a hook:
- The menu closes. The mouse cursor and keyboard focus are released and the camera goes back to gameplay.
- Your hook function runs.
Because the menu is already closed, your hook can safely open another UI that needs NUI focus. Return values from hooks are ignored.
Hook reference
Section titled “Hook reference”| Function | Called when | Arguments | Default behaviour |
|---|---|---|---|
PauseMenu.Framework.Report() |
The Report card is clicked, if its action is { type = 'framework', value = 'report' }. |
None | Shows a notification asking you to hook it up. |
PauseMenu.Framework.BattlePass() |
The Battle Pass card is clicked, if its action is { type = 'framework', value = 'battlepass' }. |
None | Shows a notification asking you to hook it up. |
PauseMenu.Framework.Event(eventData) |
An event card is clicked and that event has no url. |
eventData: table with title, subtitle, startDate, image, url |
Shows a notification with the event title. |
PauseMenu.Framework.Map() |
The Map card is clicked (with action { type = 'framework', value = 'map' }), or the Map tab is clicked. |
None | Opens the native GTA map. |
PauseMenu.Framework.Settings() |
The Settings tab is clicked. | None | Opens the native GTA settings menu. |
Notes:
- The Map and Settings tabs always call their hooks. The Report, Battle Pass and Map cards call hooks only while their
Config.Buttonsaction is of type'framework'. If you change a card to a'link'action, its hook is not called. - The default Event function starts with
eventData = eventData or {}so it does not fail when no data is passed. Keep that line when you edit it. - Link actions open the player’s browser and do not close the menu. Only hook actions close it.
Helper functions used by the default hooks
Section titled “Helper functions used by the default hooks”Two helper functions are available inside open.lua for opening the Rockstar frontend (the native map and settings screens).
| Function | Purpose |
|---|---|
PauseMenu.OpenNativeFrontend(menuName, togglePause, component) |
Opens a native frontend menu and tells the pause menu to hand ESC to it until it closes. The default hooks use it as PauseMenu.OpenNativeFrontend('FE_MENU_VERSION_MP_PAUSE', false, -1) for the map and PauseMenu.OpenNativeFrontend('FE_MENU_VERSION_LANDING_MENU', false, -1) for settings. The arguments mirror the GTA ActivateFrontendMenu native. |
PauseMenu.ExpectNativeMenu() |
Tells the pause menu that a native frontend menu is about to open. Call it immediately before any code that calls ActivateFrontendMenu itself. |
Examples
Section titled “Examples”Report: events, exports and commands
Section titled “Report: events, exports and commands”Pick the line that matches your report script.
function PauseMenu.Framework.Report() -- A client event: TriggerEvent('myReports:open')
-- An export: -- exports['your_report_script']:OpenReportMenu()
-- A chat command that the report script registers: -- ExecuteCommand('report')endFall back to a message when the other resource is not running:
function PauseMenu.Framework.Report() if GetResourceState('your_report_script') == 'started' then exports['your_report_script']:OpenReportMenu() else notify('Reports are not available right now.') endendnotify is the small helper defined at the top of open.lua. It is a local function, so it is only available in this file.
Battle Pass
Section titled “Battle Pass”function PauseMenu.Framework.BattlePass() -- TriggerEvent('battlepass:open') exports['your_battlepass']:Open()endUse the event name or export that your battle pass script documents. If the script provides a command instead, use ExecuteCommand('battlepass').
Events without a link
Section titled “Events without a link”Set url = '' for the event in Config.Events, then handle the click yourself. This example opens a different script depending on the event title:
function PauseMenu.Framework.Event(eventData) eventData = eventData or {}
if eventData.title == 'Cartel War' then TriggerEvent('cartelwar:openInfo') elseif eventData.title == 'Street Race Night' then exports['racing']:OpenLobbyList() else notify(('~g~[Event]~s~ %s'):format(eventData.title or 'No url set')) endendIf you prefer a link, set url on the event. Then this hook is never called for that event.
Map: your own map script
Section titled “Map: your own map script”A map that opens its own NUI does not need any handoff:
function PauseMenu.Framework.Map() TriggerEvent('myMap:open')endOpening a native map or settings menu
Section titled “Opening a native map or settings menu”The default Map hook uses the native GTA map:
function PauseMenu.Framework.Map() PauseMenu.OpenNativeFrontend('FE_MENU_VERSION_MP_PAUSE', false, -1)endIf another resource opens a Rockstar frontend menu for you (it calls ActivateFrontendMenu inside its own code), call PauseMenu.ExpectNativeMenu() right before it:
function PauseMenu.Framework.Map() PauseMenu.ExpectNativeMenu() exports['your_map_script']:OpenNativeMap()endWithout that call, the pause menu does not know a native screen is opening and does not hand ESC over to it. If no native screen appears within Config.Esc.nativeOpenTimeout milliseconds after ExpectNativeMenu(), the pause menu takes ESC back, so a failed handoff does not leave the menu stuck.
You do not need the handoff for hooks that open a NUI map, a command, or anything that is not a Rockstar frontend menu.
Settings
Section titled “Settings”Replace the native settings screen with your own settings UI:
function PauseMenu.Framework.Settings() exports['your_settings']:Open()endOr send players to the map instead:
function PauseMenu.Framework.Settings() PauseMenu.Framework.Map()endUse another notification system
Section titled “Use another notification system”The default hooks show a GTA feed notification through the local notify function at the top of open.lua. Replace its body to use your server’s notifications. The default messages contain GTA colour codes such as ~y~. Other notification systems do not understand these, so remove them from any message you keep.
ox_lib:
local function notify(msg) TriggerEvent('ox_lib:notify', { description = msg, type = 'inform' })endQBCore and QBX:
local function notify(msg) TriggerEvent('QBCore:Notify', msg, 'primary')endESX:
local function notify(msg) TriggerEvent('esx:showNotification', msg)endOnce all hooks call your real scripts, you no longer need notify and can delete it.
Telling the menu that your UI is open
Section titled “Telling the menu that your UI is open”The menu does not open while another resource holds NUI focus, and it ignores ESC for a short time after any UI releases focus. This covers most UIs without any change. Inventories that publish the invOpen and invBusy statebags are also covered by default.
For a UI that does not hold NUI focus, or when you want an explicit signal, publish a key on LocalPlayer.state while the UI is open, and add that key to Config.Esc.blockStates.
In your own resource (client side):
local function setUiOpen(state) LocalPlayer.state:set('myPhoneOpen', state, false)end
-- when your UI openssetUiOpen(true)
-- when your UI closessetUiOpen(false)
-- make sure the key is cleared if your resource stops while the UI is openAddEventHandler('onResourceStop', function(resource) if resource == GetCurrentResourceName() then setUiOpen(false) endend)In pausemenu/config.lua:
Config.Esc = { -- other options unchanged blockStates = { 'invOpen', 'invBusy', 'myPhoneOpen' },}The third argument false keeps the value on the player’s own client. It is not sent to the server.
Frameworks and data sources
Section titled “Frameworks and data sources”framework/open.lua only controls what the buttons do. Player data (name, cash, bank, job, gang) is supplied for ESX, QBCore and QBX, selected with Config.Framework. There is no open file for adding another framework’s data source. On a server with a different framework, set Config.Framework = 'standalone'. The menu then shows the FiveM player name, zero money and the default job and gang labels. All other features, including the buttons and hooks above, work the same in every mode.
Supporting several scripts in one file
Section titled “Supporting several scripts in one file”If one open.lua has to work with different scripts (for example on several servers), check which resource is running with GetResourceState:
function PauseMenu.Framework.Report() if GetResourceState('esx_report') == 'started' then TriggerEvent('esx_report:open') elseif GetResourceState('qb-report') == 'started' then TriggerEvent('qb-report:open') else notify('No report script is running.') endendThe resource names above are examples. Use the names of the scripts on your server.
