Início › Documentação › Personalização · origen_inventory

Personalização · origen_inventory

O origen_inventory oferece três formas de personalização:

  1. Hooks: escutam eventos do inventário e modificam os dados ou cancelam ações.
  2. Itens personalizados: regista, edita e remove itens em tempo de execução (ficam guardados em origen_customitems).
  3. Pontos do mundo: regista pontos interativos personalizados no mapa.
text
config/
├── hooks.lua          -- Hook examples (server + client)
modules/
├── customItems.lua    -- AddCustomItem / EditCustomItem / RemoveCustomItem implementation
client/functions/
├── f_hooks.lua        -- registerHook / removeHooks (client-side)
└── f_worldpoint.lua   -- World point exports

Hooks

Os hooks permitem que outros recursos se subscrevam aos eventos do inventário e, ou consultem os dados, ou os modifiquem ou cancelem a ação. O cliente e o servidor expõem o mesmo nome de export: registerHook.

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

Regista um callback para o hook indicado.

lua
local hookId = exports.origen_inventory:registerHook('createItem', function(payload)
    -- payload is hook-specific
    return payload.metadata
end)
Parâmetro Tipo Descrição
event string Nome do hook a escutar.
callback function É invocado com os dados do hook.
options table Configuração opcional do hook.

removeHooks(id) → void

Remove um hook registado anteriormente a partir do seu id.

lua
exports.origen_inventory:removeHooks(hookId)

Hooks de servidor

createItem

É disparado quando um item está a ser criado (por exemplo, ao inicializar os metadados). Devolve a tabela metadata (modificada, se quiseres) para aplicar as alterações.

Dados recebidos

Campo Tipo Descrição
item table Definição do item que está a ser criado.
metadata table Tabela de metadados modificável.

Exemplo: atribuir um id de saco único ao criar um paperbag:

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

Se registares o hook createItem e te esqueceres de devolver a tabela de metadados, o item será criado com os metadados vazios.

Hooks de cliente

worldpoint-interact-in

É disparado quando o jogador entra no raio de interação de um ponto do mundo.

Dados recebidos

Campo Tipo Descrição
type string Tipo de ponto (stash, shop, crafting, drop, personalizado).
id string Id único do ponto.
location vector3 Coordenadas do ponto.
label string Etiqueta apresentada.

worldpoint-interact-out

É disparado quando o jogador sai do raio de interação de um ponto do mundo. Recebe os mesmos dados que o anterior.

worldpoint-area-nearby

É disparado quando o jogador entra na zona mais ampla (zoneDistance) à volta de um stash ou de outro ponto com uma zona configurada. Serve para carregar de forma diferida interfaces pesadas.

Exemplo: registar cada entrada num stash:

lua
exports.origen_inventory:registerHook('worldpoint-interact-in', function(payload)
    if payload.type ~= 'stash' then return end
    print(('Player entered stash %s at %s'):format(payload.id, payload.label))
end)

Itens personalizados

Os itens personalizados ficam guardados na tabela origen_customitems e são recarregados quando o recurso arranca. As três operações são executadas no servidor.

AddCustomItem(data) → boolean

Adiciona um novo item personalizado. Devolve false se o item já existir.

lua
exports.origen_inventory:AddCustomItem({
    name = 'origen_compass',
    label = 'Compass',
    weight = 200,
    type = 'item',
    image = 'origen_compass.png',
    description = 'Always points to the next adventure.',
    rarity = 'rare',
    stack = false,
    close = true,
    decay = nil,
    server = nil,
    client = nil,
    buttons = {},
})
Campo Tipo Descrição
name string Chave única do item. Se estiver vazia, é gerada a partir de label.
label string Etiqueta apresentada.
weight number Peso do item.
type string Tipo de item (item, weapon, etc.).
image string Nome do ficheiro de imagem (tem de existir na pasta de imagens do teu inventário).
description string Descrição do item.
rarity string Etiqueta de raridade (opcional).
stack boolean Indica se o item é empilhável. Por omissão é true.
close boolean Fecha o inventário ao usar o item. Por omissão é true.
decay number Duração da deterioração (opcional).
server string|table Definição do callback de servidor (opcional).
client string|table Definição do callback de cliente (opcional).
buttons table Botões do menu de contexto (opcional).
consume / uses number Número de utilizações antes de o item ser consumido.

O item é adicionado ao dicionário em memória e sincronizado automaticamente com todos os clientes.

EditCustomItem(data) → boolean, error?

Edita um item personalizado existente. O campo name é obrigatório e tem de corresponder a um item existente.

lua
exports.origen_inventory:EditCustomItem({
    name = 'origen_compass',
    label = 'Magic Compass',
    weight = 150,
})

Devolve false juntamente com uma cadeia de erro quando:

RemoveCustomItem(name) → boolean

Elimina um item da base de dados e do inventário de todos os jogadores. Dispara um evento interno de sincronização para que os clientes descartem as referências em cache.

lua
exports.origen_inventory:RemoveCustomItem('origen_compass')

Esta ação é destrutiva. O item é removido de todos os inventários ativos e da tabela origen_customitems.

Pontos do mundo

Os pontos do mundo mostram locais interativos no mapa e reagem a eles. É com eles que funcionam os stashes, as lojas, as mesas de crafting, os drops e qualquer ponto personalizado que registes.

CreateWorldPoint(pointId, pointData, pointType) → void (cliente)

Regista um único ponto em tempo de execução.

lua
exports.origen_inventory:CreateWorldPoint('my_lab_table', {
    label = 'Underground Lab',
    location = vector3(2541.92, 4684.31, 34.05),
    -- marker = { type = 27, size = vector3(0.3, 0.3, 0.3), color = vector4(255, 0, 0, 150) },
    -- sprite = { enabled = true, icon = 'lucide:flask-conical' },
}, 'crafting')

RemoveWorldPoint(pointId) → void (cliente)

Remove um ponto a partir do seu id.

SetWorldPointEnabled(pointId, enabled) → void (cliente)

Ativa ou desativa um ponto existente sem o remover.

CreateBatchPoints(pointsData, pointType) → void (cliente)

Regista vários pontos de uma só vez.

lua
exports.origen_inventory:CreateBatchPoints({
    ['stash_1'] = { label = 'Stash 1', location = vector3(...) },
    ['stash_2'] = { label = 'Stash 2', location = vector3(...) },
}, 'stash')

ClearPoints(pointType) → void (cliente)

Remove todos os pontos de um tipo.

RefreshAllPoints(pointType) → void (cliente)

Recarrega todos os pontos de um tipo. É útil depois de alterares as permissões de job do jogador.

GetPoints(pointType) → table (cliente)

Devolve a lista de pontos de um tipo.

GetPointCount(pointType) → number (cliente)

Devolve o número de pontos registados de um tipo.

HasPoint(pointId) → boolean (cliente)

Devolve true se existir um ponto com esse id.

RegisterPointType(pointType, config) → void (cliente)

Regista um tipo de ponto totalmente novo, com o seu próprio sprite, marcador e hooks. Usa-o quando quiseres adicionar uma categoria nova ao lado de stash, shop, crafting e drop.

LoadPointType(pointType) → void (cliente)

Recarrega a configuração de um tipo de ponto.

GetWorldPointManager() → table (cliente)

Devolve o objeto gestor de pontos subjacente. Apenas para utilização avançada.

Ponte SQL

O helper SQL em bridge/sql.lua disponibiliza funções independentes do framework que todos os subsistemas internos utilizam. Normalmente não precisas de o usar diretamente, mas o código-fonte não está ofuscado (fica fora do âmbito de escrow_ignore) e os teus próprios scripts podem encapsulá-lo.