ox_inventory para FiveM: o que é, erros comuns e a skill de IA

Ver no skills.sh

Atualizado em

Baixar SKILL.mdComunidade

Não quer gerenciar as skills por conta própria? Obtenha o app completo.

O ox_inventory é o inventário do FiveM baseado em slots, com peso, metadata, stashes, lojas e hooks. Os itens são dados e removidos no servidor com exports.ox_inventory. Este guia cobre a API, os erros que perdem ou duplicam itens e a skill de IA.

O ox_inventory é um inventário para FiveM baseado em slots, com peso de itens, metadata, stashes, lojas e hooks. É compatível com ox_core, ESX e qbx_core. Tudo passa por exports.ox_inventory:<fn>(...), porque não existe tabela global, e qualquer mudança de itens fica no servidor.

O que a skill de ox_inventory oferece

A skill se organiza em torno das decisões que você toma ao programar itens:

  • AddItem, RemoveItem e GetItemCount para dar, remover e contar itens.
  • CanCarryItem para checar o espaço antes de fechar uma troca ou recompensa.
  • GetSlot e Search para ler um slot ou procurar itens em vários slots.
  • RegisterStash para armazenamento persistente e CreateTemporaryStash para armazenamento temporário.
  • registerHook para reagir a movimentações, aberturas e compras sem fazer polling.

Os arquivos de regras cobrem os exports de servidor e de cliente, a definição de itens em data/items.lua, stashes e lojas, e hooks. A referência original está em overextended.dev/ox_inventory.

Erros comuns com o ox_inventory

  • Dar itens pelo cliente. Os exports de cliente servem para exibir e decidir na interface. Adicione, remova e conte itens só no servidor.
  • Ignorar o retorno do AddItem. O jogador pode estar acima do peso ou sem slots. Confira o resultado antes de dizer que ele recebeu algo.
  • Checar o espaço depois de cobrar. Chame CanCarryItem primeiro, depois cobre, depois AddItem e então verifique o retorno.
  • Inventar nomes de itens. Um item que não está em data/items.lua falha em silêncio. Defina primeiro e só depois referencie.
  • Colocar dados voláteis na metadata. Itens com metadata diferente não empilham. Contadores e timestamps transformam um stack em dezenas de slots.
  • Passar um id de inventário errado. inv é o source de um jogador, um identificador ou o id de um stash. Um valor errado retorna nil, não um erro.

Por que assistentes de IA erram no ox_inventory

A maior parte do código de inventário que um assistente já viu mira o qb-inventory ou um inventário ESX antigo. Se você pede "dê um sanduíche ao jogador", costuma vir uma chamada específica de framework, um nome de item inventado ou uma entrega pelo cliente. Nada disso funciona direito no ox_inventory.

A skill do ox_inventory fixa os nomes reais das funções, a divisão entre servidor e cliente e a ordem das chamadas em uma troca. O assistente lê a regra que combina com o seu pedido e escreve código que checa CanCarryItem, chama AddItem no servidor e inclui a entrada de data/items.lua quando introduz um item novo.

Instale a skill de ox_inventory em 30 segundos

  1. Clique em "Download SKILL.md" no topo desta página.
  2. Descompacte na pasta de skills ou regras da sua ferramenta de IA. A seção de instalação abaixo mostra o caminho exato para Claude Code, Cursor e VS Code.
  3. Peça ao assistente algo concreto, como "dê um sanduíche ao jogador depois de uma compra bem-sucedida", e confira se ele chama CanCarryItem e depois AddItem no servidor e confere o retorno.

Como instalar esta skill

Baixe o zip, descompacte e coloque a pasta onde a sua ferramenta carrega skills ou regras. O caminho exato depende da ferramenta:

Claude Code

Descompacte em .claude/skills/ox-inventory/ dentro do projeto (a pasta precisa conter SKILL.md). Para todos os projetos, use ~/.claude/skills/ox-inventory/.

Documentação de skills do Claude Code

Cursor

O Cursor carrega as regras do projeto de .cursor/rules/. Adicione ali um arquivo de regra apontando para a skill descompactada, ou cole o conteúdo do SKILL.md e dos arquivos de regras em uma regra. O formato é .mdc com frontmatter e muda entre versões, então confira a documentação da sua versão.

Documentação de regras do Cursor

VS Code / Copilot

O Copilot lê arquivos de instruções em .github/instructions/*.instructions.md. Copie o SKILL.md para lá com um glob applyTo para os seus arquivos Lua e mantenha os arquivos de regras ao lado.

Documentação de instruções do VS Code

O arquivo SKILL.md

Este é o arquivo que o seu assistente de IA lê. Ele aponta para os arquivos de regras incluídos no download.

Conteúdo da skill (inclui SKILL.md e quaisquer outros arquivos)

O conteúdo da skill está em inglês: é documentação técnica feita para agentes de IA.

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

Perguntas frequentes

O ox_inventory funciona com ESX e QBCore?
Segundo a skill, ele é compatível com ox_core, ESX e qbx_core. Para outras configurações, confira a documentação do recurso antes de migrar.
O ox_inventory é gratuito?
Sim. O ox_inventory é open source e publicado no GitHub pelas equipes Overextended e CommunityOx, então você pode usá-lo em qualquer servidor sem custo.
Por que o AddItem retorna false?
O mais provável é que o jogador tenha passado do limite de peso ou ficado sem slots. O AddItem pode falhar, então confira sempre o retorno e chame CanCarryItem antes de cobrar ou remover o item da troca.

Guias relacionados

Leituras mais longas do blog da FiveAI sobre o mesmo tema.

Mais skills