Creating an item in ESX and QBCore

The problem

You want to add a new item to your server (a water bottle, a key, a quest object) but you don't know which file declares it depending on whether you run classic ESX, QBCore or ox_inventory, nor how to make something actually happen when it's used.

The cause

In FiveM there's no single place where items live: it depends on the inventory you have installed. ox_inventory reads them from a Lua file (data/items.lua), classic ESX stores them in an `items` table in the database, and QBCore defines them in `qb-core/shared/items.lua`. If you declare the item in the wrong place the inventory won't recognize it, the image shows blank, and the item isn't usable because you never registered its server-side callback.

The solution

Declare the item in the right file for your inventory, drop its .png into the inventory's images folder, and register it as usable on the server. Here's the definition in ox_inventory (items.lua) and in QBCore (shared/items.lua):

-- ============================================
-- ox_inventory  ->  ox_inventory/data/items.lua
-- ============================================
-- The key (['water']) is the internal item "name".
['water'] = {
    label = 'Water',       -- name shown in the inventory
    weight = 200,          -- weight per unit (in grams)
    stack = true,          -- true = stacks in a single slot
    close = true,          -- closes the inventory on use
    description = 'A bottle of fresh water',
    client = {
        status = { thirst = 200000 }, -- effect on use (example)
        anim = { dict = 'mp_player_intdrink', clip = 'loop_bottle' },
        usetime = 2500,
    },
},
-- Image goes in: ox_inventory/web/images/water.png
-- (the .png must be named exactly like the item key)

-- In ox_inventory you do NOT use CreateUseableItem; "using" is
-- handled by the client.* block above or via an export/hook:
-- exports('water', function(event, item, inventory, slot, data) ... end)


-- ============================================
-- QBCore  ->  qb-core/shared/items.lua
-- ============================================
water = {
    name = 'water',           -- internal name (same as the key)
    label = 'Water',          -- visible name
    weight = 100,             -- weight per unit
    type = 'item',
    image = 'water.png',      -- .png file name
    unique = false,           -- true for keys/unique objects
    useable = true,           -- flags that it has a use callback
    shouldClose = true,
    description = 'A bottle of fresh water',
},
-- Image goes in: qb-inventory/html/images/water.png
-- (or whichever QB inventory you use; ox_inventory works for QBCore too)

-- The on-use effect is registered on the SERVER (see steps).

Step by step

1. 1.Identify your inventory: if you use ox_inventory edit `ox_inventory/data/items.lua`; in classic ESX insert a row into the database `items` table (`INSERT INTO items (name, label, weight, rare, can_remove) VALUES ('water', 'Water', 1, 0, 1);`); in QBCore edit `qb-core/shared/items.lua`.
2. 2.Copy the `water.png` image into the inventory's images folder (`ox_inventory/web/images/` or `qb-inventory/html/images/`). The .png name must match the item name EXACTLY.
3. 3.Make the item usable by registering its callback on the SERVER. Classic ESX: `ESX.RegisterUsableItem('water', function(source) local xPlayer = ESX.GetPlayerFromId(source); xPlayer.removeInventoryItem('water', 1) end)`. QBCore: `QBCore.Functions.CreateUseableItem('water', function(source, item) local Player = QBCore.Functions.GetPlayer(source); Player.Functions.RemoveItem('water', 1) end)`. ox_inventory: use the item's `client.*` block or an `exports('water', ...)`.
4. 4.Restart the inventory resource (and es_extended/qb-core if you touched their shared files) so it loads the new definition; restarting just your own script is NOT enough.
5. 5.Test in-game: give yourself the item with `/giveitem <id> water 1` (ESX) or `/giveitem water 1` (QBCore) and use it from the inventory to confirm the image shows and the callback runs.

Related guides