Si estás montando un servidor de rol en FiveM, ESX Legacy será probablemente el primer ladrillo que coloques: es el framework de economía, empleos e inventario más usado del ecosistema RP, gratuito, de código abierto y mantenido activamente por la comunidad. Esta guía cubre la instalación completa, desde la base de datos hasta el primer arranque, junto con los errores más habituales y cómo resolverlos.
Calcula entre 30 y 45 minutos para una primera instalación limpia.
¿Qué es ESX Legacy?
ESX Legacy es la versión mantenida y modernizada del framework ESX histórico (el que se conocía antes como es_extended v1). Aporta la base común sobre la que se apoyan la mayoría de servidores RP de FiveM: cuentas de jugador, dinero (efectivo y banco), inventario, empleos, sociedades y un sistema de permisos. La gran mayoría de scripts RP del mercado, gratuitos o de pago, están hechos para funcionar encima de él.
La alternativa más conocida es QBCore: técnicamente ambos son sólidos, y la elección depende sobre todo de la compatibilidad con los scripts que pienses usar (ver la FAQ al final de esta página).
Requisitos previos
- Un servidor FiveM que ya arranque (una base
cfx-server-datao una instalación con txAdmin). Si aún no es tu caso, empieza por montar el servidor FiveM, que es el paso cero antes de este. - Acceso a una base de datos MySQL o MariaDB. En un servidor FiveM de ElypseCloud viene incluida con la oferta o está disponible como opción: consúltalo en tu área de cliente.
- Acceso al gestor de archivos de tu panel (Pterodactyl en ElypseCloud) o acceso por SFTP.
- Soltura básica editando el archivo
server.cfg.
¿Quieres probar ESX Legacy sin gastar nada? La oferta FiveM gratuita basta para seguir este tutorial de principio a fin y ver el framework funcionando antes de pasar a una oferta dimensionada para jugadores reales.
Paso 1: preparar la base de datos
Crea una base de datos dedicada: no reutilices una que ya sirva a otro proyecto. Apunta con exactitud:
- el nombre de la base de datos
- el usuario y su contraseña
- el host (a menudo
localhost, o una dirección interna si la base es compartida)
Necesitarás esos tres datos en el paso 4.
Paso 2: instalar oxmysql
ESX Legacy necesita un conector MySQL asíncrono para hablar con tu base de datos. El estándar actual en el ecosistema FiveM es oxmysql. Los antiguos mysql-async / ghmattimysql siguen funcionando en algunas instalaciones, pero oxmysql es lo que recomienda hoy la documentación de ESX Legacy. Consulta la documentación oficial del framework mientras lees esto: el ecosistema de FiveM se mueve rápido.
- Descarga la última release de oxmysql desde su repositorio oficial.
- Coloca la carpeta en
resources/[core]/oxmysql(el prefijo[core]es una convención de organización, no un requisito técnico). - Añade esto a
server.cfg, antes de cualquier línea que cargue ESX:
ensure oxmysqlPaso 3: descargar es_extended y los recursos de ESX
Descarga es_extended (el núcleo del framework) desde el repositorio oficial de ESX Legacy, junto con los recursos adicionales que vayas a necesitar: spawnmanager, esx_menu_default, esx_context, etc. La lista exacta depende de la versión y de los scripts que pienses instalar encima.
Coloca cada recurso en su propia carpeta dentro de resources/[esx]/.
Paso 4: configurar server.cfg
En este orden, tu server.cfg debe cargar:
ensure oxmysql
ensure es_extended
ensure spawnmanager
ensure esx_menu_default
ensure esx_menu_dialog
ensure esx_menu_listDespués añade la cadena de conexión a tu base de datos, con tus datos reales del paso 1:
set mysql_connection_string "mysql://usuario:contraseña@localhost/nombre_base?charset=utf8mb4"El orden de carga importa. oxmysql debe arrancar siempre antes que es_extended: si no, ESX no encuentra conexión con la base de datos al arrancar y se cae.
Paso 5: importar el esquema SQL
El repositorio de ESX Legacy incluye un archivo .sql con la estructura base (tablas de jugadores, sociedades, etc.). Impórtalo en tu base de datos con phpMyAdmin, Adminer o la línea de comandos, según lo que ofrezca tu panel.
Paso 6: arrancar y probar
Reinicia el servidor desde tu panel y observa la consola durante el arranque. Conéctate en el juego: deberías aparecer en el spawn con un personaje en blanco. Si se abre un menú de ESX (F2 por defecto en la mayoría de configuraciones), la instalación funciona.
Errores frecuentes
«oxmysql wasn't ready before a resource was started»
El conector MySQL no tuvo tiempo de inicializarse antes de que es_extended intentara conectarse. Revisa el orden en server.cfg (oxmysql primero) y que la cadena de conexión sea correcta.
Error de conexión a la base de datos («Access denied», «Unknown database»)
Comprueba el usuario, la contraseña y el nombre de la base en mysql_connection_string, y que el usuario de MySQL tenga realmente permisos sobre esa base concreta.
«Could not find resource» al arrancar
Un recurso listado en server.cfg no está en el sitio correcto dentro de resources/, o el nombre de la carpeta no coincide exactamente con lo escrito en server.cfg, que distingue mayúsculas y minúsculas en algunos sistemas.
El personaje no aparece / pantalla negra permanente
Comprueba que spawnmanager se carga después de es_extended, y mira en la consola si hay un error de Lua o JS más concreto antes de seguir investigando.
¿Y ahora qué?
Una vez ESX Legacy está en marcha, lo que viene después depende de tu proyecto: scripts de empleos, inventario avanzado, sistemas de empresas. Hay dos puntos de infraestructura que merecen atención, al margen del framework: la RAM disponible a medida que crece el número de scripts, y la calidad del enlace con la base de datos bajo carga. Ahí es donde la mayoría de servidores RP empiezan a ir a tirones, no dentro de ESX. Si ya estás en esa situación con tu hosting actual, hemos escrito una página sobre ello.