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

237 instalações no skills.sh

Atualizado em

Baixar SKILL.mdComunidade

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

O ESX Legacy é o framework de roleplay mais antigo do FiveM, construído em torno de xPlayer, empregos, contas e inventário. Este guia cobre a API principal, os erros que quebram scripts ESX e a skill de IA que escreve código contra a API real.

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.

Referência rápida

As chamadas do ESX Legacy mais buscadas. No servidor, sempre verifique se xPlayer não é nil.

Chamada Lado O que faz
ESX.GetPlayerFromId(source) Servidor Retorna o xPlayer de um jogador, ou nil
ESX.GetPlayerFromIdentifier(identifier) Servidor Busca um jogador pelo identificador
ESX.GetExtendedPlayers(key, value) Servidor Jogadores que atendem a um filtro, como 'job', 'police'
xPlayer.getMoney() / addMoney(amount, reason) / removeMoney(amount, reason) Servidor Dinheiro em mãos
xPlayer.getAccount(name) / addAccountMoney(account, amount, reason) Servidor Contas como bank
xPlayer.getJob() / setJob(name, grade, onDuty) Servidor Dados do emprego e mudanças de emprego
xPlayer.addInventoryItem(item, count) / removeInventoryItem(item, count) Servidor Itens
ESX.RegisterServerCallback(name, cb) Servidor Responde a um pedido do cliente; o handler recebe source, cb, ...
ESX.TriggerServerCallback(name, cb, ...) Cliente Pede dados ao servidor
ESX.IsPlayerLoaded() / ESX.PlayerData Cliente Confirme que o jogador carregou antes de ler dados

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.

Para ver como uma skill se compara a outras configurações de IA para FiveM, leia nosso comparativo.

Instale a skill de ESX em 30 segundos

  1. Clique em "Download SKILL.md" no topo desta página.
  2. 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.
  3. 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 Development

Complete guide for developing with ESX Legacy Framework — the most trusted FiveM roleplay framework since 2017.

When to use

  • Creating or editing ESX resources/scripts
  • Working with player data (xPlayer, PlayerData)
  • Implementing jobs, economy, inventory, or weapon systems
  • Using ESX client/server functions, callbacks, or events
  • Questions about ESX best practices and optimization

How to use

Read individual rule files for detailed explanations and examples:

  • rules/core-concepts.md — ESX architecture, PlayerData, xPlayer object, framework initialization

  • rules/client-functions.md — Client-side ESX functions, UI systems, player state management

  • rules/server-functions.md — Server-side functions, player retrieval, callbacks, triggers

  • rules/xplayer-methods.md — xPlayer object methods: money, items, weapons, inventory, jobs, metadata

  • rules/jobs-economy.md — Job system, salaries, accounts (money/bank), society management

  • rules/inventory-items.md — Inventory system, item management, usable items, weight calculations

  • rules/weapons-loadout.md — Weapon system, loadout, components, ammo, tints

  • rules/events-callbacks.md — ESX events, server callbacks, client callbacks, secure net events

  • rules/best-practices.md — ESX coding standards, optimization, security, naming conventions

  • rules/reference-links.md — Official ESX documentation links

Key principles

  1. Always check for nil — if xPlayer then ... end before using xPlayer
  2. Use ESX.GetPlayerFromId — Standard player retrieval: local xPlayer = ESX.GetPlayerFromId(source)
  3. Wait for player load — Check ESX.IsPlayerLoaded() on client before accessing PlayerData
  4. Never trust client — Validate all data server-side, use SecureNetEvent for client events
  5. Follow ESX patterns — Use ESX functions instead of reinventing (callbacks, notifications, etc.)
  6. Optimize loops — Cache player objects, avoid unnecessary GetPlayerFromId calls
  7. Use camelCase — Follow Lua naming: myVariable, MyGlobalFunction, MY_CONSTANT
  8. Minimal globals — Keep variables local unless they need global scope
  9. Use ox_lib for UI — Prefer ox_lib for menus, dialogs, notifications, progress bars instead of ESX UI

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.

Guias relacionados

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

Mais skills