Intégrations

cxg-tattoos peut se connecter à différents frameworks pour facturer les achats et vérifier les permissions d’administration. L’intégration d’apparence réapplique les tatouages enregistrés lorsque le personnage charge ou change de skin. Chaque partie se configure séparément.

Consultez aussi Introduction, Installation, Configuration, Catalogue et Interface.

Frameworks disponibles

Système	Identifiant de configuration	Ressource par défaut	Paiements	Permissions
Qbox	`qbx`	`qbx_core`	Oui	Oui
QBCore	`qbcore`	`qb-core`	Oui	Oui
ESX	`esx`	`es_extended`	Oui	Oui
Sans framework	`standalone`	Sans objet	Callback personnalisé ou achats gratuits	ACE ou vérification personnalisée

Avec auto, la ressource détecte Qbox, QBCore ou ESX s’ils sont démarrés ; si aucun n’est trouvé, elle utilise standalone. Vous pouvez choisir le framework lorsque le serveur en exécute plusieurs ou utilise un autre nom de ressource :

Code

Config.Purchases.framework = 'qbx' -- auto | qbx | qbcore | esx | standalone
Config.Purchases.resources.qbx = 'qbx_core'
Config.Purchases.accounts = { 'cash', 'bank' }
Config.Purchases.esxAccountMap.cash = 'money'
Config.Purchases.esxAccountMap.bank = 'bank'
Config.Purchases.allowFreePurchases = false

Les comptes sont vérifiés dans l’ordre indiqué. Le paiement est prélevé sur un seul compte ; si son solde est insuffisant, le suivant est essayé. Dans ESX, esxAccountMap traduit cash par le nom de compte money.

Config.Purchases.reason et refundReason indiquent le motif des opérations pour les providers qui le prennent en charge. Leurs valeurs initiales sont tattoo-purchase et tattoo-purchase-refund. L’option allowFreePurchases permet d’ignorer le paiement dans l’adaptateur standalone ; elle ne rend pas gratuits les achats des autres frameworks.

Paiements sans framework

En mode standalone, reliez tryCharge et refund à la ressource d’économie de votre serveur. Les deux callbacks sont nécessaires pour accepter les achats : le remboursement permet de rendre le paiement si l’enregistrement du tatouage échoue.

Code

Config.Purchases.framework = 'standalone'
Config.Purchases.standalone.tryCharge = function(source, totalAmount, context)
    -- Sustituye esta llamada por la API de economía de tu servidor.
    local charged, receipt = MyEconomy.charge(source, totalAmount, context)
    if charged then
        return true, receipt
    end
    return false, 'No tienes saldo suficiente.'
end

Config.Purchases.standalone.refund = function(source, totalAmount, context, receiptData)
    -- Usa receiptData para devolver el mismo cobro aprobado.
    return MyEconomy.refund(source, totalAmount, receiptData) == true
end

MyEconomy représente l’API de votre serveur ; remplacez-le par son nom et ses appels réels. Pour autoriser intentionnellement les achats gratuits, définissez allowFreePurchases = true.

Les adaptateurs de paiement exposent isAvailable(settings), charge(source, amount, context, settings) et refund(source, amount, context, settings). Un paiement approuvé doit conserver le reçu dans context.paymentReceipt ; cxg-tattoos s’en sert pour envoyer tout remboursement au même système de paiement. Pour une économie personnalisée, les callbacks standalone tryCharge et refund constituent la méthode directe de configuration.

Permissions d’administration

Les permissions sont vérifiées côté serveur pour ouvrir et utiliser le panneau d’administration. Masquer ou modifier l’interface client n’accorde aucun accès.

La configuration initiale utilise le framework détecté et ACE comme solution de secours :

Code

Config.Permissions = {
    framework = 'auto', -- auto | qbx | qbcore | esx | standalone
    mode = 'hybrid',    -- framework | ace | hybrid | custom
    acePrefix = 'cxg-tattoos.',
    resources = {
        qbx = 'qbx_core',
        qbcore = 'qb-core',
        esx = 'es_extended',
    },
    bindings = {
        admin = {
            ace = { 'cxg-tattoos.admin', 'group.admin', 'admin' },
            qbx = { 'god', 'admin', 'group.admin' },
            qbcore = { 'god', 'admin', 'group.admin' },
            esx = { 'superadmin', 'admin' },
        },
    },
}

Le mode framework consulte les rôles du framework. ace utilise les entrées ACE du binding. hybrid autorise l’une ou l’autre de ces méthodes. En mode standalone, l’autorisation par framework n’est pas disponible ; configurez ACE ou une vérification personnalisée.

Par exemple, pour autoriser les membres du principal ACE group.admin :

Code

add_ace group.admin cxg-tattoos.admin allow

Pour déléguer la décision à votre propre système, utilisez mode = 'custom'. Le callback reçoit l’identifiant du joueur, la permission, le contexte de l’opération et le binding configuré ; seule la valeur booléenne true autorise l’accès :

Code

Config.Permissions.mode = 'custom'
Config.Permissions.custom = {
    hasPermission = function(source, permission, context, binding)
        return exports.my_permissions:hasPermission(source, permission) == true
    end,
}

Adaptez my_permissions à l’API installée sur votre serveur. Si le callback est absent, échoue ou renvoie une autre valeur, l’accès est refusé.

La commande qui ouvre le panneau se configure également. permission doit correspondre à une clé de Config.Permissions.bindings :

Code

Config.AdminCommand.enabled = true
Config.AdminCommand.name = 'tattooadmin'
Config.AdminCommand.permission = 'admin'

Avec ces valeurs, la permission admin protège la commande /tattooadmin et les actions administratives. Définissez enabled = false pour désactiver la commande ; la permission reste vérifiée par les autres voies d’administration.

Fichiers d’intégration modifiables

Les bridges modifiables regroupent les connexions aux systèmes externes. Pour une permission ou un paiement personnalisé, il est préférable de configurer les callbacks expliqués ci-dessus. Si vous adaptez un bridge existant, conservez son contrat :

Fichier ou groupe	Utilisation	Contrat de l’adaptateur
`bridge/permissions/server.lua`	Sélection du framework et application du mode `framework`, `ace`, `hybrid` ou `custom`	`TattooPermissions.Has(source, permission, context)` renvoie `true` uniquement si l’accès est autorisé
`bridge/permissions/registry.lua`	Enregistrement et utilitaires communs de permissions	`TattooPermissionBridge.register(name, adapter)`
`bridge/permissions/qbx.lua`, `qbcore.lua`, `esx.lua`, `standalone.lua`	Vérifications pour chaque framework ou mode sans framework	`isAvailable(settings)` et `hasPermission(source, binding, settings, permission)` ; accepte un `context` supplémentaire en cas d’adaptation
`bridge/payments/server.lua`	Sélection du provider, paiement et remboursement	`Config.TryChargePlayer(source, totalAmount, context)` et `Config.RefundPlayer(source, totalAmount, context)`
`bridge/payments/registry.lua`	Enregistrement et utilitaires communs de paiement	`TattooPaymentBridge.register(name, adapter)` et utilitaires de reçus
`bridge/payments/qbx.lua`, `qbcore.lua`, `esx.lua`, `standalone.lua`	Opérations de paiement par framework ou callbacks personnalisés	`isAvailable(settings)`, `charge(...)` et `refund(...)`
`bridge/appearance.lua`	Événements de chargement de skin et demande des tatouages enregistrés	Demande la liste du personnage et l’applique une fois le chargement de l’apparence terminé

Le callback de permission reçoit également context comme cinquième argument lorsqu’il est appelé par le bridge. Le registre contient les providers inclus (qbx, qbcore, esx, standalone) ; les options personnalisées ne nécessitent pas l’ajout d’un autre provider.

Dans un adaptateur de paiement, conservez l’enregistrement du reçu avec TattooPaymentBridge.setReceipt(context, provider, account, amount, identifier, data). Le remboursement doit vérifier le même provider et le même montant avec getReceipt(context, provider, amount), puis marquer le reçu comme remboursé une fois le remboursement confirmé. Adaptez le fichier du provider que vous utilisez déjà ; pour une intégration personnalisée sans modifier les adaptateurs, utilisez les callbacks standalone.

Apparence et chargement du personnage

La ressource écoute les événements habituels de illenium-appearance, fivem-appearance, QBCore, ESX et spawnmanager, puis récupère et réapplique les tatouages enregistrés. Dans Qbox, la configuration d’aperçu multicharacter utilise playerskins.skin pour afficher les tatouages enregistrés lors de la sélection du personnage.

Si votre système d’apparence utilise un autre événement, demandez l’application une fois le chargement du skin terminé :

Code

TriggerServerEvent('cxg-tattoos:fetchMyTattoos')

L’événement renvoie au client les tatouages du personnage actuel. N’envoyez pas la liste depuis une source choisie par le joueur : la propriété est résolue et validée côté serveur.

L’aperçu multicharacter de Qbox se règle avec ces champs :

Code

Config.QbxMulticharacterPreview.enabled = true
Config.QbxMulticharacterPreview.resource = 'qbx_core'
Config.QbxMulticharacterPreview.playerskinsTable = 'playerskins'
Config.QbxMulticharacterPreview.playersTable = 'players'
Config.QbxMulticharacterPreview.syncExistingOnStart = true

enabled active l’intégration ; resource indique le nom de la ressource Qbox installée. playerskinsTable et playersTable identifient les tables d’apparence et de personnages utilisées par cette installation. syncExistingOnStart permet de synchroniser au démarrage de cxg-tattoos les tatouages déjà enregistrés, afin qu’ils apparaissent également dans la sélection multicharacter. Si votre serveur a renommé les tables, mettez à jour ces deux champs. Il n’est pas nécessaire de modifier qbx_core.