QBCore items usáveis: CreateUseableItem, AddItem e RemoveItem

Em QBCore, um item usável é uma função de server registrada sob um nome de item. Quando o jogador usa o item no inventory, a função roda. Este artigo cobre o registro, as funções que dão, removem e checam items, a notificação de caixa de item, e o que é diferente em QBox.

#O item deve existir primeiro

Items de QBCore são definidos em qb-core/shared/items.lua. Um item que é usável precisa de useable = true:

['burger'] = {
    name = 'burger',
    label = 'Burger',
    weight = 200,
    type = 'item',
    image = 'burger.png',
    unique = false,
    useable = true,
    shouldClose = true,
    description = 'A warm burger.',
},

A chave e o name devem ser iguais. O image é um arquivo na pasta de imagens do seu inventory. Para o formato completo de item, veja adding items on QBCore.

#Registre o item usável

No server, em seu script:

local QBCore = exports['qb-core']:GetCoreObject()

QBCore.Functions.CreateUseableItem('burger', function(source, item)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end

    if Player.Functions.RemoveItem('burger', 1) then
        TriggerClientEvent('my_script:eatBurger', source)
    end
end)

O callback recebe o id do jogador e os dados do item. Não remove o item, então você o remove você mesmo e apenas roda o efeito se a remoção funcionou. Se QBCore é nil aqui, veja the GetCoreObject fix.

O evento do cliente apenas toca o efeito:

RegisterNetEvent('my_script:eatBurger', function()
    -- animation, progress bar, hunger update
end)

#Adicione, remova e cheque items

Essas são as funções do jogador que você usa o tempo todo, no server:

local Player = QBCore.Functions.GetPlayer(source)

-- give
Player.Functions.AddItem('burger', 2)

-- remove
Player.Functions.RemoveItem('burger', 1)

-- check
local item = Player.Functions.GetItemByName('burger')
if item and item.amount >= 1 then
    -- the player has at least one
end

AddItem e RemoveItem retornam true quando funcionam e false quando não, por exemplo porque o inventory está cheio ou o item está faltando. Sempre cheque o resultado antes de continuar:

if Player.Functions.AddItem('lockpick', 1) then
    -- reward given
else
    TriggerClientEvent('QBCore:Notify', source, 'Your inventory is full', 'error')
end

AddItem também pega argumentos opcionais slot e info, onde info carrega dados extras no item, como um número de série.

#A caixa de item

Quando o jogador ganha ou perde um item, o inventory usualmente mostra uma pequena caixa com a picture do item. Em qb-inventory você a dispara com um evento do cliente:

TriggerClientEvent('inventory:client:ItemBox', source, QBCore.Shared.Items['burger'], 'add', 2)
TriggerClientEvent('inventory:client:ItemBox', source, QBCore.Shared.Items['burger'], 'remove', 1)

O nome do evento e argumentos podem diferir entre versões do inventory, e algumas versões mostram a caixa por conta própria dentro de AddItem. Olhe como um script existente em seu server a chama, e copie. Chamá-la em cima de uma caixa automática mostra a notificação duas vezes.

Dica: faça o efeito apenas após RemoveItem retornar true. Um script que toca a animação primeiro e remove o item depois dá hambúrgueres grátis aos jogadores quando a remoção falha.

#Um exemplo: craft um item de outro

RegisterNetEvent('my_script:makeBandage', function()
    local src = source
    local Player = QBCore.Functions.GetPlayer(src)
    if not Player then return end

    local cloth = Player.Functions.GetItemByName('cloth')
    if not cloth or cloth.amount < 2 then
        return TriggerClientEvent('QBCore:Notify', src, 'You need 2 cloth', 'error')
    end

    if Player.Functions.RemoveItem('cloth', 2) then
        if not Player.Functions.AddItem('bandage', 1) then
            Player.Functions.AddItem('cloth', 2) -- give the cloth back
        end
    end
end)

Todos os checks rodam no server. Para mais sobre aquela ideia, veja securing server events.

#Em QBox

O core de QBox é qbx_core. O registro de item usável tem seu próprio export:

exports.qbx_core:CreateUseableItem('burger', function(source, item)
    -- same idea: remove the item, then trigger the effect
end)

Servers QBox usam ox_inventory, então você tem uma segunda opção: coloque o efeito no próprio item, em ox_inventory/data/items.lua, com um export client ou server. Aquele caminho é explicado em how to add items to ox_inventory. A compatibility layer para scripts qb-core também lida com QBCore.Functions.CreateUseableItem, então um script antigo continua funcionando. Items devem existir em items.lua do ox_inventory em QBox, não em shared/items.lua.

#Checklist