Bridge d'inventaire CDT Admin — cdt_admin

La configuration simple est désormais regroupée dans config/inventory.lua : choix du fournisseur, ressource, images, capacités et appels personnalisés serveur/client. Voir INVENTORY_CONFIGURATION.md pour le guide acheteur. Les sections ci-dessous détaillent les APIs natives et les adaptations avancées conservées.

État de l'intégration

Raccordements ESX et fournisseurs

Le fournisseur ak47 détecte la ressource réelle ak47_inventory, y compris avec ESX. Il prend en charge le catalogue Items, la lecture GetInventoryItems, la capacité CanAddItem et les dons/retraits AddItem / RemoveItem. Le retrait transmet le slot puis les métadonnées, dans l'ordre publié par l'éditeur. Les exports sans retour sont confirmés par une lecture du nombre d'objets après modification.

Source officielle : intégration publique AK47. Le bridge conserve les opérations d'administration dans le panneau CDT. Le bouton d'inspection du profil ouvre désormais ce même panneau pour tout fournisseur dépourvu de contrôle serveur complet des transferts, y compris le natif ESX et AK47. Consultation, dons et retraits fonctionnent ainsi sans ouvrir une interface secondaire non protégée : permission, hiérarchie, motif, snapshot et anti-rejeu sont contrôlés par server/inventory_panel.lua. L'inspection est journalisée après une lecture réussie ; les mutations ne sont journalisées qu'après confirmation. Le panneau conserve son ouverture et sa fermeture habituelles dans CDT, sans exiger une API de fermeture fournisseur. L'ouverture personnelle et la fermeture native AK47 exigent un adaptateur ; l'inspection native d'un autre joueur reste bloquée sans raccordement serveur du contrôle et de la confirmation des transferts. Le poids maximal, le nombre de slots et le chemin d'images ne sont pas inventés : configurer les convars ci-dessous ou fournir un adaptateur pour obtenir les valeurs propres à la version. ak47_qb_inventory est un autre nom et n'est pas assimilé automatiquement.

TGIANN cible maintenant l'API Ox de la version 2.0.0 publiée le 9 septembre 2026 : catalogue, inventaire, slots et signatures de retrait Ox (métadonnées avant slot), ainsi que hooks registerHook / removeHooks. Les anciennes versions restent configurables avec family='qb', hook='RegisterHook' et unhook='RemoveHooks' dans config/inventory.lua. Source : changelog officiel TGIANN 2.0.0. Core vérifie désormais sa capacité avec canCarry avant l'ajout, suivant l'API officielle actuelle. Les signatures Wasabi utilisées dans CDT suivent les exports actuels et ses hooks et événements. Ces hooks ne publient toujours pas une confirmation serveur après mutation attribuée au demandeur : le panneau CDT couvre l'inspection à leur place.

Les fournisseurs déjà présents Ox, Quasar, TGIANN, Origen, Core, CodeM Supreme V2 et Wasabi restent indépendants du framework pour leurs appels directs. Le natif ESX est sélectionné seulement si aucun fournisseur réel n'est actif et si ESX.GetConfig().CustomInventory est désactivé. Les objets ESX natifs n'ont pas les métadonnées et les slots persistants d'Ox. Sources : ESX 1.15.2, exports Quasar.

Le code du menu utilise désormais server/inventory_bridge.lua et client/inventory_bridge.lua. Les permissions, callbacks NUI, motifs, jetons anti-rejeu et journaux des dons/retraits conservent leurs contrats actuels.

Ce bridge n'est pas une certification de compatibilité complète avec les sept produits commerciaux. Les ressources commerciales ne sont pas incluses dans la livraison. Les tests des autres fournisseurs utilisent des doubles des API documentées. Les versions publiées ne précisent pas toujours un numéro de version. Le bridge cible les API publiques consultées à la date indiquée ci-dessous. Aucune ressource commerciale n'est nécessaire pour écrire ces appels ; leur installation reste nécessaire uniquement pour une validation réelle dans FiveM.

Fournisseur	Ressource	Raccordement natif	Travail restant pour la parité complète
Ox	`ox_inventory`	Catalogue, lecture, slots, dons/retraits, ouvertures, contrôle et événement après transfert du fork installé	Validation en jeu après redémarrage
Quasar	`qs-inventory`	GetItemList, GetInventory, AddItem, RemoveItem, CanCarryItem	Ouverture/fermeture, roue d'armes, capacités exactes, contrôle et notification après transfert dans les fichiers modifiables
TGIANN 2.0.0	`tgiann-inventory`	API Ox actuelle, catalogue, inventaire, slots, dons/retraits, capacité, hooks avant transfert ; inspection via panneau CDT	Notification serveur après transfert pour l'interface native
Origen	`origen_inventory`	Items (documenté dans l'intégration Origen Reports), getInventory/getItems, GetTotalWeight, dons/retraits, hooks avant transfert, ouverture personnelle, CloseInventory, ouverture par identifiant	Ouverture forcée joueur sans restriction non explicitée ; notification après transfert
Core	`core_inventory`	Catalogue, contenu, dons/retraits, canCarry, retrait exact par identifiant de pile, inspection via panneau CDT	Contrôle et notification après transfert pour l'interface native ; contenus annexes à vérifier
AK47	`ak47_inventory`	Catalogue, slots, métadonnées, dons/retraits, capacité, inspection via panneau CDT	Interface native, capacités exactes et images selon version
CodeM Supreme V2	`codem-inventoryv2`	API Ox documentée, chemin des images, hooks avant transfert, fermeture via ox_inventory:closedInventory	Notification de résultat d'un transfert attribuée à son auteur
Wasabi	`wasabi_inventory`	API Ox documentée, hooks avant transfert, événement serveur de fermeture	Notification après transfert et vérification des formats dans la version installée

L'ouverture de l'inventaire d'un autre joueur avec un fournisseur alternatif reste refusée tant que son raccordement serveur des transferts n'est pas prêt. Cela évite de rendre modifiable un inventaire qu'un admin doit seulement lire, ou de perdre la journalisation des transferts réussis. Aucun faux succès n'est renvoyé lorsqu'un export manque. Quasar ne dispose pas encore d'une ouverture personnelle native vérifiée dans ce bridge.

Sélection

Adapter toutes les opérations depuis CDT Admin

Un fichier central suffit pour les intégrations simples ; les deux autres restent disponibles pour les adaptations avancées, sans modifier le menu ni ses règles métier :

config/inventory.lua : choix du fournisseur, noms des ressources, chemins d'images, capacités et appels personnalisés par export/événement. Les champs omis conservent les valeurs du fournisseur natif.
config/inventory_server.lua : catalogue, inventaires, slots, dons/retraits, ouverture/fermeture, identification des joueurs et hooks serveur.
config/inventory_client.lua : catalogue client, ouverture/fermeture, confirmation de l'état et roue des armes.

Les adaptateurs sont indexés par clé (qs, tgiann, etc.) ou nom de ressource. Les fonctions omises utilisent les appels natifs du bridge. Pour un nouveau fournisseur, fournir toutes les opérations nécessaires. Les formats de retour sont décrits dans la section des adaptateurs ci-dessous. Les fichiers serveur ne sont pas distribués aux clients. Redémarrer cdt_admin après modification.

Exemple d'une ressource renommée :

-- config/inventory.lua
return { providers = {
    tgiann = {resource='mon_inventaire', images='nui://mon_inventaire/images'},
} }

Le fournisseur reste identifié par tgiann, mais tous les appels ciblent mon_inventaire. Un fournisseur supplémentaire utilise une nouvelle clé avec au minimum resource et images, puis ses adaptateurs serveur et client.

Pour les transferts, l'adaptateur serveur peut définir installTransfers(provider, lifecycle). Il connecte les callbacks serveur fiables du fournisseur à lifecycle.before(payload) (refus = false, sinon jeton) puis lifecycle.after(token, success) après l'opération réelle. Le format du payload et les garanties des jetons sont ceux des exports décrits ci-dessous. Il doit retourner une fonction qui désinscrit les callbacks ; cela active l'inspection native. En cas d'erreur ou d'absence de fonction de nettoyage, l'inspection reste bloquée. Le nettoyage s'exécute à l'arrêt ou au changement du fournisseur, et à l'arrêt de CDT Admin.

registerHook(event, callback) et removeHook(id) permettent de remplacer les hooks natifs ; les deux fonctions sont nécessaires. playerId(id, kind) traduit les identifiants du fournisseur en source FiveM. Cette configuration permet de raccorder une API différente depuis CDT Admin ; elle ne crée pas un événement de réussite absent du fournisseur. Ne jamais confirmer un transfert à partir d'un événement envoyé par un client.

Dans server.cfg, avant le démarrage de cdt_admin :

setr cdt_admin:inventory "auto"

Valeurs : auto, esx, ox, qs, tgiann, origen, core, codem, wasabi, ak47, ou le nom exact de la ressource ci-dessus. Auto n'accepte qu'un fournisseur réel démarré. L'énumération des ressources évite de confondre provide 'ox_inventory' avec l'installation réelle d'Ox. En présence de plusieurs fournisseurs, auto refuse de choisir arbitrairement. Les ressources renommées ne sont pas prises en charge par défaut, mais peuvent être déclarées dans config/inventory.lua. L'ancien CodeM V1 n'est pas CodeM Supreme V2.

Les chemins d'images peuvent varier selon la version et se configurent par :

setr cdt_admin:inventoryImages "nui://nom_ressource/chemin/images"

Ox conserve inventory:imagepath. CodeM utilise son export imagePath. Les images fournies par les items et leurs métadonnées sont conservées.

Les fournisseurs qui ne renvoient pas les capacités peuvent utiliser des valeurs fixes, uniquement si elles correspondent réellement à la configuration du serveur :

set cdt_admin:inventorySlots "30"
set cdt_admin:inventoryMaxWeight "30000"

Ces valeurs ne conviennent pas à des capacités variables par joueur : fournir dans ce cas un adaptateur GetInventory. La valeur zéro signifie que la capacité n'a pas été fournie ; ce n'est pas une capacité inventée.

Raccordement serveur d'une version commerciale

Cette section décrit une extension facultative pour les capacités que les API publiques ne couvrent pas. Elle ne fait pas partie du raccordement automatique basé sur la documentation. En particulier, les hooks swapItems consultés peuvent annuler une tentative mais ne donnent pas son résultat après exécution. CodeM documente ox_inventory:updateInventory(source, items) côté serveur ; cet événement confirme une modification, sans identifier l'opération, son auteur ni les deux inventaires impliqués. Il ne suffit donc pas à reproduire exactement le journal de transferts de CDT Admin. Les événements côté client ne constituent pas une preuve serveur utilisable pour ce journal.

Il n'existe actuellement pas de raccordement automatique documenté garantissant la parité complète des sept alternatives. Supprimer le blocage de l'inspection native perdrait une fonctionnalité demandée : le contrôle et le journal des transferts réussis. Le panneau CDT de consultation/don/retrait conserve quant à lui ses contrôles et ses journaux via les opérations serveur du bridge.

Les exports suivants sont locaux au serveur, sans événements réseau. Seule la ressource du fournisseur sélectionné est autorisée à les appeler.

Dans le gestionnaire serveur qui effectue réellement un transfert :

-- Adapter les identifiants et la pile depuis les données validées du serveur,
-- jamais depuis un payload client accepté sans vérification.
local token = exports.cdt_admin:CanInventoryTransfer({
    source = actorSource,
    fromInventory = fromInventoryId,
    toInventory = toInventoryId,
    fromType = fromInventoryType,
    toType = toInventoryType,
    fromSlot = validatedItem,
    count = validatedCount,
    action = validatedAction,
})
if token == false then
    -- Retourner le refus avec le mécanisme habituel du fournisseur.
    return false
end

-- Ici : opération originale du fournisseur, inchangée.
-- Après sa fin, notifier son résultat réel, y compris un refus.
exports.cdt_admin:InventoryTransferCommitted(token, operationSucceeded == true)

Les tokens sont associés au fournisseur, consommables une fois, expirent après 30 secondes et disparaissent à l'arrêt de la ressource. Un échec n'est jamais journalisé comme une réussite. L'auteur et la cible staff sont capturés avant les opérations asynchrones. Il faut raccorder toutes les branches : déplacement, empilement, échange, division, don et dépôt. Un hook avant opération seul ne constitue pas une preuve de réussite.

Après avoir raccordé ces branches dans le fournisseur, il peut enregistrer :

exports.cdt_admin:RegisterInventoryAdapter({ transfersReady = true })

Ne pas activer cette propriété avant le raccordement effectif. Un redémarrage de cdt_admin efface les adaptateurs : le fournisseur doit les réenregistrer sur onResourceStart de cdt_admin, ainsi qu'à son propre démarrage. Cette inscription doit venir du fournisseur lui-même, pas d'une ressource intermédiaire.

Un adaptateur serveur peut aussi fournir Items, GetInventory, GetSlot, AddItem, RemoveItem, forceOpenInventory, openOwn et close. Il n'est nécessaire que lorsque la version diffère du raccordement natif. Les noms et paramètres reprennent ceux de server/inventory_bridge.lua. Items(name?) renvoie la définition ou le registre ; GetInventory(source) renvoie {items, weight, maxWeight, slots} avec des items normalisés {slot, name, label, count, metadata, weight, image?, bridgeId?}. Chaque pile a un slot numérique distinct et une identité stable. Les mutations renvoient un booléen attestant l'effet réel. forceOpenInventory renvoie l'identifiant de l'inventaire réellement ouvert, ou nil avec une erreur. openOwn renvoie true seulement après confirmation de l'ouverture.

Le fournisseur peut enregistrer côté client RegisterInventoryClientAdapter({Items, openInventory, close, isOpen, weaponWheel}) pour les fonctions absentes ou différentes de son API native. Les fonctions doivent confirmer l'état réel, notamment openInventory et isOpen. Les autorisations restent toujours côté serveur.

Références des raccordements

Validation

Tests locaux : tests/inventory-config.lua, tests/inventory-bridge.lua, tests/inventory-bridge-client.lua, tests/inventory-panel.lua, tests/assets.lua, tests/integrations.lua, tests/gameplay.lua, tests/player-self-actions.lua, tests/entities-client.lua, plus vérification de syntaxe Lua et du panneau NUI d'inventaire. Ils vérifient notamment les différences d'arguments, les retours void, les piles identiques avec métadonnées différentes, les identifiants exacts Core, les permissions, les refus, l'anti-rejeu et la sélection réelle des ressources. Ils ne remplacent pas des tests dans FiveM avec chaque produit installé.

Les références et signatures ci-dessus décrivent les raccordements présents dans CDT ; elles ne certifient pas les dernières versions des produits tiers. Les fichiers tests/ cités appartiennent au dépôt de développement et ne sont pas inclus dans le ZIP.

← Tous les guides