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

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

ox_lib es una librería standalone para FiveM que da a tus recursos UI lista para usar, callbacks cliente-servidor, comandos, zonas y utilidades compartidas. Recursos como ox_inventory y ox_target dependen de ella, y la mayoría de servidores ESX y QBCore modernos ya la tienen instalada. Si escribes scripts para un servidor con ox_lib, úsala en lugar de montar tu propia NUI o copiar código de menús antiguo.

Qué te da ox_lib

El setup es una línea en fxmanifest.lua: shared_scripts { '@ox_lib/init.lua' }. Puedes añadir ox_libs { 'locale', 'callback' } para precargar los módulos que uses con frecuencia.

Interfaz. lib.notify para notificaciones, lib.alertDialog para confirmaciones, lib.inputDialog para formularios, además de menús contextuales, barras de progreso y TextUI. Los iconos vienen de Font Awesome 6.
Callbacks. lib.callback.register en el servidor, lib.callback.await en el cliente. El cliente pregunta, el servidor responde y recibes el valor en la misma línea.
Comandos. lib.addCommand en el servidor con help, params y restricted, para que el comando valide sus argumentos y compruebe permisos por ti.
Zonas. lib.zones.poly, lib.zones.box y lib.zones.sphere con handlers onEnter, onExit e inside. Úsalas en el cliente. El soporte en servidor es limitado.
Utilidades. Keybinds, locales, lib.table, lib.string y otros módulos compartidos.

La referencia completa está en coxdocs.dev/ox_lib.

Errores comunes con ox_lib

Olvidar @ox_lib/init.lua en el manifest. El script carga y muere con “attempt to index a nil value (global ‘lib’)”. Añade shared_scripts { '@ox_lib/init.lua' } y asegúrate de que ox_lib arranca antes que tu recurso.
Registrar el callback en el lado equivocado. Un cliente que llama a lib.callback.await('myjob:getData') no recibe nada porque el callback también se registró en el cliente. Registra con lib.callback.register en el servidor y espera con await en el cliente. Si el servidor necesita preguntar a un cliente, pasa el source del jugador como segundo argumento.
Usar un callback para avisar y olvidar. Si el cliente solo necesita decirle al servidor “pulsé el botón”, basta con un net event. Los callbacks bloquean hasta que llega la respuesta, así que úsalos solo cuando necesites un valor de vuelta.
Tratar las zonas como función de servidor. Las zonas corren en el cliente, donde está la posición del jugador. El soporte de zonas en servidor es limitado, así que detecta entradas y salidas en el cliente y manda el resultado al servidor si lo necesitas.
Mezclar patrones antiguos. Llamadas exports.ox_lib, menús ESX viejos y una NUI propia para un simple diálogo de confirmación son señales de código escrito antes de que existiera ox_lib. Sustitúyelos por lib.alertDialog, lib.inputDialog y menús contextuales.

Por qué los asistentes de IA se equivocan con ox_lib

Un asistente genérico ha visto años de código FiveM, casi todo escrito antes de ox_lib o con una versión antigua. Pide un diálogo de confirmación y puede inventarse un export como exports.ox_lib:showDialog, escribir un menú ESX o darte un callback registrado en el cliente. El código parece correcto y falla en la primera ejecución.

La skill de ox_lib lo corrige con archivos de reglas, uno por módulo: init.md, callback.md, interface.md, addCommand.md y zones.md. Cada uno indica los nombres reales de las funciones, a qué lado de la red pertenecen y qué argumentos reciben. El asistente lee la regla que coincide con tu petición y escribe contra la API documentada en vez de adivinar.

Instala la skill de ox_lib en 30 segundos

Haz clic en “Download SKILL.md” en la parte superior de esta página.
Descomprímelo en la carpeta de skills o rules de tu herramienta de IA. La sección de instalación de abajo muestra la ruta exacta para Claude Code, Cursor y VS Code.
Pide al asistente algo concreto, como “añade un callback de servidor que devuelva el trabajo del jugador y muéstralo con lib.notify”, y comprueba que usa lib.callback.register en el servidor y lib.callback.await en el cliente.

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/oxlib/ dentro del proyecto (la carpeta debe contener SKILL.md). Para todos los proyectos, usa ~/.claude/skills/oxlib/.

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_lib

Shared FiveM library: UI (notify, dialogs, menus, progress), client/server callbacks, commands and zones via the global lib.

Activation Contract

Load this skill when the user needs notifications, alert or input dialogs, menus, progress bars, TextUI, a client-server request/response, a typed server command, zones ("player enters/leaves area"), keybinds, or any resource that depends on ox_lib.

Hard Rules

Add shared_scripts { '@ox_lib/init.lua' } to fxmanifest.lua and ensure ox_lib starts before the resource; without it lib is nil.
Prefer lib.callback / lib.callback.await over paired events or framework-specific callbacks for data across the network.
lib.callback.register(name, function(source, ...)) on the server receives source first; validate arguments there.
Callback names must be unique (resourcename:action).
UI functions (lib.notify, lib.alertDialog, lib.inputDialog, lib.progress, lib.context, lib.menu, lib.showTextUI) render on the CLIENT; from the server trigger the client to call them.
Icons are Font Awesome 6, default style solid; brand icons use {'fab', 'name'}.
lib.addCommand is SERVER-side; use restricted for permissions and typed params (number, playerId, string, longString).
Zones: onEnter, onExit and inside do not work on the server; create zones on the client. Keep the returned zone to call zone:remove().
Modules load on first use or via ox_libs { ... } / lib.require.

Decision Gates

Need	Call
Toast message	`lib.notify({ title, description, type })`
Confirm / OK dialog	`lib.alertDialog({ header, content, centered, cancel })`
Form input	`lib.inputDialog(title, rows)`
Client asks server	`lib.callback.await(name, false, ...)` + server `lib.callback.register`
Server asks client	`lib.callback.await(name, source, ...)` + client `lib.callback.register`
Chat command with args	`lib.addCommand(name, { help, params, restricted }, cb)`
Area trigger	`lib.zones.poly` / `lib.zones.box` / `lib.zones.sphere`

Execution Steps

Add the manifest line and start order (read rules/init.md).
Pick the call from Decision Gates; read the matching rules file for the option table.
Put request handling on the server callback; put UI on the client.
Name callbacks and commands with the resource prefix.
Store zone handles for removal.

Output Contract

Return runnable Lua using the global lib, with the manifest line when the resource is new and the client/server side explicit.

References

rules/init.md — fxmanifest, shared_script, ox_libs, lib.require.
rules/callback.md — lib.callback, await, register on both sides.
rules/interface.md — notify, alertDialog, inputDialog, other UI modules, icons.
rules/addCommand.md — server commands with help, params, restricted.
rules/zones.md — poly, box, sphere zones, methods and utilities.

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

Preguntas frecuentes

¿ox_lib funciona con ESX y QBCore?

Sí. ox_lib es standalone y no depende de ningún framework. Los servidores ESX y QBCore lo usan, y las skills de FiveAI para esos frameworks lo recomiendan para notificaciones, diálogos y menús.

¿ox_lib es gratis?

Sí. ox_lib es open source y está publicado en GitHub bajo licencia LGPL. Puedes usarlo en cualquier servidor sin pagar, siempre que respetes los términos de la licencia.

¿Puedo usar esta skill con ChatGPT?

Sí, con un paso manual. El SKILL.md es markdown plano, así que puedes pegarlo en la conversación como contexto. El soporte nativo de skills es para Claude Code, Cursor y VS Code.

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