ox_inventory for FiveM: what it is, common mistakes and the AI skill

View on skills.sh

Updated

Download SKILL.mdCommunity

Don’t want to manage skills yourself? Get the full app.

ox_inventory is the slot-based FiveM inventory with weight, item metadata, stashes, shops and hooks. You grant and remove items on the server through exports.ox_inventory. This guide covers the API, the mistakes that lose or dupe items and the AI skill.

ox_inventory is a slot-based inventory for FiveM with item weight, metadata, stashes, shops and hooks. It supports ox_core, ESX and qbx_core. Everything goes through exports.ox_inventory:<fn>(...), because there is no global table, and every change to items belongs on the server.

What the ox_inventory skill gives you

The skill is organized around the decisions you make while scripting items:

  • AddItem, RemoveItem and GetItemCount to give, take and count items.
  • CanCarryItem to check space before you commit a trade or a reward.
  • GetSlot and Search to read one slot or find items across slots.
  • RegisterStash for persistent storage and CreateTemporaryStash for short-lived storage.
  • registerHook to react to moves, opens and purchases instead of polling.

Rule files cover the server exports, the client exports, defining items in data/items.lua, stashes and shops, and hooks. The upstream reference is overextended.dev/ox_inventory.

Common mistakes with ox_inventory

  • Granting items from the client. Client exports are for display and UI decisions. Add, remove and count items on the server only.
  • Ignoring the return value of AddItem. The player may be over weight or out of slots. Check the result before you tell the player they received something.
  • Checking space after taking payment. Call CanCarryItem first, then take payment, then AddItem, then verify the return.
  • Inventing item names. An item that is not in data/items.lua fails silently. Define the item first, then reference it.
  • Putting volatile data in metadata. Items with different metadata do not stack. Counters and timestamps turn one stack into dozens of slots.
  • Passing the wrong inventory id. inv is a player source, an identifier or a stash id. A wrong value returns nil, not an error.

Why AI assistants get ox_inventory wrong

Most inventory code an assistant has seen targets qb-inventory or an old ESX inventory. Ask for "give the player a sandwich" and you often get a framework-specific call, an invented item name or a client-side grant. None of that behaves correctly on ox_inventory.

The ox_inventory skill states the real function names, the server and client split and the order of calls for a trade. The assistant reads the rule that matches your request and writes code that checks CanCarryItem, calls AddItem on the server and includes the data/items.lua entry when it introduces a new item.

Install the ox_inventory skill in 30 seconds

  1. Click "Download SKILL.md" at the top of this page.
  2. Unzip it into the skills or rules folder of your AI tool. The install section below shows the exact path for Claude Code, Cursor and VS Code.
  3. Ask the assistant for something concrete, like "give a player a sandwich after a successful purchase", and check that it calls CanCarryItem and then AddItem on the server and checks the return value.

How to install this skill

Download the zip, unzip it, and place the folder where your tool loads skills or rules. The exact path depends on the tool:

Claude Code

Unzip into .claude/skills/ox-inventory/ inside the project (the folder must contain SKILL.md). For every project, use ~/.claude/skills/ox-inventory/ instead.

Claude Code skills docs

Cursor

Cursor loads project rules from .cursor/rules/. Add a rule file there that points to the unzipped skill, or paste the contents of SKILL.md and the rule files into a rule. The format is .mdc with frontmatter and changes between versions, so check the docs for your version.

Cursor rules docs

VS Code / Copilot

Copilot reads instruction files from .github/instructions/*.instructions.md. Copy SKILL.md there with an applyTo glob for your Lua files, and keep the rule files next to it.

VS Code custom instructions docs

The SKILL.md file

This is the file your AI assistant reads. It links to the rule files bundled in the download.

Skill contents (includes SKILL.md and any other files)

ox_inventory

Slot-based inventory with weight, metadata, stashes, shops and hooks. Supports ox_core, esx and qbx_core.

Activation Contract

Load this skill when the user asks to give, take, count or check items, register a stash or shop, define a new item, react to inventory actions, or migrate from qb-inventory or esx inventory.

Hard Rules

  • Call everything through exports.ox_inventory:<fn>(...). There is no global table.
  • Grant, remove and count items on the SERVER only. Client exports are for display and UI decisions.
  • AddItem can fail. Always check the return value: the player may be over weight or out of slots.
  • Check CanCarryItem BEFORE taking payment or removing the traded item, never after.
  • Never invent item names. An item must exist in data/items.lua or it silently fails.
  • inv is a player source, an identifier, or a stash id. Passing the wrong one returns nil, not an error.
  • Metadata makes items non-stackable when it differs. Do not put volatile data in metadata.

Decision Gates

Goal Call
Give an item AddItem(inv, item, count, metadata, slot)
Take an item RemoveItem(inv, item, count, metadata, slot)
Check space first CanCarryItem(inv, item, count, metadata)
How many does the player have GetItemCount(inv, item, metadata, strict)
Read one slot GetSlot(inv, slot)
Find items across slots Search(inv, 'slots'|'count', item, metadata)
Persistent storage RegisterStash(...)
Short-lived storage CreateTemporaryStash(properties)
React to a player action registerHook(event, cb, options)

Execution Steps

  1. Confirm ox_inventory starts after ox_lib and the framework core.
  2. Decide the side: mutation is server, display is client.
  3. For a trade or reward, order the calls: CanCarryItem -> take payment -> AddItem -> verify the return.
  4. Define any new item in data/items.lua before referencing it. Read rules/items.md.
  5. Use hooks instead of polling when reacting to moves, opens or purchases.

Output Contract

Return runnable Lua using exports.ox_inventory, with the server/client split explicit. Include the data/items.lua entry whenever a new item is introduced.

References

  • rules/server-exports.md — item and inventory functions on the server.
  • rules/client-exports.md — weight, current weapon, opening inventories.
  • rules/items.md — defining items in data/items.lua.
  • rules/stashes.md — stashes, shops and temporary storage.
  • rules/hooks.md — registerHook and cancelling actions.

Upstream docs: https://overextended.dev/ox_inventory

Frequently asked questions

Does ox_inventory work with ESX and QBCore?
It supports ox_core, ESX and qbx_core, according to the skill. For other setups, check the resource documentation before you migrate.
Is ox_inventory free?
Yes. ox_inventory is open source and published on GitHub by the Overextended and CommunityOx teams, so you can run it on any server at no cost.
Why does AddItem return false?
The player is probably over the weight limit or out of slots. AddItem can fail, so always check its return value, and call CanCarryItem before you take payment or remove the traded item.

Related guides

Longer reads from the FiveAI blog on the same topic.

More skills