ESX Legacy para FiveM: qué es, errores comunes y la skill de IA

237 instalaciones en skills.sh

Descargar SKILL.md Comunidad

¿No quieres gestionar las skills tú mismo? Consigue la app completa.

ESX Legacy es el framework que corre en buena parte de los servidores de roleplay de FiveM: gestiona jugadores, trabajos, dinero, inventario y armas a través del recurso es_extended. Si escribes scripts para un servidor ESX, hablas con él mediante el objeto ESX, el objeto xPlayer en el servidor y PlayerData en el cliente. Esta página explica qué cubre la skill de ESX de FiveAI, los errores que más rompen scripts ESX y cómo instalar la skill en tu asistente de IA.

Qué te da la skill de ESX

La skill es un archivo SKILL.md con un archivo de reglas por cada parte del framework:

  • core-concepts: cómo se inicializa es_extended, qué contiene PlayerData en el cliente y qué contiene xPlayer en el servidor.
  • client-functions y server-functions: ESX.IsPlayerLoaded() y ESX.PlayerData en el cliente, ESX.GetPlayerFromId(source) en el servidor, callbacks y triggers.
  • xplayer-methods: los métodos para dinero, items, armas, inventario, trabajos y metadata.
  • jobs-economy: definición de trabajos, salarios, las cuentas money y bank, gestión de sociedades.
  • inventory-items y weapons-loadout: registro de items, items usables, peso, armas, componentes, munición y tintes.
  • events-callbacks: eventos de ESX, callbacks de servidor y cliente, y SecureNetEvent para eventos que dispara el cliente.
  • best-practices: comprobaciones de nil, cacheo de objetos de jugador, nombres en camelCase, pocas globales y ox_lib para menús, notificaciones y barras de progreso en lugar de la UI de ESX.

Úsala cuando crees un recurso ESX, añadas un trabajo, toques la economía o escribas cualquier cosa que lea datos del jugador.

Errores comunes con ESX

  • Usar xPlayer sin comprobar nil. Síntoma: “attempt to index a nil value” en la consola del servidor cuando un jugador se desconecta en mitad de un evento o el source no es válido. Solución: local xPlayer = ESX.GetPlayerFromId(source) seguido de if not xPlayer then return end.
  • Mezclar las APIs de ESX y QBCore. Síntoma: una llamada a QBCore.Functions.GetPlayer o a Player.Functions.AddMoney dentro de un script ESX y un error de nil en ejecución. Pasa cuando el script se copió de un tutorial de QBCore. Solución: usa ESX.GetPlayerFromId y los métodos de xPlayer, nada más.
  • Leer ESX.PlayerData antes de que el jugador cargue. Síntoma: trabajo o dinero vacíos en el cliente durante los primeros segundos tras el spawn. Solución: comprueba ESX.IsPlayerLoaded() o espera al evento de jugador cargado antes de leer PlayerData.
  • Confiar en las cantidades de dinero que envía el cliente. Síntoma: un tramposo dispara tu evento con una cantidad inventada y el servidor la paga. Solución: calcula precios y recompensas en el servidor, valida el source y usa SecureNetEvent para los eventos que dispara el cliente.
  • Llamar a ESX.GetPlayerFromId dentro de bucles. Síntoma: un hilo del servidor que se ejecuta cada frame y busca al mismo jugador en cada iteración. Solución: obtén xPlayer una vez, guárdalo en una local y reutilízalo.

Por qué los asistentes de IA se equivocan con ESX

Un asistente genérico ha visto años de tutoriales de ESX, y muchos apuntan a versiones antiguas. Suele recurrir al evento esx:getSharedObject para obtener el objeto ESX, inventa métodos que no existen en xPlayer o mete lógica exclusiva de servidor en un archivo de cliente. También mezcla vocabulario de frameworks: xPlayer en una función y Player.PlayerData en la siguiente, porque ambos aparecen en sus datos de entrenamiento.

La skill le da al asistente una referencia corta y actual. Los tutoriales antiguos usan el evento getSharedObject; ESX Legacy entrega el objeto a través del import o el export de es_extended, y el archivo de conceptos básicos de la skill apunta al asistente hacia ahí. La lista de principios (comprobar nil, esperar la carga del jugador, no confiar en el cliente, cachear objetos de jugador, preferir ox_lib para la UI) se carga cada vez que pides código ESX, así que el resultado coincide con la API que corre tu servidor.

Instala la skill de ESX en 30 segundos

  1. Haz clic en “Download SKILL.md” en la parte superior de esta página.
  2. Descomprímelo en la carpeta de skills o reglas de tu herramienta de IA. La sección de instalación de abajo muestra la ruta exacta para Claude Code, Cursor y VS Code.
  3. Pide al asistente algo concreto, como un evento de servidor que quite un item y sume dinero a la cuenta bank, y comprueba que usa ESX.GetPlayerFromId con comprobación de nil.

Cómo instalar esta skill

Descarga el zip, descomprímelo y coloca la carpeta donde tu herramienta carga skills o reglas. La ruta exacta depende de la herramienta:

Claude Code

Descomprime en .claude/skills/esx-framework/ dentro del proyecto (la carpeta debe contener SKILL.md). Para todos los proyectos, usa ~/.claude/skills/esx-framework/.

Documentación de skills de Claude Code

Cursor

Cursor carga las reglas del proyecto desde .cursor/rules/. Añade ahí un archivo de regla que apunte a la skill descomprimida, o pega el contenido de SKILL.md y los archivos de reglas en una regla. El formato es .mdc con frontmatter y cambia entre versiones, así que revisa la documentación de tu versión.

Documentación de reglas de Cursor

VS Code / Copilot

Copilot lee archivos de instrucciones desde .github/instructions/*.instructions.md. Copia SKILL.md ahí con un glob applyTo para tus archivos Lua y deja los archivos de reglas al lado.

Documentación de instrucciones de VS Code

El archivo SKILL.md

Este es el archivo que lee tu asistente de IA. Enlaza a los archivos de reglas incluidos en la descarga.

Contenido de la skill (incluye SKILL.md y cualquier otro archivo)

El contenido de la skill está en inglés: es documentación técnica pensada 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

  1. Confirm es_extended starts before the resource; acquire ESX per side.
  2. Decide the side: mutation and validation on server, display on client.
  3. Fetch xPlayer, nil-check, then validate every client-supplied argument.
  4. Pick the call from Decision Gates; read the matching rules file for signatures.
  5. 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

Preguntas frecuentes

¿Elijo ESX o QBCore para un servidor nuevo?
Los dos son válidos. ESX es el framework más antiguo y sigue muy extendido, con un catálogo enorme de scripts compatibles. QBCore tiene otra API y su propio ecosistema. Elige el que conozca tu equipo y cuyos scripts vayas a usar, y no mezcles las dos APIs en un mismo recurso.
¿Esta skill cubre solo ESX Legacy?
Sí. La skill documenta la API actual de ESX Legacy: ESX.GetPlayerFromId, los métodos de xPlayer, ESX.IsPlayerLoaded, callbacks de servidor y SecureNetEvent. Los patrones de ESX 1.1 o 1.2 no son el objetivo.
¿Puedo usar esta skill con ChatGPT?
Sí. SKILL.md es markdown plano. Pégalo como instrucción personalizada o adjúntalo a un proyecto de ChatGPT. Claude Code, Cursor y VS Code lo cargan directamente desde su carpeta de skills o reglas.

Guías relacionadas

Lecturas más largas del blog de FiveAI sobre el mismo tema.

Más skills