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

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

1. Haz clic en "Download SKILL.md" en la parte superior de esta página.
2. 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.
3. 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.