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

Não quer gerenciar as skills por conta própria? Obtenha o app completo.

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

Clique em “Download SKILL.md” no topo desta página.
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.
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.

Como instalar esta skill

Baixe o zip, descompacte e coloque a pasta onde a sua ferramenta carrega skills ou regras. O caminho exato depende da ferramenta:

Claude Code

Descompacte em .claude/skills/oxlib/ dentro do projeto (a pasta precisa conter SKILL.md). Para todos os projetos, use ~/.claude/skills/oxlib/.

Documentação de skills do Claude Code

Cursor

O Cursor carrega as regras do projeto de .cursor/rules/. Adicione ali um arquivo de regra apontando para a skill descompactada, ou cole o conteúdo do SKILL.md e dos arquivos de regras em uma regra. O formato é .mdc com frontmatter e muda entre versões, então confira a documentação da sua versão.

Documentação de regras do Cursor

VS Code / Copilot

O Copilot lê arquivos de instruções em .github/instructions/*.instructions.md. Copie o SKILL.md para lá com um glob applyTo para os seus arquivos Lua e mantenha os arquivos de regras ao lado.

Documentação de instruções do VS Code

O arquivo SKILL.md

Este é o arquivo que o seu assistente de IA lê. Ele aponta para os arquivos de regras incluídos no download.

Conteúdo da skill (inclui SKILL.md e quaisquer outros arquivos)

O conteúdo da skill está em inglês: é documentação técnica feita 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

Perguntas frequentes

O ox_lib funciona com ESX e QBCore?

Sim. O ox_lib é standalone e não depende de nenhum framework. Servidores ESX e QBCore usam a biblioteca, e as skills da FiveAI para esses frameworks a recomendam para notificações, diálogos e menus.

O ox_lib é gratuito?

Sim. O ox_lib é open source e está publicado no GitHub sob a licença LGPL. Você pode usar em qualquer servidor sem pagar, desde que respeite os termos da licença.

Posso usar esta skill com o ChatGPT?

Sim, com um passo manual. O SKILL.md é markdown puro, então você pode colar na conversa como contexto. O suporte nativo a skills é para Claude Code, Cursor e VS Code.

Leituras mais longas do blog da FiveAI sobre o mesmo tema.