Início › Documentação › Hooks de servidor · origen_inventory

Hooks de servidor · origen_inventory

Os hooks permitem que outros recursos se subscrevam aos eventos do inventário no servidor e, ou consultem os dados, ou os modifiquem ou cancelem a ação devolvendo false.

O sistema de hooks é exposto através de dois exports, registerHook e removeHooks, e é simétrico com a API de hooks do cliente.

API

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

Regista um hook de servidor. Devolve o hookId interno para que o possas remover mais 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

Remove os hooks que pertencem ao recurso que faz a chamada. Passa um id para remover um único hook, ou omite-o para remover todos os hooks registados pelo recurso.

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

Contrato de cancelamento

A maioria dos hooks de servidor respeita um contrato de cancelamento:

• Devolve false → o inventário aborta a ação (o item não é adicionado, trocado, comprado, etc.).
• Devolve qualquer outra coisa (ou nada) → a ação continua normalmente.

A única exceção é createItem, que é mutante: tens de devolver a tabela metadata (modificada, se quiseres).

Referência de hooks

createItem

É disparado quando um item é adicionado a um inventário e os metadados estão a ser inicializados. Mutante: tem de devolver metadata.

Dados recebidos

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

É disparado depois de um item ser adicionado a um inventário. Apenas leitura / observação: o valor devolvido é ignorado.

Dados recebidos

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

É disparado depois de um slot ser usado com sucesso. É apenas de observação.

Dados recebidos

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

useSlot

É disparado antes de um slot ser usado. Devolve false para cancelar a utilização.

Dados recebidos

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

É disparado antes de qualquer movimento / troca / divisão / entrega entre dois inventários (de jogador para jogador, transferências de stash, porta-bagagens, drops, etc.). Devolve false para cancelar a transferência.

Dados recebidos

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

É disparado antes de criar um drop no chão. Devolve false para o bloquear.

Dados recebidos

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

buyItem

É disparado antes de confirmar uma compra numa loja. Devolve false para cancelar a compra.

Dados recebidos

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

É disparado antes de abrir um stash ou uma loja. Devolve false para negar o acesso.

Dados recebidos

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

É disparado antes de esvaziar um inventário. Devolve false para cancelar o esvaziamento.

Dados recebidos

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

É disparado quando um item com decay chega ao fim da validade. Devolve false para manter o item no slot mesmo assim (é raro: o normal é deixar que seja removido).

Dados recebidos

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 desempenho

• Cada hook é encapsulado num pcall. Os erros dentro do teu hook ficam isolados e não deitam o inventário abaixo.
• O tempo de execução é medido. Se um hook demorar mais de 100ms, o inventário imprime um log de depuração para que possas identificar os callbacks lentos.
• Usa as opções itemFilter / inventoryFilter / typeFilter sempre que possível: cortam o ciclo de despacho e são muito mais baratas do que filtrar dentro do teu callback.

Ver também

• Exports · origen_inventory: referência completa de exports.
• Custom · Hooks (resumo): resumo original dos hooks e hooks de cliente.
• Custom · Hooks de cliente: hooks de pontos do mundo e da interface.