API, events et hooks

Exports client et serveur de MrPoulpi UI, events, hooks client et serveur, logs Discord et liaison avec un framework maison.

Tous les exports s’appellent avec exports.mrpoulpi_ui:Nom(...). Les exemples d’utilisation sont dans Notifications, Fenêtres et Aide et raccourcis.

Exports client

Fenêtres

client exports.mrpoulpi_ui:OpenUI(data)

Ouvre une fenêtre input, confirm ou choice et donne le focus à l’interface. Une fenêtre déjà ouverte est remplacée (son attente éventuelle reçoit la valeur d’annulation). Renvoie false si Hooks.CanOpen refuse.

Retourboolean

client exports.mrpoulpi_ui:CloseUI()

Ferme la fenêtre et rend la main au joueur. false si aucune fenêtre n’était ouverte.

Retourboolean

client exports.mrpoulpi_ui:ToggleUI(data)

Ferme la fenêtre ouverte, sinon ouvre data.

Retourboolean

client exports.mrpoulpi_ui:IsUIOpen()

true si une fenêtre est ouverte.

Retourboolean

client exports.mrpoulpi_ui:SetUIData(data)

Met à jour la fenêtre ouverte : les champs donnés remplacent les anciens, les autres sont gardés. Le type de fenêtre ne change pas.

Retourboolean

client exports.mrpoulpi_ui:RefreshUI()

Redessine la fenêtre, l’aide et la barre de raccourcis affichées.

Retourboolean (fenêtre ouverte)

client exports.mrpoulpi_ui:Input(data)

Saisie bloquante : attend la réponse du joueur. nil s’il annule. Avec inputType = 'number', renvoie un nombre. À appeler dans un thread (CreateThread).

Retourstring, number ou nil

client exports.mrpoulpi_ui:Confirm(data)

Confirmation bloquante. true seulement si le joueur confirme. Accepte aussi une simple question : Confirm('Supprimer ?').

Retourboolean

client exports.mrpoulpi_ui:Choice(data)

Choix bloquant. Renvoie l’id de l’option et l’option complète, ou nil si le joueur ferme la fenêtre.

Retourid, option ou nil

Actions

client exports.mrpoulpi_ui:RegisterUIAction(name, callback)

Enregistre une action appelée par les boutons dont action = name : callback(payload, context). Supprimée automatiquement à l’arrêt de la ressource qui l’a enregistrée.

Retourboolean

client exports.mrpoulpi_ui:UnregisterUIAction(name)

Supprime une action client.

Retourboolean

Notifications

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

Notification simple. Accepte aussi une table { message, type, duration, id }. Donner un id déjà affiché remplace cette notification.

Retourid

client exports.mrpoulpi_ui:Announce(data)

Notification annonce : logo, nom, badge et message.

Retourid

client exports.mrpoulpi_ui:Media(data)

Notification média : bandeau, visuel carré et légende.

Retourid

client exports.mrpoulpi_ui:RemoveNotification(id)

Retire une notification avant la fin de sa durée.

client exports.mrpoulpi_ui:ClearNotifications()

Retire toutes les notifications.

Aide et raccourcis

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

Affiche l’aide d’interaction « Appuyez sur [E] … ». Accepte aussi une table { key, text, prefix }. prefix remplace « Appuyez sur ».

client exports.mrpoulpi_ui:HideHint()

Masque l’aide.

client exports.mrpoulpi_ui:IsHintVisible()

true si l’aide est affichée.

Retourboolean

client exports.mrpoulpi_ui:SetKeybinds(list)

Affiche la barre de raccourcis : liste de { key, label, active }. Remplace la barre précédente. Une entrée sans key est ignorée.

client exports.mrpoulpi_ui:SetKeybindActive(key, active)

Met en avant (ou non) le raccourci de cette touche. active absent = true. false si aucune barre n’est affichée.

Retourboolean

client exports.mrpoulpi_ui:HideKeybinds()

Masque la barre de raccourcis.

client exports.mrpoulpi_ui:IsKeybindsVisible()

true si la barre de raccourcis est affichée.

Retourboolean

Exports serveur

serveur exports.mrpoulpi_ui:OpenUI(source, data)

Ouvre une fenêtre chez un joueur. Les options server = true de cette fenêtre deviennent les seules actions de menu acceptées pour ce joueur.

serveur exports.mrpoulpi_ui:CloseUI(source)

Ferme la fenêtre d’un joueur et oublie ses actions de menu.

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

Notification simple. source = -1 pour tous les joueurs.

serveur exports.mrpoulpi_ui:Announce(source, data)

Notification annonce. source = -1 pour tous les joueurs.

serveur exports.mrpoulpi_ui:Media(source, data)

Notification média. source = -1 pour tous les joueurs.

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

Affiche l’aide d’interaction chez un joueur.

serveur exports.mrpoulpi_ui:HideHint(source)

Masque l’aide chez un joueur.

serveur exports.mrpoulpi_ui:SetKeybinds(source, list)

Affiche la barre de raccourcis chez un joueur.

serveur exports.mrpoulpi_ui:HideKeybinds(source)

Masque la barre de raccourcis chez un joueur.

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

Enregistre une action serveur : callback(source, payload). options.requirePermission = true exige la permission du menu. Nom de 64 caractères au plus. Supprimée à l’arrêt de la ressource qui l’a enregistrée.

Retourboolean

serveur exports.mrpoulpi_ui:UnregisterServerAction(name)

Supprime une action serveur.

Retourboolean

serveur exports.mrpoulpi_ui:HasPermission(source)

true si le joueur a la permission du menu (Config.Permissions et Hooks.HasPermission).

Retourboolean

Events

Events client, à déclencher depuis le serveur avec TriggerClientEvent ou depuis le client avec TriggerEvent :

Event	Arguments	Effet
`mrpoulpi_ui:open`	`data`	Comme OpenUI.
`mrpoulpi_ui:close`	—	Comme CloseUI.
`mrpoulpi_ui:toggle`	`data`	Comme ToggleUI.
`mrpoulpi_ui:updateData`	`data`	Comme SetUIData.
`mrpoulpi_ui:refresh`	—	Comme RefreshUI.
`mrpoulpi_ui:notify`	`message, type, duration`	Comme Notify.
`mrpoulpi_ui:announce`	`data`	Comme Announce.
`mrpoulpi_ui:media`	`data`	Comme Media.
`mrpoulpi_ui:hint`	`key, text, prefix`	Comme ShowHint ; false à la place de key masque l’aide.
`mrpoulpi_ui:keybinds`	`list`	Comme SetKeybinds ; false masque la barre.

Events locaux émis par la ressource, à écouter avec AddEventHandler côté client :

Event	Arguments	Effet
`mrpoulpi_ui:opened`	`data`	Émis après l’ouverture d’une fenêtre.
`mrpoulpi_ui:closed`	`reason`	Émis après la fermeture. reason : submit, cancel, toggle, event ou manual.

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

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

Le préfixe des events est le nom du dossier de la ressource : ne le renommez pas.

Hooks client

Dans client/hooks.lua :

Hook	Rôle
`Hooks.CanOpen(data)`	Renvoyez false pour bloquer l’ouverture (joueur mort, menotté…).
`Hooks.OnOpen(data)`	Après l’ouverture d’une fenêtre.
`Hooks.OnClose(reason, data)`	Après la fermeture.
`Hooks.OnAction(name, payload, context)`	À chaque action déclenchée par un bouton, avant son callback.
`Hooks.GetPlayerData()`	Données du joueur lues dans le framework.
`Hooks.Notify(message, type, duration)`	Notifications envoyées par la ressource elle-même.
`Hooks.Log(...)`	Logs client, affichés seulement avec Config.Debug.
`Hooks.Setup()`	Au démarrage : enregistre les actions du menu de démonstration.

Le menu de démonstration est défini dans ce fichier (demoActions, enregistrées par Hooks.Setup). Supprimez ou remplacez ces actions si vous changez Config.Menu.

Hooks serveur

Dans server/hooks.lua :

Hook	Rôle
`Hooks.HasPermission(source)`	Permission d’ouvrir le menu, d’après Config.Permissions.
`Hooks.GetMenu(source)`	Menu envoyé au joueur. Par défaut Config.Menu.
`Hooks.CanSeeOption(source, option)`	Filtre les options du menu. Gère le champ ace d’une option.
`Hooks.CanUseAction(source, name, payload)`	Dernier contrôle avant une action serveur. false l’annule.
`Hooks.OnServerAction(source, name, payload)`	Actions server = true du menu qui n’ont pas de RegisterServerAction.
`Hooks.GetCompany(source)`	Entreprise du joueur pour les annonces : renvoie name, data ou nil.
`Hooks.CanAnnounce(source, company, kind, message)`	Dernier contrôle avant une annonce d’entreprise. false l’annule.
`Hooks.Notify(source, message, type, duration)`	Notifications envoyées par le serveur de la ressource.
`Hooks.Log(source, event, data)`	Logs serveur et webhook Discord.

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 = 'Amende', variant = 'warning', action = 'police:fine', server = true }
            }
        }
    end
    return Config.Menu
end

Logs et webhook Discord

Hooks.Log(source, event, data) reçoit les évènements de la ressource :

Event	Quand
`action`	Une action serveur acceptée.
`menu_denied`	Ouverture du menu sans permission.
`action_denied`	Action réservée, sans permission.
`unknown_action`	Action ni enregistrée ni présente dans la dernière fenêtre.
`invalid_payload`	Données refusées (type ou longueur).
`company_announce`	Annonce d’entreprise envoyée.

Avec Config.Debug = true, ils sont écrits dans la console serveur. Pour les recevoir sur Discord, collez l’adresse du webhook en haut de server/hooks.lua :

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

Ce fichier n’est jamais envoyé aux joueurs. Ne mettez pas le webhook dans shared/config.lua.

Framework maison

Avec Config.Framework = 'custom', complétez le bloc custom de server/framework.lua (et de client/framework.lua si vous utilisez Hooks.GetPlayerData) :

Fonction	Retour	Rôle
`init()`	objet ou `true`	Récupérer l’objet du framework.
`getPlayer(object, source)`	joueur ou `nil`	Joueur chargé.
`getIdentifier(player, source)`	string	Identifiant du joueur.
`hasGroup(player, source, group)`	boolean	Le joueur a-t-il ce groupe ?
`getJob(player)`	`{ name, grade }` ou `nil`	Métier et grade (nombre).

Les autres fichiers utilisent seulement Framework.GetPlayer, Framework.GetIdentifier, Framework.HasGroup et Framework.GetJob.

Exports client

Fenêtres

Actions

Notifications

Aide et raccourcis

Exports serveur

Events

Hooks client

Hooks serveur

Menu différent selon le joueur

Logs et webhook Discord

Framework maison