ox_lib para FiveM: o que é, erros comuns e a skill de IA

ox_lib é uma biblioteca standalone para FiveM que dá aos seus recursos UI pronta, callbacks cliente-servidor, comandos, zonas e utilitários compartilhados. Recursos como ox_inventory e ox_target dependem dela, e a maioria dos servidores ESX e QBCore modernos já a tem instalada. Se você escreve scripts para um servidor com ox_lib, use a biblioteca em vez de montar sua própria NUI ou copiar código de menu antigo.

O que o ox_lib oferece

O setup é uma linha no fxmanifest.lua: shared_scripts { '@ox_lib/init.lua' }. Você pode adicionar ox_libs { 'locale', 'callback' } para pré-carregar os módulos que usa com frequência.

• Interface. lib.notify para notificações, lib.alertDialog para confirmações, lib.inputDialog para formulários, além de menus de contexto, barras de progresso e TextUI. Os ícones vêm do Font Awesome 6.
• Callbacks. lib.callback.register no servidor, lib.callback.await no cliente. O cliente pergunta, o servidor responde e você recebe o valor na mesma linha.
• Comandos. lib.addCommand no servidor com help, params e restricted, para que o comando valide os argumentos e verifique permissões por você.
• Zonas. lib.zones.poly, lib.zones.box e lib.zones.sphere com handlers onEnter, onExit e inside. Use no cliente. O suporte no servidor é limitado.
• Utilitários. Keybinds, locales, lib.table, lib.string e outros módulos compartilhados.

A referência completa está em coxdocs.dev/ox_lib.

Erros comuns com ox_lib

• Esquecer @ox_lib/init.lua no manifest. O script carrega e morre com "attempt to index a nil value (global 'lib')". Adicione shared_scripts { '@ox_lib/init.lua' } e garanta que o ox_lib inicia antes do seu recurso.
• Registrar o callback do lado errado. Um cliente que chama lib.callback.await('myjob:getData') não recebe nada porque o callback também foi registrado no cliente. Registre com lib.callback.register no servidor e use await no cliente. Se o servidor precisa perguntar a um cliente, passe o source do jogador como segundo argumento.
• Usar callback para avisar e esquecer. Se o cliente só precisa dizer ao servidor "apertei o botão", um net event basta. Callbacks bloqueiam até a resposta chegar, então use apenas quando precisar de um valor de volta.
• Tratar zonas como recurso de servidor. Zonas rodam no cliente, onde está a posição do jogador. O suporte a zonas no servidor é limitado, então detecte entradas e saídas no cliente e mande o resultado ao servidor se precisar.
• Misturar padrões antigos. Chamadas exports.ox_lib, menus ESX velhos e uma NUI própria para um simples diálogo de confirmação são sinais de código escrito antes do ox_lib existir. Substitua por lib.alertDialog, lib.inputDialog e menus de contexto.

Por que assistentes de IA erram com ox_lib

Um assistente genérico viu anos de código FiveM, quase todo escrito antes do ox_lib ou com uma versão antiga. Peça um diálogo de confirmação e ele pode inventar um export como exports.ox_lib:showDialog, escrever um menu ESX ou entregar um callback registrado no cliente. O código parece certo e falha na primeira execução.

A skill do ox_lib corrige isso com arquivos de regras, um por módulo: init.md, callback.md, interface.md, addCommand.md e zones.md. Cada um indica os nomes reais das funções, a que lado da rede pertencem e quais argumentos recebem. O assistente lê a regra que corresponde ao seu pedido e escreve contra a API documentada em vez de adivinhar.

Instale a skill do ox_lib 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 "adicione um callback de servidor que retorne o emprego do jogador e mostre com lib.notify", e confira se ele usa lib.callback.register no servidor e lib.callback.await no cliente.