ox_inventory item metadata: AddItem, Search, SetMetadata and unique items

An item in ox_inventory is a name and a count. When two items of the same name need to be different, such as a car key for one plate and a key for another, you use metadata: a table stored with the item. This article shows how to add an item with metadata, find it again, read and update it, display it, and build unique items like IDs and keys.

#Add an item with metadata

The fourth argument of AddItem is the metadata table:

exports.ox_inventory:AddItem(source, 'car_key', 1, {
    plate = 'ABC 123',
    label = 'Key ABC 123',
    description = 'Opens the car with plate ABC 123.',
})

The signature is AddItem(inventory, item, count, metadata). inventory is the player id for a player inventory. Any key you add is stored with the slot, and you can read it back later. Keep metadata small and made of plain data: strings, numbers, booleans and simple tables.

Tip: the item must exist in data/items.lua, for example car_key. See adding items to ox_inventory.

#Show it to the player

A few metadata keys change what the inventory displays:

exports.ox_inventory:AddItem(source, 'id_card', 1, {
    label = 'ID card: Jane Doe',
    description = 'Born 1994-05-12',
    image = 'id_card',
})

Everything else you put in the table is stored, but not shown, unless the item's own definition displays it. Use a unique label when you need players to tell items apart at a glance.

#Search for items

Search finds items in an inventory. With 'count' it returns how many, with 'slots' it returns the slots:

local count = exports.ox_inventory:Search(source, 'count', 'car_key')

local slots = exports.ox_inventory:Search(source, 'slots', 'car_key')
for _, slot in pairs(slots) do
    print(slot.slot, slot.metadata and slot.metadata.plate)
end

You can also filter by metadata. Pass a table as the fourth argument:

local keys = exports.ox_inventory:Search(source, 'slots', 'car_key', { plate = 'ABC 123' })
if #keys > 0 then
    -- the player has the key for that plate
end

This is the standard way to check ownership: do it on the server, with the data you trust, never from a client message.

#Read one slot

If you know the slot number, GetSlot returns that slot's data:

local slot = exports.ox_inventory:GetSlot(source, 5)
if slot and slot.name == 'car_key' then
    print(slot.metadata.plate)
end

When you only know the item, use GetSlotWithItem:

local slot = exports.ox_inventory:GetSlotWithItem(source, 'car_key', { plate = 'ABC 123' })

Both return nil when nothing matches, so check the result before reading slot.metadata. A slot also has slot.count and slot.weight.

#Update metadata with SetMetadata

To change an existing slot, for example mark a key as copied, or reduce the charges left on an item, use SetMetadata:

local slot = exports.ox_inventory:GetSlotWithItem(source, 'battery')
if slot then
    local metadata = slot.metadata or {}
    metadata.charge = (metadata.charge or 100) - 10
    exports.ox_inventory:SetMetadata(source, slot.slot, metadata)
end

SetMetadata(inventory, slot, metadata) replaces the slot's metadata with the table you give. Copy the existing table first, change one field, and send the whole table back, otherwise you erase the other keys.

#Unique items: IDs, keys, licenses

For a unique item you want two things: an item that does not stack, and metadata that identifies it.

-- data/items.lua
['id_card'] = {
    label = 'ID card',
    weight = 10,
    stack = false,
    close = true,
},

-- server: give it at character creation
exports.ox_inventory:AddItem(source, 'id_card', 1, {
    firstname = 'Jane',
    lastname = 'Doe',
    dob = '1994-05-12',
    label = 'ID card: Jane Doe',
})

Items with different metadata do not stack, so two keys for two cars always take two slots, and stack = false makes that explicit for items that never should.

To read the data when the item is used, register a server export on the item:

-- data/items.lua
['id_card'] = {
    label = 'ID card',
    weight = 10,
    stack = false,
    server = { export = 'my_script.id_card' },
},

-- my_script/server.lua
exports('id_card', function(event, item, inventory, slot, data)
    if event == 'usingItem' then
        local info = exports.ox_inventory:GetSlot(inventory.id, slot)
        if info and info.metadata then
            print(info.metadata.firstname, info.metadata.lastname)
        end
    end
end)

The event argument tells you the phase of the use. The exact arguments depend on your ox_inventory version, so check the documentation for your release if the export is not called.

#Things to watch

• Metadata lives on the slot. When the player drops or trades the item, it moves with it, and it is the item that proves the right to access something.
• Do not put secrets in metadata. Players do not see unlisted keys, but treat them as data, not as protection.
• A lot of items with large metadata tables makes inventory saving slower. Store an id and keep the heavy data in your own database table.
• Metadata set on the client is not trusted. Always call AddItem and SetMetadata from server code.

#Checklist