Inicio › Documentación › Hooks de servidor · origen_inventory

Hooks de servidor · origen_inventory

Los hooks permiten que otros recursos se suscriban a los eventos del inventario en el servidor y, o bien consulten los datos, o bien los modifiquen o cancelen la acción devolviendo false.

El sistema de hooks se expone mediante dos exports, registerHook y removeHooks, y es simétrico con la API de hooks de cliente.

API

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

Registra un hook de servidor. Devuelve el hookId interno para que puedas eliminarlo más tarde.

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

Filtros (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

Elimina los hooks que pertenecen al recurso que hace la llamada. Pasa un id para eliminar un único hook, u omítelo para eliminar todos los hooks registrados por el recurso.

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

Contrato de cancelación

La mayoría de los hooks de servidor respetan un contrato de cancelación:

• Devuelve false → el inventario aborta la acción (el objeto no se añade, intercambia, compra, etc.).
• Devuelve cualquier otra cosa (o nada) → la acción continúa con normalidad.

La única excepción es createItem, que es mutante: debes devolver la tabla metadata (modificada, si quieres).

Referencia de hooks

createItem

Se dispara cuando se añade un objeto a un inventario y se están inicializando los metadatos. Mutante: debe devolver metadata.

Datos recibidos

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

Se dispara después de añadir un objeto a un inventario. Solo lectura / observación: el valor devuelto se ignora.

Datos recibidos

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

Se dispara después de usar un slot correctamente. Es solo de observación.

Datos recibidos

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

useSlot

Se dispara antes de usar un slot. Devuelve false para cancelar el uso.

Datos recibidos

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

Se dispara antes de cualquier movimiento / intercambio / división / entrega entre dos inventarios (de jugador a jugador, transferencias de stash, maletero, drops, etc.). Devuelve false para cancelar la transferencia.

Datos recibidos

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

Se dispara antes de crear un drop en el suelo. Devuelve false para bloquearlo.

Datos recibidos

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

buyItem

Se dispara antes de confirmar una compra en una tienda. Devuelve false para cancelar la compra.

Datos recibidos

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

Se dispara antes de abrir un stash o una tienda. Devuelve false para denegar el acceso.

Datos recibidos

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

Se dispara antes de vaciar un inventario. Devuelve false para cancelar el vaciado.

Datos recibidos

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

Se dispara cuando un objeto con decay llega a su caducidad. Devuelve false para mantener el objeto en el slot de todos modos (es raro: lo normal es dejar que se elimine).

Datos recibidos

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)

Notas de rendimiento

• Cada hook se envuelve en un pcall. Los errores dentro de tu hook quedan aislados y no harán caer el inventario.
• Se mide el tiempo de ejecución. Si un hook tarda más de 100ms, el inventario imprimirá un log de depuración para que puedas localizar los callbacks lentos.
• Usa las opciones itemFilter / inventoryFilter / typeFilter siempre que puedas: cortan el bucle de despacho y son mucho más baratas que filtrar dentro de tu callback.

Véase también

• Exports · origen_inventory: referencia completa de exports.
• Custom · Hooks (resumen): resumen original de hooks y hooks de cliente.
• Custom · Hooks de cliente: hooks de puntos del mundo y de la interfaz.