API, hooks et bridges

Exports serveur et client de Multicharacter, commandes, hooks client et serveur, et fonctions à écrire pour brancher un autre framework ou système d’apparence.

Exports serveur

serveur exports.mrpoulpi_multicharacter:Logout(source)

Déconnecte le personnage chargé (sauvegarde par le framework, hook OnLogout) et rouvre la sélection pour ce joueur. Renvoie false si la ressource démarre, si une action est en cours pour ce joueur ou s’il n’a pas de personnage chargé. Fonctionne même avec Features.Relog = false.

Retourboolean

serveur exports.mrpoulpi_multicharacter:AddSlots(sourceOrLicense, amount)

Ajoute amount emplacements bonus en base. sourceOrLicense : ID serveur d’un joueur connecté, ou licence Rockstar (license:xxx ou xxx seul). Un amount négatif en retire. Le bonus est borné de 0 à 255.

Retournouveau bonus (number) ou false

serveur exports.mrpoulpi_multicharacter:SetSlots(sourceOrLicense, amount)

Fixe le bonus en base à amount (0 retire tout bonus). Ne touche ni à Slots.Default, ni aux bonus ACE, ni aux totaux par identifiant.

Retournouveau bonus (number) ou false

serveur exports.mrpoulpi_multicharacter:GetSlots(source)

Nombre d’emplacements débloqués d’un joueur connecté : Slots.Default + bonus ACE + bonus en base, au moins le total de Slots.Identifiers, au plus Config.Slots.Max.

Retournumber

Exports client

client exports.mrpoulpi_multicharacter:IsOpen()

true tant que l’écran de sélection est affiché. Utile pour masquer un HUD ou bloquer un menu pendant la sélection.

Retourboolean

Commandes

Commande	Utilisable	Effet
`/relog`	en jeu, tous les joueurs	Retour à la sélection de personnage. Nom réglable par Config.Features.RelogCommand, désactivable par Config.Features.Relog.
`multichar_slots <id \| license:xxx> <nombre> [set]`	console serveur uniquement	Ajoute <nombre> emplacements bonus au joueur (ou en retire avec un nombre négatif). Avec set, fixe le bonus à <nombre>. Nom réglable par ServerConfig.Slots.Command.

/relog est ouvert à tous. Pour ajouter vos conditions (pas menotté, pas en combat…), désactivez la commande avec Config.Features.Relog = false et appelez l’export :

RegisterNetEvent('mon_menu:changerPersonnage', function()
    local src = source
    if Player(src).state.isCuffed then
        return
    end
    exports.mrpoulpi_multicharacter:Logout(src)
end)

Le personnage est sauvegardé par le framework, comme à une déconnexion normale.

Hooks serveur

Dans config/server.lua :

Hook	Appelé	Erreur dans le hook
`ServerHooks.OnCharacterCreated(source, charId, identity)`	Après la création réussie et le chargement du personnage. identity contient firstname, lastname, birthdate (AAAA-MM-JJ), sex (m ou f), nationality et height.	Interceptée et affichée en console ; le script continue.
`ServerHooks.OnCharacterLoaded(source, charId)`	Après le chargement d’un personnage existant (bouton Jouer ou Apparence).	Interceptée et affichée en console ; le script continue.
`ServerHooks.OnCharacterDeleted(source, charId)`	Après la suppression d’un personnage, une fois les données effacées.	Interceptée et affichée en console ; le script continue.
`ServerHooks.OnLogout(source, charId)`	Après /relog ou l’export Logout, avant la réouverture de la sélection. charId peut être nil si la session n’était pas suivie.	Interceptée et affichée en console ; le script continue.

function ServerHooks.OnCharacterCreated(source, charId, identity)
    print(('%s a créé %s %s'):format(GetPlayerName(source), identity.firstname, identity.lastname))
end

Hooks client

Dans config/client.lua :

Hook	Appelé	Erreur dans le hook
`ClientHooks.OnSelectionOpen()`	À l’ouverture de la sélection, avant la mise en place de la scène. Livré : coupe la synchronisation météo de qb-weathersync et cd_easytime.	Non interceptée : elle interrompt la suite (ouverture, fermeture ou fin de création).
`ClientHooks.OnSelectionClose()`	À la fermeture de la sélection, avant l’apparition. Livré : rétablit la synchronisation météo.	Non interceptée : elle interrompt la suite (ouverture, fermeture ou fin de création).
`ClientHooks.OnSpawned(isNew)`	Après l’apparition et le fondu d’entrée. isNew vaut true pour un personnage qui vient d’être créé (avant l’ouverture de l’éditeur d’apparence).	Interceptée et affichée en console ; le script continue.
`ClientHooks.OnCreatorFinished()`	Quand le joueur a validé l’éditeur d’apparence d’un nouveau personnage. Pas appelé pour le bouton Apparence d’un personnage existant.	Non interceptée : elle interrompt la suite (ouverture, fermeture ou fin de création).

Limites

Une même action répétée trop vite est refusée avec « Patientez un instant » : 1 s pour ouvrir la liste, 1,5 s pour jouer, 2 s pour créer, supprimer ou enregistrer l’apparence. Une seule action est traitée à la fois par joueur.

Bridges

Un bridge relie la ressource à un framework ou à un système d’apparence. Chaque bridge déclare un nom, une priorité et une fonction de détection :

local Framework = { Name = 'custom', Priority = 0 }
Bridge.Framework.custom = Framework

function Framework.Detect()
    return false
end

Framework, côté serveur

Fonction	Retour	Rôle
`Init()`	—	Récupérer l’objet du framework.
`CheckSetup()`	`nil` ou une clé de texte	Facultatif. Signale une installation incorrecte.
`GetIdentifier(source)`	string	Identifiant du propriétaire des personnages.
`GetCharacters(source, owner)`	table	Liste des personnages (format ci-dessous).
`CreateCharacter(source, owner, slot, identity)`	string ou `nil`	Créer et charger le personnage, renvoyer son identifiant.
`LoadCharacter(source, owner, charId)`	boolean	Charger un personnage existant.
`IsLoaded(source)`	boolean	Le joueur a-t-il un personnage chargé ?
`GetCharId(source)`	string ou `nil`	Identifiant du personnage chargé.
`Logout(source)`	—	Sauvegarder et décharger le personnage.
`DeleteCharacter(source, owner, charId)`	boolean	Supprimer le personnage et ses données.
`SaveSkin(source, model, skin)`	boolean	Enregistrer l’apparence.

Chaque personnage renvoyé par GetCharacters contient : id, slot, firstname, lastname, birthdate (AAAA-MM-JJ), sex (m ou f), job ({ name, label, grade }), cash, bank, position ({ x, y, z, w }), model et skin. nationality et height sont facultatifs.

CreateCharacter reçoit identity avec firstname, lastname, birthdate, sex, nationality et height, déjà vérifiés.

Framework, côté client

Fonction	Retour	Rôle
`Init()`	—	Récupérer l’objet du framework.
`WaitLoaded(timeout)`	boolean	Attendre que le client ait reçu les données du personnage.
`OnSpawned(isNew)`	—	Déclencher les événements d’apparition du framework.

Apparence

Fonction	Retour	Rôle
`Apply(model, skin, sex)`	boolean	Appliquer une apparence enregistrée. `false` affiche le ped par défaut.
`Create(sex, done)`	—	Ouvrir l’éditeur à la création ; appeler `done(true)` une fois enregistré.
`Edit(done)`	—	Ouvrir l’éditeur pour un personnage existant.

Pour enregistrer l’apparence, appelez Callback('saveSkin', 15000, model, skin) depuis le bridge.