ESX Legacy 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.

O ESX Legacy é o framework que roda em boa parte dos servidores de roleplay do FiveM: ele gerencia jogadores, empregos, dinheiro, inventário e armas através do recurso es_extended. Se você escreve scripts para um servidor ESX, conversa com ele pelo objeto ESX, pelo objeto xPlayer no servidor e pelo PlayerData no cliente. Esta página explica o que a skill de ESX da FiveAI cobre, os erros que mais quebram scripts ESX e como instalar a skill no seu assistente de IA.

O que a skill de ESX te dá

A skill é um arquivo SKILL.md com um arquivo de regras para cada parte do framework:

core-concepts: como o es_extended inicializa, o que o PlayerData guarda no cliente e o que o xPlayer guarda no servidor.
client-functions e server-functions: ESX.IsPlayerLoaded() e ESX.PlayerData no cliente, ESX.GetPlayerFromId(source) no servidor, callbacks e triggers.
xplayer-methods: os métodos para dinheiro, itens, armas, inventário, empregos e metadata.
jobs-economy: definição de empregos, salários, as contas money e bank, gestão de sociedades.
inventory-items e weapons-loadout: registro de itens, itens usáveis, peso, armas, componentes, munição e tints.
events-callbacks: eventos do ESX, callbacks de servidor e cliente, e SecureNetEvent para eventos disparados pelo cliente.
best-practices: checagem de nil, cache de objetos de jogador, nomes em camelCase, poucas globais e ox_lib para menus, notificações e barras de progresso no lugar da UI do ESX.

Use a skill quando criar um recurso ESX, adicionar um emprego, mexer na economia ou escrever qualquer coisa que leia dados do jogador.

Erros comuns com ESX

Usar xPlayer sem checar nil. Sintoma: “attempt to index a nil value” no console do servidor quando um jogador desconecta no meio de um evento ou o source é inválido. Correção: local xPlayer = ESX.GetPlayerFromId(source) seguido de if not xPlayer then return end.
Misturar as APIs do ESX e do QBCore. Sintoma: uma chamada a QBCore.Functions.GetPlayer ou a Player.Functions.AddMoney dentro de um script ESX e um erro de nil em execução. Acontece quando o script foi copiado de um tutorial de QBCore. Correção: use ESX.GetPlayerFromId e os métodos do xPlayer, nada mais.
Ler ESX.PlayerData antes de o jogador carregar. Sintoma: emprego ou dinheiro vazios no cliente nos primeiros segundos depois do spawn. Correção: cheque ESX.IsPlayerLoaded() ou espere o evento de jogador carregado antes de ler o PlayerData.
Confiar nos valores de dinheiro enviados pelo cliente. Sintoma: um trapaceiro dispara seu evento com um valor inventado e o servidor paga. Correção: calcule preços e recompensas no servidor, valide o source e use SecureNetEvent para eventos disparados pelo cliente.
Chamar ESX.GetPlayerFromId dentro de loops. Sintoma: uma thread do servidor que roda a cada frame e busca o mesmo jogador em cada iteração. Correção: pegue o xPlayer uma vez, guarde em uma local e reutilize.

Por que os assistentes de IA erram com ESX

Um assistente genérico viu anos de tutoriais de ESX, e muitos apontam para versões antigas. Ele costuma recorrer ao evento esx:getSharedObject para obter o objeto ESX, inventa métodos que não existem no xPlayer ou coloca lógica exclusiva de servidor em um arquivo de cliente. Também mistura vocabulário de frameworks: xPlayer em uma função e Player.PlayerData na seguinte, porque os dois aparecem nos dados de treinamento.

A skill dá ao assistente uma referência curta e atual. Tutoriais antigos usam o evento getSharedObject; o ESX Legacy entrega o objeto pelo import ou pelo export do es_extended, e o arquivo de conceitos básicos da skill aponta o assistente para isso. A lista de princípios (checar nil, esperar o jogador carregar, nunca confiar no cliente, cachear objetos de jogador, preferir ox_lib para UI) é carregada toda vez que você pede código ESX, então a saída bate com a API que roda no seu servidor.

Instale a skill de ESX em 30 segundos

Clique em “Download SKILL.md” no topo desta página.
Descompacte na pasta de skills ou regras 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 um evento de servidor que remova um item e some dinheiro na conta bank, e confira se ele usa ESX.GetPlayerFromId com checagem de nil.

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/esx-framework/ dentro do projeto (a pasta precisa conter SKILL.md). Para todos os projetos, use ~/.claude/skills/esx-framework/.

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.

ESX Framework

Server/client API for ESX Legacy: xPlayer, PlayerData, callbacks, events, jobs and money.

Activation Contract

Load this skill when the user creates or edits an ESX resource, touches xPlayer or ESX.PlayerData, needs jobs, money, accounts, items or weapons through ESX, or asks about ESX callbacks, events or best practices.

Hard Rules

Get the object with ESX = exports['es_extended']:getSharedObject(). On the client, wait for ESX and ESX.IsPlayerLoaded() before reading ESX.PlayerData.
xPlayer exists on the SERVER only (ESX.GetPlayerFromId(source)). ESX.PlayerData exists on the CLIENT only.
Always nil-check: if not xPlayer then return end before calling any method.
Money, items, weapons, jobs and metadata are mutated on the server through xPlayer.* methods, never from the client.
Pass a reason to addMoney, removeMoney, addAccountMoney, removeAccountMoney.
Client callbacks (ESX.TriggerClientCallback, ESX.AwaitClientCallback) must never decide anything sensitive: the client can fake the answer.
Use ESX.SecureNetEvent for client events that only the server may trigger.
Prefer ox_lib for notifications, menus, dialogs and progress bars over ESX UI.
Cache PlayerPedId() and update on esx:playerPedChanged; never Wait(0) loops without need.

Decision Gates

Need	Use
Client asks server for data	`ESX.RegisterServerCallback` + `ESX.TriggerServerCallback`
Server pushes an event to one player	`xPlayer.triggerEvent(name, ...)`
Server-only client event	`ESX.SecureNetEvent(name, cb)` on the client
Find player by source / identifier	`ESX.GetPlayerFromId` / `ESX.GetPlayerFromIdentifier`
Filter players by job etc.	`ESX.GetExtendedPlayers(key, value)`
Usable item	`ESX.RegisterUsableItem(item, cb)`
Admin command with group	`ESX.RegisterCommand(name, group, cb, allowConsole, suggestion)`

Execution Steps

Confirm es_extended starts before the resource; acquire ESX per side.
Decide the side: mutation and validation on server, display on client.
Fetch xPlayer, nil-check, then validate every client-supplied argument.
Pick the call from Decision Gates; read the matching rules file for signatures.
Return data via callbacks, not paired events.

Output Contract

Return runnable Lua with the client/server split explicit, xPlayer nil-checked, and reasons on money operations. Use ox_lib for UI unless the user asks otherwise.

References

rules/core-concepts.md — architecture, PlayerData, xPlayer, startup flow.
rules/client-functions.md — client-side ESX functions and player state.
rules/server-functions.md — player retrieval, callbacks, commands, jobs, items.
rules/xplayer-methods.md — xPlayer money, accounts, inventory, weapons, meta.
rules/events-callbacks.md — server/client callbacks, events, SecureNetEvent.
rules/best-practices.md — naming, caching, loops, security, Lua 5.4.
rules/reference-links.md — official ESX documentation links.

Upstream docs: https://docs.esx-framework.org

Perguntas frequentes

Escolho ESX ou QBCore para um servidor novo?

Os dois são válidos. O ESX é o framework mais antigo e continua muito usado, com um catálogo enorme de scripts compatíveis. O QBCore tem outra API e seu próprio ecossistema. Escolha o que sua equipe conhece e cujos scripts você vai rodar, e não misture as duas APIs no mesmo recurso.

Esta skill cobre só o ESX Legacy?

Sim. A skill documenta a API atual do ESX Legacy: ESX.GetPlayerFromId, os métodos do xPlayer, ESX.IsPlayerLoaded, callbacks de servidor e SecureNetEvent. Os padrões do ESX 1.1 ou 1.2 não são o alvo.

Posso usar esta skill com o ChatGPT?

Sim. O SKILL.md é markdown puro. Cole como instrução personalizada ou anexe a um projeto do ChatGPT. Claude Code, Cursor e VS Code carregam o arquivo direto da pasta de skills ou regras.

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