Metadados de item ox_inventory: AddItem, Search, SetMetadata e itens únicos

Um item em ox_inventory é um nome e uma contagem. Quando dois itens de mesmo nome precisam ser diferentes, como uma chave de carro para uma placa e uma chave para outra, você usa metadados: uma tabela armazenada com o item. Este artigo mostra como adicionar um item com metadados, encontrá-lo novamente, ler e atualizá-lo, exibi-lo e criar itens únicos como IDs e chaves.

#Adicione um item com metadados

O quarto argumento de AddItem é a tabela de metadados:

exports.ox_inventory:AddItem(source, 'car_key', 1, {
    plate = 'ABC 123',
    label = 'Key ABC 123',
    description = 'Opens the car with plate ABC 123.',
})

A assinatura é AddItem(inventory, item, count, metadata). inventory é o id do jogador para um inventário de jogador. Qualquer chave que você adicione é armazenada com o slot, e você pode lê-la novamente mais tarde. Mantenha metadados pequenos e feitos de dados simples: strings, números, booleanos e tabelas simples.

Dica: o item deve existir em data/items.lua, por exemplo car_key. Veja adicionando itens a ox_inventory.

#Mostre-o ao jogador

Algumas chaves de metadados mudam o que o inventário exibe:

exports.ox_inventory:AddItem(source, 'id_card', 1, {
    label = 'ID card: Jane Doe',
    description = 'Born 1994-05-12',
    image = 'id_card',
})

Tudo mais que você coloca na tabela é armazenado, mas não é mostrado, a menos que a própria definição do item o exiba. Use um label único quando você precisa que os jogadores diferenciem itens à primeira vista.

#Procure por itens

Search encontra itens em um inventário. Com 'count' retorna quantos, com 'slots' retorna os slots:

local count = exports.ox_inventory:Search(source, 'count', 'car_key')

local slots = exports.ox_inventory:Search(source, 'slots', 'car_key')
for _, slot in pairs(slots) do
    print(slot.slot, slot.metadata and slot.metadata.plate)
end

Você também pode filtrar por metadados. Passe uma tabela como o quarto argumento:

local keys = exports.ox_inventory:Search(source, 'slots', 'car_key', { plate = 'ABC 123' })
if #keys > 0 then
    -- the player has the key for that plate
end

Esta é a maneira padrão de verificar a propriedade: faça-o no servidor, com os dados que você confia, nunca de uma mensagem do cliente.

#Leia um slot

Se você sabe o número do slot, GetSlot retorna os dados desse slot:

local slot = exports.ox_inventory:GetSlot(source, 5)
if slot and slot.name == 'car_key' then
    print(slot.metadata.plate)
end

Quando você apenas conhece o item, use GetSlotWithItem:

local slot = exports.ox_inventory:GetSlotWithItem(source, 'car_key', { plate = 'ABC 123' })

Ambos retornam nil quando nada coincide, então verifique o resultado antes de ler slot.metadata. Um slot também tem slot.count e slot.weight.

#Atualize metadados com SetMetadata

Para alterar um slot existente, por exemplo marcar uma chave como copiada, ou reduzir as cargas restantes em um item, use SetMetadata:

local slot = exports.ox_inventory:GetSlotWithItem(source, 'battery')
if slot then
    local metadata = slot.metadata or {}
    metadata.charge = (metadata.charge or 100) - 10
    exports.ox_inventory:SetMetadata(source, slot.slot, metadata)
end

SetMetadata(inventory, slot, metadata) substitui os metadados do slot pela tabela que você fornece. Copie a tabela existente primeiro, mude um campo e envie a tabela inteira de volta, caso contrário você apaga as outras chaves.

#Itens únicos: IDs, chaves, licenças

Para um item único você quer duas coisas: um item que não se empilha e metadados que o identifiquem.

-- data/items.lua
['id_card'] = {
    label = 'ID card',
    weight = 10,
    stack = false,
    close = true,
},

-- server: give it at character creation
exports.ox_inventory:AddItem(source, 'id_card', 1, {
    firstname = 'Jane',
    lastname = 'Doe',
    dob = '1994-05-12',
    label = 'ID card: Jane Doe',
})

Itens com metadados diferentes não se empilham, então duas chaves para dois carros sempre ocupam dois slots, e stack = false torna isso explícito para itens que nunca deveriam.

Para ler os dados quando o item é usado, registre uma exportação de servidor no item:

-- data/items.lua
['id_card'] = {
    label = 'ID card',
    weight = 10,
    stack = false,
    server = { export = 'my_script.id_card' },
},

-- my_script/server.lua
exports('id_card', function(event, item, inventory, slot, data)
    if event == 'usingItem' then
        local info = exports.ox_inventory:GetSlot(inventory.id, slot)
        if info and info.metadata then
            print(info.metadata.firstname, info.metadata.lastname)
        end
    end
end)

O argumento event lhe diz a fase do uso. Os argumentos exatos dependem de sua versão ox_inventory, então verifique a documentação para sua versão se a exportação não for chamada.

#Coisas a observar

• Metadados vivem no slot. Quando o jogador drop ou troca o item, ele se move com ele, e é o item que prova o direito de acessar algo.
• Não coloque segredos em metadados. Os jogadores não veem chaves não listadas, mas os tratam como dados, não como proteção.
• Muitos itens com tabelas de metadados grandes torna o salvamento de inventário mais lento. Armazene um id e mantenha os dados pesados em sua própria tabela de banco de dados.
• Metadados definidos no cliente não são confiáveis. Sempre chame AddItem e SetMetadata a partir do código do servidor.

#Lista de verificação