FiveM NUI: como funciona, erros comuns e a skill de IA

FiveM NUI é o sistema que permite a um recurso desenhar sua interface com HTML, CSS e JavaScript dentro de um navegador embutido. Cada inventário, celular, HUD e menu de loja personalizado em um servidor FiveM é uma página NUI. Se você está construindo uma interface que o ox_lib não cobre, precisa entender como a página é declarada, como Lua e JavaScript conversam e onde fica a fronteira de segurança.

O que o FiveM NUI oferece

O recurso declara sua página no fxmanifest.lua com ui_page 'html/index.html' e lista cada asset que o navegador vai carregar no bloco files {}. A página renderiza em tela cheia por cima do jogo.

• De Lua para JavaScript. SendNUIMessage({ action = 'open', data = ... }) no cliente envia um objeto JSON. A página recebe com window.addEventListener('message', ...) e lê event.data.
• Foco e cursor. SetNuiFocus(hasFocus, hasCursor) decide se a página captura teclado e mouse. Abra com SetNuiFocus(true, true) e feche com SetNuiFocus(false, false).
• De JavaScript para Lua. RegisterNUICallback('close', function(data, cb) ... cb('ok') end) no cliente. A página chama com fetch('https://<resource-name>/close', { method: 'POST', body: JSON.stringify(data) }). Use GetParentResourceName() no JS para obter o nome do recurso sem escrever à mão.
• Segurança. O código NUI roda na máquina do jogador. Tudo o que ele envia precisa ser validado no servidor antes de tocar dinheiro, itens ou o banco de dados.

Os natives estão documentados em docs.fivem.net/natives.

Erros comuns com FiveM NUI

• Esquecer SetNuiFocus(false, false) ao fechar. A página some, mas o jogador não consegue se mover nem abrir o menu de pausa. Todo caminho de fechamento, incluindo a tecla Escape e o botão de fechar, precisa liberar o foco.
• URL errada no fetch. A pasta do recurso se chama my-shop, mas o JS chama https://myshop/buy. O console F8 mostra 404 ou “failed to fetch”. Use GetParentResourceName() e mantenha o nome do callback idêntico nos dois lados.
• Nunca chamar cb. O callback Lua roda, faz o trabalho e termina sem cb(...). A promise do fetch no JS nunca resolve e a UI trava. Chame cb sempre, mesmo com uma tabela vazia.
• Confiar nos dados da NUI como se o servidor tivesse validado. Um callback recebe { price = 0 } e o cliente repassa ao servidor, que cobra zero. Callbacks NUI chegam do cliente, então o servidor precisa consultar preços e permissões por conta própria.
• Arquivos faltando em files {}. A página carrega em branco e o console F8 mostra 404 para a folha de estilos ou o script. Cada arquivo que a página carrega precisa estar listado, incluindo imagens e fontes.

Por que assistentes de IA erram com FiveM NUI

Assistentes genéricos confundem as camadas. Colocam SendNUIMessage em um script de servidor, inventam um RegisterNUICallback no servidor ou escrevem fetch('/callback') com um caminho relativo que o navegador CEF não resolve. Também tratam o payload do callback como entrada confiável e escrevem lógica de negócio no cliente, que qualquer jogador pode editar.

A skill de FiveM NUI dá ao assistente um arquivo de regras por tema: setup.md para o manifest e a estrutura de pastas, fullscreen-nui.md para mensagens e foco, nui-callbacks.md para o contrato do callback e suas regras de segurança, best-practices.md para desempenho e tratamento de erros, e reference-links.md para a documentação oficial. O assistente lê a regra correspondente e escreve o native certo do lado certo.

Instale a skill de FiveM NUI em 30 segundos

1. Clique em “Download SKILL.md” no topo desta página.
2. Descompacte na pasta de skills ou rules 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 “um menu em tela cheia que abre com um comando e fecha com Escape”, e confira se ele usa SetNuiFocus, RegisterNUICallback com cb e lista todos os arquivos no fxmanifest.lua.