QBCore usable items: CreateUseableItem, AddItem and RemoveItem

On QBCore, a usable item is a server function registered under an item name. When the player uses the item in the inventory, the function runs. This article covers the registration, the functions that give, remove and check items, the item box notification, and what is different on QBox.

#The item must exist first

QBCore items are defined in qb-core/shared/items.lua. An item that is usable needs useable = true:

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

The key and the name must be the same. The image is a file in your inventory's images folder. For the full item format, see adding items on QBCore.

#Register the usable item

On the server, in your 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)

The callback receives the player id and the item data. It does not remove the item, so you remove it yourself and only run the effect if the removal worked. If QBCore is nil here, see the GetCoreObject fix.

The client event only plays the effect:

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

#Add, remove and check items

These are the player functions you use all the time, on the 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 and RemoveItem return true when they worked and false when they did not, for example because the inventory is full or the item is missing. Always check the result before you continue:

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

AddItem also takes optional slot and info arguments, where info carries extra data on the item, such as a serial number.

#The item box

When the player gets or loses an item, the inventory usually shows a small box with the item picture. In qb-inventory you trigger it with a client event:

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

The event name and arguments can differ between inventory versions, and some versions show the box on their own inside AddItem. Look at how an existing script in your server calls it, and copy that. Calling it on top of an automatic box shows the notification twice.

Tip: do the effect only after RemoveItem returns true. A script that plays the animation first and removes the item later gives players free burgers when the removal fails.

#An example: craft one item from another

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)

All checks run on the server. For more on that idea, see securing server events.

#On QBox

QBox's core is qbx_core. The usable item registration has its own export:

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

QBox servers use ox_inventory, so you have a second option: put the effect in the item itself, in ox_inventory/data/items.lua, with a client or server export. That path is explained in how to add items to ox_inventory. The compatibility layer for qb-core scripts also handles QBCore.Functions.CreateUseableItem, so an older script keeps working. Items must exist in ox_inventory's items.lua on QBox, not in shared/items.lua.

#Checklist