Inventories: stack, weight, slot

The two models: slot and weight

The mental model first. There are two common ways to limit what a player can carry.

• Slot-based. The inventory is a fixed grid of numbered pockets, say 50 slots. Each kind of item occupies a slot, and a slot holds up to a stack limit of that item. Run out of free slots and you cannot carry more, even if each item is feather-light.
• Weight-based. The inventory has a single kilogram cap, say 60 kg. Nothing else is counted. Carry one heavy item or a thousand light ones, the only question is the total weight.

ox_inventory enforces both at once: every player has a slot count and a weight cap. When someone tries to pick something up, the inventory checks whether it fits under both the slot and weight caps first, and refuses the pickup if it does not. That is why a player can be blocked from grabbing loot even though their bag looks half empty: they have hit the weight cap, not the slot cap.

Stacking and metadata

Identical items stack. Two units of an item are identical when they share the same name and the same metadata, so they merge into one slot and the slot's count goes up. That is what keeps a slot-based inventory usable: 64 rounds of ammo sit in one slot, not 64.

Metadata is the per-item data attached to a single stack: durability, a weapon serial, a registered owner, a crafting quality. The rule that follows is the one to memorize. Items only stack when their metadata matches. Two burgers with different metadata can no longer share a slot, because they are no longer identical, so they occupy two slots with a count of 1 each. This is exactly how unique items work. A serialized pistol cannot stack with another pistol, because each carries a different serial in its metadata. A plain burger and a burger carrying quality metadata split into two separate slots for the same reason.

Where the item itself is defined

An item name is not magic. It is a key in ox_inventory's data/items.lua, a single Lua table where each key is the canonical item name and each value is that item's config. If a name is not in this table, the inventory rejects it with invalid_item, which is exactly the failure mode listed below. As an owner you edit this file to define what items exist on your server; you do not need to write a script to do it.

Here is the testburger entry from ox_inventory's own data/items.lua, trimmed to two example buttons for readability (the real file adds three more grouped "Hamburger Puns" buttons). Note stack is absent because it defaults to true, weight is in grams not kilograms, and consume = 0.3 drains durability per use instead of removing a whole item:

['testburger'] = {
    label = 'Test Burger',
    weight = 220,
    degrade = 60,
    client = {
        image = 'burger_chicken.png',
        status = { hunger = 200000 },
        anim = 'eating',
        prop = 'burger',
        usetime = 2500,
        export = 'ox_inventory_examples.testburger'
    },
    server = {
        export = 'ox_inventory_examples.testburger',
        test = 'what an amazingly delicious burger, amirite?'
    },
    buttons = {
        { label = 'Lick it', action = function(slot) print('You licked the burger') end },
        { label = 'Squeeze it', action = function(slot) print('You squeezed the burger :(') end }
    },
    consume = 0.3
}

The key ('testburger') is the string used everywhere: in shops, in the database, and by the give command below. The icon is a PNG in web/images/ named after the key (or after client.image when set, here burger_chicken.png). After you edit data/items.lua you must restart ox_inventory so it reloads the definitions, otherwise the running server keeps rejecting the new name with invalid_item.

data/items.lua   return { ['key'] = { config } }

['testburger']
  label    "Test Burger"   display name
  weight   220             grams, not kg
  stack    absent -> true  identical items merge
  consume  0.3             drains durability, not a whole item
  client   { image, status, anim, prop, usetime, export }
  server   { export, ...custom keys }
  buttons  { right-click menu entries }

web/images/burger_chicken.png   icon, filename = client.image (or the key)

A one-line note on the paid alternative: qs-inventory (Quasar Store) defines items in shared/items.lua with a flatter QBCore-style shape and uses unique = true where ox uses stack = false, so an ox item config will not stack correctly if you paste it straight into qs without translating those fields. Defining a full item in both is its own walkthrough: Create a usable item in ox_inventory (and qs-inventory).

The owner way to give an item: /giveitem

Once an item is defined in the items file, you do not need to write a script to hand it to a player. Every major inventory ships a built-in admin command:

/giveitem [id] [item] [count]

Run it from the server console or in game as an admin. [id] is the target player's server id, [item] is the item key from data/items.lua, and [count] is how many. For example, /giveitem 1 burger 5 hands five burgers to the player with server id 1. Most inventories also expose an in-game admin menu that gives items by clicking. This built-in command is ACE-gated, so grant it to your admin group first, for example add_ace group.admin command.giveitem allow. If the item name is not in the items file, the give fails with invalid_item.