Si vous montez un serveur roleplay sur FiveM, ESX Legacy est probablement la première brique que vous allez poser : c'est le framework économie/jobs/inventaire le plus utilisé de l'écosystème RP, gratuit, open source et maintenu activement par la communauté. Ce guide couvre l'installation complète, de la base de données au premier démarrage, avec les erreurs les plus courantes et comment les résoudre.
Comptez 30 à 45 minutes pour une première installation propre.
Qu'est-ce qu'ESX Legacy ?
ESX Legacy est la version maintenue et modernisée du framework ESX historique (celui qu'on appelait es_extended v1). Il fournit la base commune à la plupart des serveurs RP FiveM : comptes joueurs, argent (cash/banque), inventaire, métiers, société et système de permissions. La grande majorité des scripts RP payants ou gratuits qu'on trouve sur le marché sont conçus pour tourner dessus.
L'alternative la plus connue est QBCore : les deux se valent techniquement, le choix dépend surtout de la compatibilité avec les scripts que vous comptez utiliser (voir la FAQ en bas de page).
Prérequis
- Un serveur FiveM qui démarre déjà (base
cfx-server-dataou installation via txAdmin). Si ce n'est pas encore le cas, commencez par la mise en place du serveur FiveM, c'est l'étape zéro avant celle-ci. - Un accès à une base de données MySQL ou MariaDB. Sur un serveur FiveM ElypseCloud, elle est fournie avec l'offre ou disponible en option : vérifiez dans votre espace client.
- Un accès au gestionnaire de fichiers de votre panel (Pterodactyl côté ElypseCloud) ou un accès SFTP.
- Des notions de base sur l'édition du fichier
server.cfg.
Vous voulez tester ESX Legacy sans engager de budget ? L'offre FiveM gratuite suffit pour dérouler ce tutoriel de bout en bout et voir le framework tourner avant de passer sur une offre dimensionnée pour de vrais joueurs.
Étape 1 : Préparer la base de données
Créez une base de données dédiée : ne réutilisez pas une base déjà occupée par un autre projet. Notez précisément :
- le nom de la base
- l'utilisateur et son mot de passe
- l'hôte (souvent
localhost, ou une adresse interne si la base est mutualisée)
Ces trois informations vous serviront à l'étape 4.
Étape 2 : Installer oxmysql
ESX Legacy a besoin d'un connecteur MySQL asynchrone pour parler à votre base. Le standard actuel de l'écosystème FiveM est oxmysql. L'ancien mysql-async / ghmattimysql fonctionne encore sur certains setups, mais oxmysql est ce que la documentation ESX Legacy recommande aujourd'hui. Vérifiez la doc officielle du framework au moment où vous lisez ces lignes, l'écosystème FiveM bouge vite.
- Téléchargez la dernière release d'oxmysql depuis son dépôt officiel.
- Placez le dossier dans
resources/[core]/oxmysql(le préfixe[core]n'est qu'une convention de rangement, pas une obligation technique). - Ajoutez dans
server.cfg, avant toute ligne qui charge ESX :
ensure oxmysqlÉtape 3 : Télécharger es_extended et les ressources ESX
Récupérez es_extended (le cœur du framework) depuis le dépôt officiel ESX Legacy, ainsi que les ressources additionnelles dont vous aurez besoin : spawnmanager, esx_menu_default, esx_context, etc. La liste exacte dépend de la version et des scripts que vous comptez installer par-dessus.
Placez chaque ressource dans son propre dossier sous resources/[esx]/.
Étape 4 : Configurer server.cfg
Dans l'ordre, votre server.cfg doit charger :
ensure oxmysql
ensure es_extended
ensure spawnmanager
ensure esx_menu_default
ensure esx_menu_dialog
ensure esx_menu_listAjoutez ensuite la chaîne de connexion à votre base, avec vos vraies informations de l'étape 1 :
set mysql_connection_string "mysql://utilisateur:motdepasse@localhost/nom_de_la_base?charset=utf8mb4"L'ordre de chargement compte. oxmysql doit toujours démarrer avant es_extended : sinon ESX ne trouve aucune connexion à la base au démarrage et plante.
Étape 5 : Importer le schéma SQL
Le dépôt ESX Legacy fournit un fichier .sql contenant la structure de base (tables joueurs, société, etc.). Importez-le dans votre base via phpMyAdmin, Adminer ou la ligne de commande, selon ce que propose votre panel.
Étape 6 : Démarrer et tester
Redémarrez le serveur depuis votre panel, puis surveillez la console au démarrage. Connectez-vous en jeu : vous devriez atterrir en spawn avec un personnage vierge. Si un menu ESX s'ouvre (F2 par défaut sur la plupart des configurations), l'installation est fonctionnelle.
Erreurs courantes
« oxmysql wasn't ready before a resource was started »
Le connecteur MySQL n'a pas eu le temps de s'initialiser avant qu'es_extended tente de s'y connecter. Vérifiez l'ordre dans server.cfg (oxmysql en premier) et que la chaîne de connexion est correcte.
Erreur de connexion à la base (« Access denied », « Unknown database »)
Vérifiez l'utilisateur, le mot de passe et le nom de base dans mysql_connection_string, et que l'utilisateur MySQL a bien les droits sur cette base précise.
« Could not find resource » au démarrage
Une ressource listée dans server.cfg n'est pas au bon endroit dans resources/, ou le nom du dossier ne correspond pas exactement à ce qui est écrit dans server.cfg, ce qui est sensible à la casse sur certains systèmes.
Le personnage ne spawn pas / écran noir persistant
Vérifiez que spawnmanager est bien chargé après es_extended, et regardez la console pour trouver une erreur Lua/JS plus précise avant de chercher plus loin.
Et ensuite ?
Une fois ESX Legacy en place, la suite dépend de votre projet : ajout de scripts métiers, inventaire avancé, système d'entreprises. Deux points d'attention côté infrastructure, indépendants du framework : la RAM disponible quand le nombre de scripts grimpe, et la qualité de la liaison à la base de données sous charge. C'est là que la plupart des serveurs RP se mettent à lag, pas dans ESX lui-même. Si vous êtes déjà dans ce cas sur votre hébergement actuel, on a écrit une page pour ça.