Articles utilisables QBCore : CreateUseableItem, AddItem et RemoveItem

Sur QBCore, un article utilisable est une fonction serveur enregistrée sous un nom d'article. Quand le joueur utilise l'article dans l'inventaire, la fonction s'exécute. Cet article couvre l'enregistrement, les fonctions qui donnent, suppriment et vérifient les articles, la notification de boîte d'article, et ce qui est différent sur QBox.

#L'article doit d'abord exister

Les articles QBCore sont définis dans qb-core/shared/items.lua. Un article qui est utilisable a besoin 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.',
},

La clé et le name doivent être les mêmes. Le image est un fichier dans le dossier des images de votre inventaire. Pour le format d'article complet, consultez ajout d'articles sur QBCore.

#Enregistrer l'article utilisable

Sur le serveur, dans votre 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)

Le callback reçoit l'ID du joueur et les données de l'article. Il ne supprime pas l'article, vous le supprimez donc vous-même et n'exécutez l'effet que si la suppression a fonctionné. Si QBCore est nil ici, consultez la correction GetCoreObject.

L'événement client joue uniquement l'effet :

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

#Ajouter, supprimer et vérifier les articles

Ce sont les fonctions du joueur que vous utilisez tout le temps, sur le serveur :

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 et RemoveItem retournent true quand elles ont fonctionné et false quand elles n'ont pas, par exemple parce que l'inventaire est plein ou l'article est manquant. Vérifiez toujours le résultat avant de continuer :

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

AddItem prend aussi les arguments optionnels slot et info, où info transporte les données supplémentaires sur l'article, comme un numéro de série.

#La boîte d'article

Quand le joueur obtient ou perd un article, l'inventaire affiche généralement une petite boîte avec l'image de l'article. Dans qb-inventory vous la déclenchez avec un événement client :

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

Le nom de l'événement et les arguments peuvent différer entre les versions d'inventaire, et certaines versions affichent la boîte d'elles-mêmes à l'intérieur de AddItem. Regardez comment un script existant sur votre serveur l'appelle, et copiez cela. L'appeler en plus d'une boîte automatique affiche la notification deux fois.

Conseil : ne jouez l'effet qu'après que RemoveItem retourne true. Un script qui joue l'animation d'abord et supprime l'article plus tard donne aux joueurs des burgers gratuits quand la suppression échoue.

#Un exemple : fabriquer un article à partir d'un autre

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)

Toutes les vérifications s'exécutent sur le serveur. Pour plus sur cette idée, consultez sécuriser les événements serveur.

#Sur QBox

Le noyau de QBox est qbx_core. L'enregistrement d'article utilisable a son propre export :

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

Les serveurs QBox utilisent ox_inventory, vous avez donc une deuxième option : mettez l'effet dans l'article lui-même, dans ox_inventory/data/items.lua, avec un export client ou server. Ce chemin est expliqué dans comment ajouter des articles à ox_inventory. La couche de compatibilité pour les scripts qb-core gère aussi QBCore.Functions.CreateUseableItem, ainsi un ancien script continue à fonctionner. Les articles doivent exister dans items.lua d'ox_inventory sur QBox, pas dans shared/items.lua.

#Liste de contrôle