Elementos usables de QBCore: CreateUseableItem, AddItem y RemoveItem

En QBCore, un elemento usable es una función del servidor registrada bajo un nombre de elemento. Cuando el jugador usa el elemento en el inventario, la función se ejecuta. Este artículo cubre el registro, las funciones que dan, elimina y verifican elementos, la notificación de caja de elementos, y qué es diferente en QBox.

#El elemento debe existir primero

Los elementos de QBCore se definen en qb-core/shared/items.lua. Un elemento que es usable necesita 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 clave y el name deben ser iguales. La image es un archivo en la carpeta de imágenes de tu inventario. Para el formato de elemento completo, consulta añadir elementos en QBCore.

#Registra el elemento usable

En el servidor, en tu 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)

La devolución de llamada recibe el id del jugador y los datos del elemento. No elimina el elemento, así que lo eliminas tú mismo y solo ejecutas el efecto si la eliminación funcionó. Si QBCore es nil aquí, consulta la solución de GetCoreObject.

El evento del cliente solo toca el efecto:

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

#Añadir, eliminar y verificar elementos

Estas son las funciones del jugador que usas todo el tiempo, en el servidor:

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 y RemoveItem devuelven true cuando funcionan y false cuando no, por ejemplo porque el inventario está lleno o el elemento falta. Siempre comprueba el 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 también toma argumentos opcionales slot e info, donde info lleva datos extra en el elemento, como un número de serie.

#La caja de elementos

Cuando el jugador obtiene o pierde un elemento, el inventario generalmente muestra una pequeña caja con la imagen del elemento. En qb-inventory la activas con un evento del cliente:

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

El nombre del evento y los argumentos pueden diferir entre versiones de inventario, y algunas versiones muestran la caja por sí solas dentro de AddItem. Mira cómo un script existente en tu servidor lo llama, y copia eso. Llamarlo encima de una caja automática muestra la notificación dos veces.

Consejo: haz el efecto solo después de que RemoveItem devuelva true. Un script que toca la animación primero y elimina el elemento después da a los jugadores hamburguesas gratis cuando la eliminación falla.

#Un ejemplo: fabricar un elemento de otro

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)

Todas las verificaciones se ejecutan en el servidor. Para más sobre esa idea, consulta asegurar eventos del servidor.

#En QBox

El núcleo de QBox es qbx_core. El registro de elemento usable tiene su propia exportación:

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

Los servidores de QBox usan ox_inventory, así que tienes una segunda opción: pon el efecto en el elemento en sí, en ox_inventory/data/items.lua, con una exportación client o server. Ese camino se explica en cómo añadir elementos a ox_inventory. La capa de compatibilidad para scripts qb-core también maneja QBCore.Functions.CreateUseableItem, así que un script más antiguo sigue funcionando. Los elementos deben existir en items.lua de ox_inventory en QBox, no en shared/items.lua.

#Lista de verificación