Articoli usabili QBCore: CreateUseableItem, AddItem e RemoveItem

Su QBCore, un articolo usabile è una funzione server registrata sotto un nome di articolo. Quando il giocatore usa l'articolo nell'inventario, la funzione gira. Questo articolo copre la registrazione, le funzioni che danno, rimuovono e controllano gli articoli, la notifica della scatola dell'articolo, e cosa è diverso su QBox.

#L'articolo deve esistere prima

Gli articoli QBCore sono definiti in qb-core/shared/items.lua. Un articolo che è usabile ha bisogno di useable = true:

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

La chiave e il name devono essere lo stesso. L'image è un file nella cartella immagini del tuo inventario. Per il formato completo dell'articolo, vedi aggiungere articoli su QBCore.

#Registra l'articolo usabile

Sul server, nel tuo 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)

Il callback riceve l'id del giocatore e i dati dell'articolo. Non rimuove l'articolo, quindi lo rimuovi tu stesso e esegui solo l'effetto se la rimozione ha funzionato. Se QBCore è nil qui, vedi il GetCoreObject fix.

L'evento client solo riproduce l'effetto:

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

#Aggiungi, rimuovi e controlla gli articoli

Queste sono le funzioni giocatore che usi tutto il tempo, sul 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 ritornano true quando hanno funzionato e false quando non hanno, per esempio perché l'inventario è pieno o l'articolo manca. Controlla sempre il risultato prima di continuare:

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

AddItem prende anche argomenti slot e info opzionali, dove info porta dati extra sull'articolo, come un numero di serie.

#La scatola dell'articolo

Quando il giocatore riceve o perde un articolo, l'inventario di solito mostra una piccola scatola con l'immagine dell'articolo. In qb-inventory lo attivi con un evento client:

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

Il nome dell'evento e gli argomenti possono differire tra le versioni dell'inventario, e alcune versioni mostrano la scatola da sole dentro AddItem. Guarda come uno script esistente nel tuo server lo chiama, e copia quello. Chiamarlo in cima a una scatola automatica mostra la notifica due volte.

Suggerimento: fai l'effetto solo dopo che RemoveItem ritorna true. Uno script che riproduce l'animazione per primo e rimuove l'articolo dopo dà ai giocatori burger gratis quando la rimozione fallisce.

#Un esempio: crea un articolo da un altro

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)

Tutti i controlli girano sul server. Per di più su quell'idea, vedi securing server events.

#Su QBox

Il core di QBox è qbx_core. La registrazione dell'articolo usabile ha il suo export:

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

I server QBox usano ox_inventory, quindi hai una seconda opzione: metti l'effetto nell'articolo stesso, in ox_inventory/data/items.lua, con un export client o server. Quel percorso è spiegato in come aggiungere articoli a ox_inventory. Il livello di compatibilità per gli script qb-core gestisce anche QBCore.Functions.CreateUseableItem, quindi uno script più vecchio continua a funzionare. Gli articoli devono esistere in items.lua di ox_inventory su QBox, non in shared/items.lua.

#Checklist