Hooks

Los hooks son una forma de modificar el comportamiento del sistema de inventario. Se registran en el servidor y pueden usarse para modificar el comportamiento del sistema de inventario, por ejemplo para evitar que los jugadores muevan ítems a un inventario específico. Hay algunos ejemplos de hooks en la carpeta jaksam_inventory/_hooks.

Buenas Prácticas

Usa filtros

Usa siempre los filtros adecuados para evitar ejecuciones innecesarias de hooks

Retornos tempranos

Usa retornos tempranos para salir de los hooks cuando no se cumplan las condiciones

Rendimiento

Mantén la lógica de los hooks ligera para no afectar el rendimiento del inventario

Ejemplos de Casos de Uso

Evitar que los jugadores roben ítems que tienen el campo de metadato sole_owner (p. ej., ítems VIP)
Evitar que los jugadores muevan armas policiales a su inventario personal
Permitir solo una mochila por inventario de jugador
Craftear ítems arrastrando un ítem específico sobre otro (por ejemplo, arrastrar pan sobre carne puede crear un sándwich)
Bloquear el uso de ítems cuando el jugador está esposado o en zonas específicas
Registrar estadísticas de uso de ítems y logros
Evitar el uso de ciertos ítems dentro de vehículos
Agregar ítems iniciales a los inventarios de jugadores nuevos cuando se crean
Prepoblar contenedores de basura o stashes con ítems aleatorios al crearse

Funciones de la API

Registrar un Hook

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

Parámetros

Nombre	Tipo de Dato	Descripción
`eventName`	string	El nombre del hook event a escuchar (consulta los Events de Hook Disponibles más abajo)
`callback`	function	La función que se ejecuta cuando se activa el hook
`options`	table	Filtros y opciones de configuración (consulta el Parámetro Options más abajo)
`priority`	number	Prioridad de ejecución (los números más altos se ejecutan primero, por defecto: 0)

Valor de retorno

Nombre	Tipo de Dato	Descripción
`hookId`	string	Identificador único del hook registrado (se usa para anular el registro del hook)

Anular el Registro de un Hook

exports['jaksam_inventory']:unregisterHook(hookId)

Parámetros

Nombre	Tipo de Dato	Descripción
`hookId`	string	El identificador único devuelto al registrar el hook

Anular el Registro de Todos los Hooks de un Resource

exports['jaksam_inventory']:unregisterResourceHooks(resourceName)

Parámetros

Nombre	Tipo de Dato	Descripción
`resourceName`	string	Nombre del resource al que se le anulará el registro de todos los hooks

Parámetro Options

El parámetro options acepta una table con filtros para optimizar el rendimiento.

Común (todos los events)
Filtros de inventario
Filtros de transferencia

    local options = {
        -- Debug: Imprime en la consola cuando se activa el hook
        print = true,

        -- Solo activar para ítems específicos
        itemNameFilter = {
            bread = true,
            weapon_pistol = true
        },

        -- Solo activar para tipos de ítem específicos
        itemTypeFilter = {
            weapon = true,
            currency = true
        }
    }

Para onItemAdded, onItemRemoved, onInventoryCreated, onPreOpenInventory, onOmnipackTransaction:

    local options = {
        -- Filtrar por tipo de inventario (recomendado)
        inventoryTypeFilter = {
            player = true,
            stash = true
        },

        -- Filtrar por patrones específicos de inventario (avanzado)
        inventoryFilter = {
            "player:.*",      -- Todos los jugadores
            "stash_police"    -- Stash específico
        }
    }

Solo para onItemTransferred:

    local options = {
        -- Filtrar el inventario de origen por tipo
        inventoryFromTypeFilter = { player = true },

        -- Filtrar el inventario de origen por patrón de nombre
        inventoryFromFilter = {
            "player:.*",      -- Todos los jugadores
            "vehicle:123"     -- Vehículo específico
        },

        -- Filtrar el inventario de destino por tipo
        inventoryToTypeFilter = { stash = true },

        -- Filtrar el inventario de destino por patrón de nombre
        inventoryToFilter = {
            "stash_police",   -- Stash específico
            "container:.*"    -- Todos los contenedores
        },

        -- Solo movimientos dentro del mismo inventario (arrastrar dentro del mismo inventario)
        intraInventoryOnly = true
    }

Events de Hook Disponibles

Event	Descripción
Item added	Se activa cuando se agrega un ítem a un inventario
Item removed	Se activa cuando se elimina un ítem de un inventario
Item transferred	Se activa cuando un ítem se transfiere entre inventarios
Omnipack transaction	Se activa cuando un admin crea o destruye un ítem a través del inventario de admin
Pre use item	Se activa antes de que se use un ítem, puede cancelar el uso
Post use item	Se activa después de que se ha usado un ítem, solo como notificación
Inventory created	Se activa cuando se crea un nuevo inventario
Pre open inventory	Se activa antes de que se abra un inventario secundario, puede impedir que se abra

Comportamiento de los Hooks

Prioridad

Los números más altos se ejecutan primero (por defecto: 0)

Valores de retorno

return nil o return true: permite que la acción continúe.return false, "message", "notifyType": evita la acción y detiene la ejecución de los demás hooks. Los parámetros message y notifyType son opcionales (notifyType puede ser "error", "success", "info")

Excepción - onPreOpenInventory: el mensaje no se muestra al jugador, porque la precarga haría que se repitiese. Llama a notifyPlayer desde dentro del hook si quieres decirle al jugador el motivo.

Compatibilidad con ox_inventory

Cuando el resource de compatibilidad con ox_inventory está instalado, exports.ox_inventory:registerHook(...) se traduce a los hooks nativos de arriba, así que los scripts de ox_inventory funcionan sin cambios. Los payloads se transforman al formato de ox, y los nombres de opciones de ox (itemFilter, typeFilter, inventoryFilter, print) también se traducen.

Hook de ox_inventory	Soportado	Hook nativo usado
`createItem`	Sí	`onItemAdded`
`swapItems`	Sí	`onItemTransferred`
`openInventory`	Sí	`onPreOpenInventory`
`usingItem`	Sí	`onPreUseItem`
`buyItem` / `openShop`	No	todavía no hay hooks de tienda
`craftItem`	No	todavía no hay hooks de crafteo

Registrar un hook no soportado imprime una advertencia y devuelve nil en lugar de lanzar un error. Tres diferencias a tener en cuenta al migrar:

Un hook de ox solo puede permitir o bloquear; no puede proporcionar un mensaje personalizado ni un tipo de notificación. Usa los hooks nativos para eso
openInventory hereda el requisito de no tener estado descrito en onPreOpenInventory
Los inventarios de jugador se identifican de forma distinta. Los hooks de ox reciben el ID de servidor del jugador como number (inventoryId = 4), igual que ox_inventory. Los hooks nativos reciben el identificador de personaje de jaksam como string (inventoryId = "char1:35030084..."). Cualquier otro tipo de inventario usa el mismo ID string en ambos

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

Buenas Prácticas

Usa filtros

Retornos tempranos

Rendimiento

Ejemplos de Casos de Uso

Funciones de la API

Registrar un Hook

Parámetros

Valor de retorno

Anular el Registro de un Hook

Parámetros

Anular el Registro de Todos los Hooks de un Resource

Parámetros

Parámetro Options

Events de Hook Disponibles

Comportamiento de los Hooks

Prioridad

Valores de retorno

Compatibilidad con ox_inventory

​Buenas Prácticas

Usa filtros

Retornos tempranos

Rendimiento

​Ejemplos de Casos de Uso

​Funciones de la API

​Registrar un Hook

​Parámetros

​Valor de retorno

​Anular el Registro de un Hook

​Parámetros

​Anular el Registro de Todos los Hooks de un Resource

​Parámetros

​Parámetro Options

​Events de Hook Disponibles

​Comportamiento de los Hooks

Prioridad

Valores de retorno

​Compatibilidad con ox_inventory

Buenas Prácticas

Ejemplos de Casos de Uso

Funciones de la API

Registrar un Hook

Parámetros

Valor de retorno

Anular el Registro de un Hook

Parámetros

Anular el Registro de Todos los Hooks de un Resource

Parámetros

Parámetro Options

Events de Hook Disponibles

Comportamiento de los Hooks

Compatibilidad con ox_inventory