Accueil › Documentation › Hooks serveur · origen_inventory

Hooks serveur · origen_inventory

Les hooks permettent à d’autres ressources de s’abonner aux événements de l’inventaire côté serveur et, soit de consulter les données, soit de les modifier ou d’annuler l’action en renvoyant false.

Le système de hooks est exposé via deux exports, registerHook et removeHooks, et il est symétrique avec l’API de hooks côté client.

API

registerHook(event, callback, options?) → string (id)

Enregistre un hook serveur. Renvoie le hookId interne afin que tu puisses le supprimer plus tard.

local hookId = exports.origen_inventory:registerHook('createItem', function(payload)
    return payload.metadata
end)

Filtres (options)

exports.origen_inventory:registerHook('swapItems', function(payload)
    -- only fires for these inventories / items / types
end, {
    itemFilter      = { tosti = true, water_bottle = true },
    inventoryFilter = { '^stash%-', '^trunk%-' },
    typeFilter      = { player = true, stash = true },
    debugger        = true, -- prints execution time and resource origin
})

removeHooks(id?) → void

Supprime les hooks appartenant à la ressource appelante. Passe un id pour supprimer un seul hook, ou omets-le pour supprimer tous les hooks enregistrés par la ressource.

exports.origen_inventory:removeHooks(hookId) -- single hook
exports.origen_inventory:removeHooks()        -- every hook from this resource

Contrat d’annulation

La plupart des hooks serveur respectent un contrat d’annulation :

• Renvoie false → l’inventaire abandonne l’action (l’objet n’est pas ajouté, échangé, acheté, etc.).
• Renvoie autre chose (ou rien) → l’action se poursuit normalement.

La seule exception est createItem, qui est mutant : tu dois renvoyer la table metadata (éventuellement modifiée).

Référence des hooks

createItem

Déclenché lorsqu’un objet est ajouté à un inventaire et que ses métadonnées sont en cours d’initialisation. Mutant : doit renvoyer metadata.

Données reçues

exports.origen_inventory:registerHook('createItem', function(payload)
    if payload.item.name == 'paperbag' and not payload.metadata.bagId then
        payload.metadata.bagId = math.random(1000, 9999)
    end
    return payload.metadata -- MUST return metadata
end)

itemCreated

Déclenché après l’ajout d’un objet à un inventaire. Lecture seule / observation : la valeur renvoyée est ignorée.

Données reçues

exports.origen_inventory:registerHook('itemCreated', function(payload)
    print(('Item %s x%s added to %s'):format(payload.item.name, payload.count, payload.inventoryId))
end)

itemUsed

Déclenché après l’utilisation réussie d’un slot. Uniquement pour l’observation.

Données reçues

exports.origen_inventory:registerHook('itemUsed', function(payload)
    if payload.item.name == 'lockpick' then
        -- log lockpick usage
    end
end)

useSlot

Déclenché avant l’utilisation d’un slot. Renvoie false pour annuler l’utilisation.

Données reçues

exports.origen_inventory:registerHook('useSlot', function(payload)
    if payload.item.name == 'weapon_pistol' and IsRestrictedZone(payload.source) then
        return false -- cancel use
    end
end)

swapItems

Déclenché avant tout déplacement / échange / fractionnement / don entre deux inventaires (de joueur à joueur, transferts de stash, coffre, drops, etc.). Renvoie false pour annuler le transfert.

Données reçues

exports.origen_inventory:registerHook('swapItems', function(payload)
    -- block moving illegal items into a public trunk
    if payload.toType == 'trunk' and payload.fromSlot.name == 'weapon_rpg' then
        return false
    end
end)

createDrop

Déclenché avant la création d’un drop au sol. Renvoie false pour le bloquer.

Données reçues

exports.origen_inventory:registerHook('createDrop', function(payload)
    if Config.NoDropZones[GetZoneAtCoords(payload.coords)] then
        return false
    end
end)

buyItem

Déclenché avant la validation d’un achat en boutique. Renvoie false pour annuler l’achat.

Données reçues

exports.origen_inventory:registerHook('buyItem', function(payload)
    -- block restricted weapons from being bought outside police stations
    if payload.item.type == 'weapon' and not IsAtPoliceStation(payload.source) then
        return false
    end
end)

openInventory

Déclenché avant l’ouverture d’un stash ou d’une boutique. Renvoie false pour refuser l’accès.

Données reçues

exports.origen_inventory:registerHook('openInventory', function(payload)
    if payload.inventoryType == 'stash' and payload.inventoryId:match('^faction%-') then
        return PlayerHasFactionAccess(payload.source, payload.inventoryId)
    end
end)

clearInventory

Déclenché avant qu’un inventaire soit vidé. Renvoie false pour annuler le vidage.

Données reçues

exports.origen_inventory:registerHook('clearInventory', function(payload)
    if payload.inventoryType == 'stash' and IsAuditedStash(payload.inventoryId) then
        return false -- audited stashes cannot be wiped
    end
end)

itemExpired

Déclenché lorsqu’un objet avec decay arrive à expiration. Renvoie false pour conserver malgré tout l’objet dans le slot (rare : en général, on le laisse être supprimé).

Données reçues

exports.origen_inventory:registerHook('itemExpired', function(payload)
    if payload.item.name == 'sealed_evidence' then
        return false -- evidence does not decay even if config says so
    end
end)

Notes sur les performances

• Chaque hook est encapsulé dans un pcall. Les erreurs survenant dans ton hook sont isolées et ne feront pas planter l’inventaire.
• Le temps d’exécution est mesuré. Si un hook dépasse 100ms, l’inventaire affiche un log de débogage pour que tu puisses repérer les callbacks lents.
• Utilise les options itemFilter / inventoryFilter / typeFilter dès que possible : elles court-circuitent la boucle de dispatch et sont bien moins coûteuses qu’un filtrage dans ton callback.

Voir aussi

• Exports · origen_inventory : référence complète des exports.
• Custom · Hooks (aperçu) : aperçu d’origine des hooks et hooks client.
• Custom · Hooks client : hooks des points du monde et de l’interface.