Add Items

To add an item in ESX Legacy, insert a row into the items table and reload items with /refreshitems (or restart the server). To make the item do something when a player uses it, register a server-side handler with ESX.RegisterUsableItem. If your server runs ox_inventory, items are defined in ox_inventory's own data/items.lua instead and the ESX items table is not used.

OverviewCopy Anchor Link

The items tableCopy Anchor Link

Add an item with SQLCopy Anchor Link

INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
  ('energy_drink', 'Energy Drink', 1, 0, 1),
  ('lockpick',     'Lockpick',     1, 0, 1),
  ('id_card',      'ID Card',      0, 0, 0);

refreshitems

giveitem 1 energy_drink 5

Add items from a script with ESX.AddItemsCopy Anchor Link

If your resource needs its own items, register them at runtime so server owners do not have to run SQL.

ESX.AddItems(items)

It skips items that already exist in ESX.Items, validates every field (invalid entries are skipped with a console message), inserts the rest with INSERT IGNORE and refreshes online inventories. There is no return value.

ESX = exports['es_extended']:getSharedObject()

if ESX.AddItems then -- not defined when ox_inventory is used
    ESX.AddItems({
        { name = 'energy_drink', label = 'Energy Drink', weight = 1 },
        { name = 'id_card', label = 'ID Card', weight = 0, canRemove = false },
    })
end

Make an item usableCopy Anchor Link

Usable items are server-side. When a player uses the item in the default inventory, the client sends esx:useItem; ESX checks that the player actually has at least one, then calls your handler. ESX does not remove the item for you.

ESX.RegisterUsableItem(item, cb)

ESX = exports['es_extended']:getSharedObject()

ESX.RegisterUsableItem('energy_drink', function(source, item)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then return end

    -- Remove first so a fast double-use cannot consume one item twice
    xPlayer.removeInventoryItem(item, 1)
    xPlayer.showNotification('You feel energized!')
    TriggerClientEvent('energy:boost', source, 30000)
end)

RegisterNetEvent('energy:boost', function(durationMs)
    local playerId = PlayerId()
    SetRunSprintMultiplierForPlayer(playerId, 1.2)
    Wait(durationMs)
    SetRunSprintMultiplierForPlayer(playerId, 1.0)
end)

The handler is wrapped in pcall, so an error in your code prints a warning instead of breaking ESX. Registering an item marks it as usable = true in online players' inventories immediately. ESX.GetUsableItems() returns a table of all registered usable item names, and ESX.UseItem(source, item) lets you trigger the handler yourself.

Official addons follow the same pattern, for example esx_basicneeds (bread, water) and esx_ambulancejob (bandage, medikit).

Work with items in scriptsCopy Anchor Link

The most used xPlayer inventory methods:

local xPlayer = ESX.GetPlayerFromId(source)

local item = xPlayer.getInventoryItem('lockpick')   -- { name, label, count, weight, usable, rare, canRemove }
if item and item.count >= 1 then
    xPlayer.removeInventoryItem('lockpick', 1)
end

if xPlayer.canCarryItem('energy_drink', 3) then
    xPlayer.addInventoryItem('energy_drink', 3)
else
    xPlayer.showNotification('Your pockets are full')
end

Use ESX.GetItemLabel(name) to show the label of an item, and ESX.GetItems() to get the full item registry.

Starting itemsCopy Anchor Link

Config.StartingInventoryItems in es_extended/shared/config/main.lua is false by default. Set it to a table of item = count to give new characters items on creation:

Config.StartingInventoryItems = { bread = 2, water = 2 }

It only applies to newly created players, not to existing ones.

ox_inventory noteCopy Anchor Link

ox_inventory has its own item list and its own way of handling item use:

• Define items in ox_inventory/data/items.lua. The ESX items table has no effect while ox mode is active.
• ESX.Items is filled from ox_inventory's item list, and ESX.GetItemLabel reads from exports.ox_inventory:Items(name).
• xPlayer.addInventoryItem, removeInventoryItem, getInventoryItem, canCarryItem and hasItem still work; ESX routes them to ox_inventory.
• ox_inventory can run code on use through its item options (for example a server.export). Check the ox_inventory docs for how it handles items registered with ESX.RegisterUsableItem.

Details and setup order: Using ox_inventory with ESX.

Common issuesCopy Anchor Link

RelatedCopy Anchor Link

• xPlayer reference
• Using ox_inventory with ESX
• Database schema
• esx_inventory
• esx_basicneeds

Frequently asked questions