ox_inventory para FiveM: qué es, errores comunes y la skill de IA

Ver en skills.sh

Actualizado

Descargar SKILL.mdComunidad

¿No quieres gestionar las skills tú mismo? Consigue la app completa.

ox_inventory es el inventario de FiveM basado en slots, con peso, metadata, stashes, tiendas y hooks. Los ítems se dan y se quitan en el servidor con exports.ox_inventory. Esta guía cubre la API, los errores que pierden o duplican ítems y la skill de IA.

ox_inventory es un inventario para FiveM basado en slots, con peso de ítems, metadata, stashes, tiendas y hooks. Es compatible con ox_core, ESX y qbx_core. Todo pasa por exports.ox_inventory:<fn>(...), porque no existe una tabla global, y cualquier cambio de ítems va en el servidor.

Qué te da la skill de ox_inventory

La skill se organiza alrededor de las decisiones que tomas al programar ítems:

  • AddItem, RemoveItem y GetItemCount para dar, quitar y contar ítems.
  • CanCarryItem para comprobar el espacio antes de cerrar un intercambio o una recompensa.
  • GetSlot y Search para leer un slot o buscar ítems en varios slots.
  • RegisterStash para almacenamiento persistente y CreateTemporaryStash para almacenamiento temporal.
  • registerHook para reaccionar a movimientos, aperturas y compras sin hacer polling.

Los archivos de reglas cubren los exports de servidor y de cliente, la definición de ítems en data/items.lua, stashes y tiendas, y hooks. La referencia original está en overextended.dev/ox_inventory.

Errores comunes con ox_inventory

  • Dar ítems desde el cliente. Los exports de cliente sirven para mostrar y decidir en la interfaz. Añade, quita y cuenta ítems solo en el servidor.
  • Ignorar el retorno de AddItem. El jugador puede superar el peso o quedarse sin slots. Comprueba el resultado antes de decirle que recibió algo.
  • Comprobar el espacio después de cobrar. Llama primero a CanCarryItem, luego cobra, luego AddItem y después verifica el retorno.
  • Inventar nombres de ítems. Un ítem que no está en data/items.lua falla en silencio. Defínelo primero y luego referéncialo.
  • Meter datos volátiles en la metadata. Los ítems con metadata distinta no se apilan. Contadores y marcas de tiempo convierten un stack en decenas de slots.
  • Pasar un id de inventario equivocado. inv es el source de un jugador, un identificador o el id de un stash. Un valor incorrecto devuelve nil, no un error.

Por qué los asistentes de IA se equivocan con ox_inventory

Casi todo el código de inventario que ha visto un asistente apunta a qb-inventory o a un inventario ESX antiguo. Si pides "dale un sándwich al jugador", suele salir una llamada propia de un framework, un nombre de ítem inventado o una entrega desde el cliente. Nada de eso funciona bien en ox_inventory.

La skill de ox_inventory fija los nombres reales de las funciones, la división entre servidor y cliente y el orden de las llamadas en un intercambio. El asistente lee la regla que encaja con tu petición y escribe código que comprueba CanCarryItem, llama a AddItem en el servidor e incluye la entrada de data/items.lua cuando introduce un ítem nuevo.

Instala la skill de ox_inventory en 30 segundos

  1. Haz clic en "Download SKILL.md" en la parte superior de esta página.
  2. Descomprímela en la carpeta de skills o reglas de tu herramienta de IA. La sección de instalación de más abajo muestra la ruta exacta para Claude Code, Cursor y VS Code.
  3. Pídele al asistente algo concreto, como "dale un sándwich al jugador tras una compra correcta", y comprueba que llama a CanCarryItem y después a AddItem en el servidor y comprueba el retorno.

Cómo instalar esta skill

Descarga el zip, descomprímelo y coloca la carpeta donde tu herramienta carga skills o reglas. La ruta exacta depende de la herramienta:

Claude Code

Descomprime en .claude/skills/ox-inventory/ dentro del proyecto (la carpeta debe contener SKILL.md). Para todos los proyectos, usa ~/.claude/skills/ox-inventory/.

Documentación de skills de Claude Code

Cursor

Cursor carga las reglas del proyecto desde .cursor/rules/. Añade ahí un archivo de regla que apunte a la skill descomprimida, o pega el contenido de SKILL.md y los archivos de reglas en una regla. El formato es .mdc con frontmatter y cambia entre versiones, así que revisa la documentación de tu versión.

Documentación de reglas de Cursor

VS Code / Copilot

Copilot lee archivos de instrucciones desde .github/instructions/*.instructions.md. Copia SKILL.md ahí con un glob applyTo para tus archivos Lua y deja los archivos de reglas al lado.

Documentación de instrucciones de VS Code

El archivo SKILL.md

Este es el archivo que lee tu asistente de IA. Enlaza a los archivos de reglas incluidos en la descarga.

Contenido de la skill (incluye SKILL.md y cualquier otro archivo)

El contenido de la skill está en inglés: es documentación técnica pensada 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

Preguntas frecuentes

¿ox_inventory funciona con ESX y QBCore?
Según la skill, es compatible con ox_core, ESX y qbx_core. Para otras configuraciones, revisa la documentación del recurso antes de migrar.
¿ox_inventory es gratis?
Sí. ox_inventory es open source y lo publican en GitHub los equipos de Overextended y CommunityOx, así que puedes usarlo en cualquier servidor sin coste.
¿Por qué AddItem devuelve false?
Lo más probable es que el jugador haya superado el límite de peso o no tenga slots libres. AddItem puede fallar, así que comprueba siempre su retorno y llama a CanCarryItem antes de cobrar o quitar el ítem del intercambio.

Guías relacionadas

Lecturas más largas del blog de FiveAI sobre el mismo tema.

Más skills