FiveM NUI: cómo funciona, errores comunes y la skill de IA

FiveM NUI es el sistema que permite a un recurso dibujar su interfaz con HTML, CSS y JavaScript dentro de un navegador embebido. Cada inventario, teléfono, HUD y menú de tienda personalizado en un servidor FiveM es una página NUI. Si construyes una interfaz que ox_lib no cubre, necesitas entender cómo se declara la página, cómo se comunican Lua y JavaScript y dónde está la frontera de seguridad.

Qué te da FiveM NUI

El recurso declara su página en fxmanifest.lua con ui_page 'html/index.html' y lista cada asset que cargará el navegador en el bloque files {}. La página se renderiza a pantalla completa sobre el juego.

• De Lua a JavaScript. SendNUIMessage({ action = 'open', data = ... }) en el cliente envía un objeto JSON. La página lo recibe con window.addEventListener('message', ...) y lee event.data.
• Foco y cursor. SetNuiFocus(hasFocus, hasCursor) decide si la página captura teclado y ratón. Abre con SetNuiFocus(true, true) y cierra con SetNuiFocus(false, false).
• De JavaScript a Lua. RegisterNUICallback('close', function(data, cb) ... cb('ok') end) en el cliente. La página lo llama con fetch('https://<resource-name>/close', { method: 'POST', body: JSON.stringify(data) }). Usa GetParentResourceName() en JS para obtener el nombre del recurso sin escribirlo a mano.
• Seguridad. El código NUI corre en la máquina del jugador. Todo lo que envíe debe validarse en el servidor antes de tocar dinero, items o la base de datos.

Los natives están documentados en docs.fivem.net/natives.

Errores comunes con FiveM NUI

• Olvidar SetNuiFocus(false, false) al cerrar. La página desaparece pero el jugador no puede moverse ni abrir el menú de pausa. Cada ruta de cierre, incluida la tecla Escape y el botón de cerrar, debe liberar el foco.
• URL equivocada en fetch. La carpeta del recurso se llama my-shop pero el JS llama a https://myshop/buy. La consola F8 muestra un 404 o "failed to fetch". Usa GetParentResourceName() y mantén el nombre del callback idéntico en ambos lados.
• No llamar nunca a cb. El callback Lua se ejecuta, hace su trabajo y termina sin cb(...). La promesa del fetch en JS nunca se resuelve y la UI se queda colgada. Llama a cb siempre, aunque sea con una tabla vacía.
• Confiar en los datos de la NUI como si el servidor los hubiera validado. Un callback recibe { price = 0 } y el cliente lo reenvía al servidor, que cobra cero. Los callbacks NUI llegan del cliente, así que el servidor debe consultar precios y permisos por su cuenta.
• Archivos que faltan en files {}. La página carga en blanco y la consola F8 muestra un 404 para la hoja de estilos o el script. Cada archivo que carga la página debe estar listado, incluidas imágenes y fuentes.

Por qué los asistentes de IA se equivocan con FiveM NUI

Los asistentes genéricos confunden las capas. Ponen SendNUIMessage en un script de servidor, se inventan un RegisterNUICallback en el servidor o escriben fetch('/callback') con una ruta relativa que el navegador CEF no puede resolver. También tratan el payload del callback como entrada de confianza y escriben lógica de negocio en el cliente, que cualquier jugador puede editar.

La skill de FiveM NUI da al asistente un archivo de reglas por tema: setup.md para el manifest y la estructura de carpetas, fullscreen-nui.md para mensajería y foco, nui-callbacks.md para el contrato del callback y sus reglas de seguridad, best-practices.md para rendimiento y manejo de errores, y reference-links.md para la documentación oficial. El asistente lee la regla correspondiente y escribe el native correcto en el lado correcto.

Instala la skill de FiveM NUI 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 "un menú a pantalla completa que se abre con un comando y se cierra con Escape", y comprueba que usa SetNuiFocus, RegisterNUICallback con cb y lista todos los archivos en fxmanifest.lua.