Hooks

Les hooks sont un moyen de modifier le comportement du système d’inventaire. Ils sont enregistrés sur le serveur et peuvent être utilisés pour modifier le comportement du système d’inventaire, par exemple pour empêcher les joueurs de déplacer des items vers un inventaire spécifique. Il y a des exemples de hooks dans le dossier jaksam_inventory/_hooks.

Bonnes pratiques

Utilise des filtres

Utilise toujours les filtres appropriés pour éviter des exécutions de hook inutiles

Sorties anticipées

Utilise des sorties anticipées pour quitter les hooks quand les conditions ne sont pas remplies

Performance

Garde la logique des hooks légère pour ne pas impacter les performances de l’inventaire

Exemples de cas d’usage

Empêcher les joueurs de voler des items ayant le champ de métadonnée sole_owner (par exemple, des items VIP)
Empêcher les joueurs de déplacer des armes de police vers leur inventaire personnel
N’autoriser qu’un seul sac à dos par inventaire de joueur
Fabriquer des items en glissant un item spécifique sur un autre (par exemple glisser du pain sur de la viande pour faire un sandwich)
Bloquer l’utilisation d’un item quand le joueur est menotté ou dans certaines zones
Suivre les statistiques d’utilisation des items et les succès
Empêcher l’utilisation de certains items en véhicule
Ajouter des items de départ aux nouveaux inventaires de joueur lors de leur création
Pré-remplir des poubelles ou planques avec des items aléatoires à leur création

Fonctions de l’API

Enregistrer un hook

exports['jaksam_inventory']:registerHook(eventName, callback, options, priority)

Paramètres

Nom	Type de donnée	Description
`eventName`	string	Le nom de l’event de hook à écouter (voir Events de hook disponibles ci-dessous)
`callback`	function	La fonction à exécuter quand le hook est déclenché
`options`	table	Filtres et options de configuration (voir Paramètre options ci-dessous)
`priority`	number	Priorité d’exécution (les nombres plus élevés s’exécutent en premier, par défaut : 0)

Valeur de retour

Nom	Type de donnée	Description
`hookId`	string	Identifiant unique du hook enregistré (utilisé pour désenregistrer le hook)

Désenregistrer un hook

exports['jaksam_inventory']:unregisterHook(hookId)

Paramètres

Nom	Type de donnée	Description
`hookId`	string	L’identifiant unique retourné lors de l’enregistrement du hook

Désenregistrer tous les hooks d’une resource

exports['jaksam_inventory']:unregisterResourceHooks(resourceName)

Paramètres

Nom	Type de donnée	Description
`resourceName`	string	Nom de la resource pour laquelle désenregistrer tous les hooks

Paramètre options

Le paramètre options accepte une table avec des filtres pour optimiser les performances.

Commun (tous les events)
Filtres d'inventaire
Filtres de transfert

    local options = {
        -- Debug : affiche dans la console quand le hook se déclenche
        print = true,

        -- Ne se déclenche que pour des items spécifiques
        itemNameFilter = {
            bread = true,
            weapon_pistol = true
        },

        -- Ne se déclenche que pour des types d'items spécifiques
        itemTypeFilter = {
            weapon = true,
            currency = true
        }
    }

Pour onItemAdded, onItemRemoved, onInventoryCreated, onPreOpenInventory, onOmnipackTransaction :

    local options = {
        -- Filtre par type d'inventaire (recommandé)
        inventoryTypeFilter = {
            player = true,
            stash = true
        },

        -- Filtre par motifs d'inventaire spécifiques (avancé)
        inventoryFilter = {
            "player:.*",      -- Tous les joueurs
            "stash_police"    -- Planque spécifique
        }
    }

Pour onItemTransferred uniquement :

    local options = {
        -- Filtre l'inventaire source par type
        inventoryFromTypeFilter = { player = true },

        -- Filtre l'inventaire source par motif de nom
        inventoryFromFilter = {
            "player:.*",      -- Tous les joueurs
            "vehicle:123"     -- Véhicule spécifique
        },

        -- Filtre l'inventaire de destination par type
        inventoryToTypeFilter = { stash = true },

        -- Filtre l'inventaire de destination par motif de nom
        inventoryToFilter = {
            "stash_police",   -- Planque spécifique
            "container:.*"    -- Tous les containers
        },

        -- Uniquement les déplacements intra-inventaire (glisser dans le même inventaire)
        intraInventoryOnly = true
    }

Events de hook disponibles

Event	Description
Item ajouté	Se déclenche quand un item est ajouté à un inventaire
Item retiré	Se déclenche quand un item est retiré d’un inventaire
Item transféré	Se déclenche quand un item est transféré entre inventaires
Transaction omnipack	Se déclenche quand un admin crée ou détruit un item via l’inventaire admin
Pre use item	Se déclenche avant qu’un item soit utilisé, peut annuler l’utilisation
Post use item	Se déclenche après qu’un item ait été utilisé, notification uniquement
Inventaire créé	Se déclenche quand un nouvel inventaire est créé
Pre open inventory	Se déclenche avant l’ouverture d’un inventaire secondaire, peut empêcher son ouverture

Comportement des hooks

Priorité

Les nombres plus élevés s’exécutent en premier (par défaut : 0)

Valeurs de retour

return nil ou return true : autorise l’action à continuer.return false, "message", "notifyType" : empêche l’action et arrête l’exécution des hooks suivants. Les paramètres message et notifyType sont optionnels (notifyType peut être "error", "success", "info")

Exception - onPreOpenInventory : le message n’est pas affiché au joueur, car le préchargement le ferait se répéter. Appelle notifyPlayer depuis l’intérieur du hook si tu veux expliquer la raison au joueur.

Compatibilité ox_inventory

Quand la ressource de compatibilité ox_inventory est installée, exports.ox_inventory:registerHook(...) est traduit vers les hooks natifs ci-dessus, les scripts ox_inventory fonctionnent donc sans modification. Les payloads sont remis au format ox, et les noms d’options ox (itemFilter, typeFilter, inventoryFilter, print) sont traduits également.

Hook ox_inventory	Supporté	Hook natif utilisé
`createItem`	Oui	`onItemAdded`
`swapItems`	Oui	`onItemTransferred`
`openInventory`	Oui	`onPreOpenInventory`
`usingItem`	Oui	`onPreUseItem`
`buyItem` / `openShop`	Non	pas encore de hooks de shop
`craftItem`	Non	pas encore de hooks de craft

Enregistrer un hook non supporté affiche un avertissement et retourne nil au lieu de lever une erreur. Trois différences à connaître lors de la migration :

Un hook ox peut seulement autoriser ou bloquer ; il ne peut pas fournir de message personnalisé ni de type de notification. Utilise les hooks natifs pour cela
openInventory hérite de l’exigence d’absence d’état décrite dans onPreOpenInventory
Les inventaires de joueur sont identifiés différemment. Les hooks ox reçoivent l’ID serveur du joueur sous forme de number (inventoryId = 4), comme ox_inventory. Les hooks natifs reçoivent l’identifiant de personnage de jaksam sous forme de string (inventoryId = "char1:35030084..."). Tous les autres types d’inventaire utilisent le même ID string dans les deux cas

General

Inventory

Jobs Creator

Drugs Creator

Doors Creator

Missions Creator

Blips Creator

Farming Creator

Shops Creator

Robberies Creator

Vehicles Keys

Dealerships Creator

Races Creator

Trackers Creator

Easy Allowlist

Billing UI

Luxury Clothes Theft

Bonnes pratiques

Utilise des filtres

Sorties anticipées

Performance

Exemples de cas d’usage

Fonctions de l’API

Enregistrer un hook

Paramètres

Valeur de retour

Désenregistrer un hook

Paramètres

Désenregistrer tous les hooks d’une resource

Paramètres

Paramètre options

Events de hook disponibles

Comportement des hooks

Priorité

Valeurs de retour

Compatibilité ox_inventory

​Bonnes pratiques

Utilise des filtres

Sorties anticipées

Performance

​Exemples de cas d’usage

​Fonctions de l’API

​Enregistrer un hook

​Paramètres

​Valeur de retour

​Désenregistrer un hook

​Paramètres

​Désenregistrer tous les hooks d’une resource

​Paramètres

​Paramètre options

​Events de hook disponibles

​Comportement des hooks

Priorité

Valeurs de retour

​Compatibilité ox_inventory

Bonnes pratiques

Exemples de cas d’usage

Fonctions de l’API

Enregistrer un hook

Paramètres

Valeur de retour

Désenregistrer un hook

Paramètres

Désenregistrer tous les hooks d’une resource

Paramètres

Paramètre options

Events de hook disponibles

Comportement des hooks

Compatibilité ox_inventory