API, events and hooks

MrPoulpi UI client and server exports, events, client and server hooks, Discord logs and bridging an in-house framework.

Every export is called with exports.mrpoulpi_ui:Name(...). Usage examples are in Notifications, Windows and Hint and keybinds.

Client exports

Windows

client exports.mrpoulpi_ui:OpenUI(data)

Opens an input, confirm or choice window and gives focus to the interface. A window already open is replaced (any pending wait receives the cancel value). Returns false if Hooks.CanOpen refuses.

Returnsboolean

client exports.mrpoulpi_ui:CloseUI()

Closes the window and gives control back to the player. false if no window was open.

Returnsboolean

client exports.mrpoulpi_ui:ToggleUI(data)

Closes the open window, otherwise opens data.

Returnsboolean

client exports.mrpoulpi_ui:IsUIOpen()

true if a window is open.

Returnsboolean

client exports.mrpoulpi_ui:SetUIData(data)

Updates the open window: given fields replace the old ones, the others are kept. The window type does not change.

Returnsboolean

client exports.mrpoulpi_ui:RefreshUI()

Redraws the window, the hint and the keybind bar on screen.

Returnsboolean (window open)

client exports.mrpoulpi_ui:Input(data)

Blocking input: waits for the player’s answer. nil if cancelled. With inputType = 'number', returns a number. Call it inside a thread (CreateThread).

Returnsstring, number or nil

client exports.mrpoulpi_ui:Confirm(data)

Blocking confirmation. true only if the player confirms. Also accepts a plain question: Confirm('Delete?').

Returnsboolean

client exports.mrpoulpi_ui:Choice(data)

Blocking choice. Returns the option id and the full option, or nil if the player closes the window.

Returnsid, option or nil

Actions

client exports.mrpoulpi_ui:RegisterUIAction(name, callback)

Registers an action called by buttons with action = name: callback(payload, context). Removed automatically when the resource that registered it stops.

Returnsboolean

client exports.mrpoulpi_ui:UnregisterUIAction(name)

Removes a client action.

Returnsboolean

Notifications

client exports.mrpoulpi_ui:Notify(message, type, duration)

Simple notification. Also accepts a table { message, type, duration, id }. Giving an id already on screen replaces that notification.

Returnsid

client exports.mrpoulpi_ui:Announce(data)

Announcement notification: logo, name, badge and message.

Returnsid

client exports.mrpoulpi_ui:Media(data)

Media notification: banner, square picture and caption.

Returnsid

client exports.mrpoulpi_ui:RemoveNotification(id)

Removes a notification before its time is up.

client exports.mrpoulpi_ui:ClearNotifications()

Removes every notification.

Hint and keybinds

client exports.mrpoulpi_ui:ShowHint(key, text, prefix)

Shows the interaction hint “Press [E] …”. Also accepts a table { key, text, prefix }. prefix replaces “Press”.

client exports.mrpoulpi_ui:HideHint()

Hides the hint.

client exports.mrpoulpi_ui:IsHintVisible()

true if the hint is shown.

Returnsboolean

client exports.mrpoulpi_ui:SetKeybinds(list)

Shows the keybind bar: list of { key, label, active }. Replaces the previous bar. An entry without key is ignored.

client exports.mrpoulpi_ui:SetKeybindActive(key, active)

Highlights (or not) the keybind of that key. Missing active = true. false if no bar is shown.

Returnsboolean

client exports.mrpoulpi_ui:HideKeybinds()

Hides the keybind bar.

client exports.mrpoulpi_ui:IsKeybindsVisible()

true if the keybind bar is shown.

Returnsboolean

Server exports

server exports.mrpoulpi_ui:OpenUI(source, data)

Opens a window for a player. The server = true options of this window become the only menu actions accepted for that player.

server exports.mrpoulpi_ui:CloseUI(source)

Closes a player’s window and forgets its menu actions.

server exports.mrpoulpi_ui:Notify(source, message, type, duration)

Simple notification. source = -1 for every player.

server exports.mrpoulpi_ui:Announce(source, data)

Announcement notification. source = -1 for every player.

server exports.mrpoulpi_ui:Media(source, data)

Media notification. source = -1 for every player.

server exports.mrpoulpi_ui:ShowHint(source, key, text, prefix)

Shows the interaction hint for a player.

server exports.mrpoulpi_ui:HideHint(source)

Hides the hint for a player.

server exports.mrpoulpi_ui:SetKeybinds(source, list)

Shows the keybind bar for a player.

server exports.mrpoulpi_ui:HideKeybinds(source)

Hides the keybind bar for a player.

server exports.mrpoulpi_ui:RegisterServerAction(name, callback, options)

Registers a server action: callback(source, payload). options.requirePermission = true requires the menu permission. Name of 64 characters at most. Removed when the resource that registered it stops.

Returnsboolean

server exports.mrpoulpi_ui:UnregisterServerAction(name)

Removes a server action.

Returnsboolean

server exports.mrpoulpi_ui:HasPermission(source)

true if the player has the menu permission (Config.Permissions and Hooks.HasPermission).

Returnsboolean

Events

Client events, triggered from the server with TriggerClientEvent or from the client with TriggerEvent:

Event	Arguments	Effect
`mrpoulpi_ui:open`	`data`	Same as OpenUI.
`mrpoulpi_ui:close`	—	Same as CloseUI.
`mrpoulpi_ui:toggle`	`data`	Same as ToggleUI.
`mrpoulpi_ui:updateData`	`data`	Same as SetUIData.
`mrpoulpi_ui:refresh`	—	Same as RefreshUI.
`mrpoulpi_ui:notify`	`message, type, duration`	Same as Notify.
`mrpoulpi_ui:announce`	`data`	Same as Announce.
`mrpoulpi_ui:media`	`data`	Same as Media.
`mrpoulpi_ui:hint`	`key, text, prefix`	Same as ShowHint; false instead of key hides the hint.
`mrpoulpi_ui:keybinds`	`list`	Same as SetKeybinds; false hides the bar.

Local events fired by the resource, to listen to with AddEventHandler client side:

Event	Arguments	Effect
`mrpoulpi_ui:opened`	`data`	Fired after a window opens.
`mrpoulpi_ui:closed`	`reason`	Fired after closing. reason: submit, cancel, toggle, event or manual.

AddEventHandler('mrpoulpi_ui:opened', function()
    DisplayRadar(false)
end)

AddEventHandler('mrpoulpi_ui:closed', function(reason)
    DisplayRadar(true)
end)

The event prefix is the resource folder name: do not rename it.

Client hooks

In client/hooks.lua:

Hook	Purpose
`Hooks.CanOpen(data)`	Return false to block opening (dead player, cuffed…).
`Hooks.OnOpen(data)`	After a window opens.
`Hooks.OnClose(reason, data)`	After closing.
`Hooks.OnAction(name, payload, context)`	On every action triggered by a button, before its callback.
`Hooks.GetPlayerData()`	Player data read from the framework.
`Hooks.Notify(message, type, duration)`	Notifications sent by the resource itself.
`Hooks.Log(...)`	Client logs, printed only with Config.Debug.
`Hooks.Setup()`	At startup: registers the demo menu actions.

The demo menu is defined in this file (demoActions, registered by Hooks.Setup). Remove or replace these actions if you change Config.Menu.

Server hooks

In server/hooks.lua:

Hook	Purpose
`Hooks.HasPermission(source)`	Permission to open the menu, from Config.Permissions.
`Hooks.GetMenu(source)`	Menu sent to the player. Config.Menu by default.
`Hooks.CanSeeOption(source, option)`	Filters the menu options. Handles the ace field of an option.
`Hooks.CanUseAction(source, name, payload)`	Last check before a server action. false cancels it.
`Hooks.OnServerAction(source, name, payload)`	Menu server = true actions that have no RegisterServerAction.
`Hooks.GetCompany(source)`	Player company for announcements: returns name, data or nil.
`Hooks.CanAnnounce(source, company, kind, message)`	Last check before a company announcement. false cancels it.
`Hooks.Notify(source, message, type, duration)`	Notifications sent by the resource server side.
`Hooks.Log(source, event, data)`	Server logs and Discord webhook.

function Hooks.GetMenu(source)
    local job = Framework.GetJob(source)
    if job and job.name == 'police' then
        return {
            type = 'choice',
            title = 'LSPD',
            options = {
                { id = 'fine', label = 'Fine', variant = 'warning', action = 'police:fine', server = true }
            }
        }
    end
    return Config.Menu
end

Logs and Discord webhook

Hooks.Log(source, event, data) receives the resource events:

Event	When
`action`	A server action was accepted.
`menu_denied`	Menu opening without permission.
`action_denied`	Restricted action, without permission.
`unknown_action`	Action neither registered nor in the last window.
`invalid_payload`	Data refused (type or length).
`company_announce`	Company announcement sent.

With Config.Debug = true, they are printed in the server console. To receive them on Discord, paste the webhook address at the top of server/hooks.lua:

local webhook = 'https://discord.com/api/webhooks/…'

This file is never sent to players. Do not put the webhook in shared/config.lua.

In-house framework

With Config.Framework = 'custom', fill in the custom block of server/framework.lua (and of client/framework.lua if you use Hooks.GetPlayerData):

Function	Returns	Role
`init()`	object or `true`	Get the framework object.
`getPlayer(object, source)`	player or `nil`	Loaded player.
`getIdentifier(player, source)`	string	Player identifier.
`hasGroup(player, source, group)`	boolean	Does the player have this group?
`getJob(player)`	`{ name, grade }` or `nil`	Job and grade (number).

The other files only use Framework.GetPlayer, Framework.GetIdentifier, Framework.HasGroup and Framework.GetJob.

Client exports

Windows

Actions

Notifications

Hint and keybinds

Server exports

Events

Client hooks

Server hooks

A different menu per player

Logs and Discord webhook

In-house framework