Installer ESX Legacy sur un serveur FiveM

Ce tuto couvre l'installation complète d'ESX Legacy sur un serveur FiveM, de la base de données MySQL au premier démarrage en jeu. ESX Legacy est le framework RP le plus utilisé de l'écosystème FiveM : économie, métiers, inventaire, sociétés, permissions. Le guide s'adresse aux administrateurs qui veulent administrer leur propre serveur roleplay, qu'il tourne sur un hébergement FiveM managé, un VPS Linux ou un serveur dédié.

Comptez 30 à 45 minutes pour une première installation propre, backup de vos fichiers compris.

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 disponibles 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 notre comparatif détaillé ESX Legacy vs QBCore et la FAQ en bas de page).

ESX est l'abréviation d'« EssentialMode Extended » : le framework est né comme une extension d'EssentialMode (ES), un ancien framework de rôle-play pour GTA, avant de devenir au fil des années le projet indépendant et très largement réécrit qu'on installe aujourd'hui.

Prérequis

• Un serveur FiveM qui démarre déjà (base cfx-server-data ou 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 (souvent appelée base MySQL dans les panels). 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), un accès SFTP, ou un accès FTP selon ce que votre hébergeur propose.
• Des notions de base sur l'édition du fichier de config server.cfg et sur la navigation dans un terminal si vous administrez un VPS.

Accéder aux fichiers du serveur

Avant de toucher à quoi que ce soit, il faut pouvoir déposer des fichiers sur le serveur. Trois méthodes principales selon votre type d'hébergement :

• Panel Pterodactyl (hébergement FiveM managé) : le gestionnaire de fichiers intégré au panel web permet d'uploader et d'éditer des fichiers directement depuis le navigateur. C'est la méthode la plus simple quand elle est disponible. Le login se fait avec votre nom d'utilisateur et mot de passe du panel.
• SFTP / FTP : si votre hébergeur le fournit, connectez-vous en SFTP (FTP chiffré via SSH, à préférer au FTP classique non chiffré) avec un client comme FileZilla. L'adresse IP du serveur, le port, le nom d'utilisateur et le mot de passe sont généralement indiqués dans le panel. FTP transmet les identifiants en clair : ne l'utilisez que si SFTP n'est pas disponible.
• SSH (VPS ou serveur dédié) : si vous administrez un VPS Linux ou un serveur dédié sous Ubuntu, Debian ou un autre système Unix, vous avez un accès SSH direct. Connectez-vous en tant que root ou avec un compte sudo, puis naviguez jusqu'au répertoire du serveur FiveM. C'est la méthode qui offre le plus de contrôle, mais elle suppose de savoir se repérer dans un terminal.

Étape 1 : Préparer la base de données

Créez une base de données dédiée à ESX Legacy : ne réutilisez pas une base MySQL déjà occupée par un autre projet, même sur un hébergement mutualisé où plusieurs bases de données cohabitent sur le même serveur. Notez précisément :

• le nom de la base de donnée (par exemple esx_serveur)
• le nom d'utilisateur MySQL et son mot de passe (vos identifiants de login à la base)
• l'hôte : souvent localhost si la base MySQL tourne sur la même machine, ou une adresse IP interne si elle est hébergée séparément

Ces trois informations vous serviront à l'étape 4 pour la chaîne de connexion.

Sur Pterodactyl, la base de données se crée depuis l'onglet « Databases » du panel. Sur un VPS Linux, vous pouvez la créer en ligne de commande avec sudo mysql ou via phpMyAdmin (une interface web en PHP pour administrer vos bases de données MySQL depuis un navigateur). Si phpMyAdmin n'est pas installé, Adminer est une alternative légère en un seul fichier PHP.

Étape 2 : Installer oxmysql

ESX Legacy a besoin d'un connecteur MySQL asynchrone pour envoyer ses requêtes SQL à votre base de données. Le standard actuel de l'écosystème FiveM est oxmysql, développé par l'équipe Overextended. L'ancien mysql-async / ghmattimysql fonctionne encore sur certains setups, mais oxmysql est ce que la documentation ESX Legacy recommande aujourd'hui.

1. Téléchargez la dernière release d'oxmysql depuis son dépôt officiel GitHub.
2. Placez le dossier dans resources/[core]/oxmysql (le préfixe [core] n'est qu'une convention de rangement, pas une obligation technique).
3. Ajoutez dans server.cfg, avant toute ligne qui charge ESX :

ensure oxmysql

Oxmysql gère le pool de connexions et transmet chaque query SQL vers la base MySQL. Les requêtes sont asynchrones : le serveur FiveM n'est pas bloqué en attendant la réponse de la base de données, ce qui évite les freezes en jeu quand un script fait une requête lourde.

É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 sur GitHub, 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]/. Si vous transférez les fichiers par FTP ou SFTP, vérifiez que l'arborescence est intacte après l'upload : un dossier imbriqué en trop (par exemple es_extended/es_extended/) est une erreur courante qui empêche le chargement sans message d'erreur clair dans les logs.

Étape 4 : Configurer server.cfg

Le fichier de config server.cfg est le point central de la configuration de votre serveur FiveM. L'ordre de chargement des resources y est critique. Dans l'ordre :

ensure oxmysql
ensure es_extended
ensure spawnmanager
ensure esx_menu_default
ensure esx_menu_dialog
ensure esx_menu_list

Ajoutez ensuite la chaîne de connexion à votre base MySQL, avec vos vraies informations de l'étape 1 :

set mysql_connection_string "mysql://utilisateur:motdepasse@localhost/nom_de_la_base?charset=utf8mb4"

Remplacez utilisateur par votre nom d'utilisateur MySQL, motdepasse par le mot de passe correspondant, et nom_de_la_base par le nom exact de votre base de données. Si la base n'est pas sur localhost, remplacez-le par l'adresse IP ou le nom de domaine du serveur de base de données.

Étape 5 : Importer le schéma SQL

Le dépôt ESX Legacy fournit un fichier .sql contenant la structure de base (tables joueurs, métiers, société, items). Importez-le dans votre base MySQL par l'une de ces méthodes :

• phpMyAdmin : connectez-vous au login de phpMyAdmin, sélectionnez la base, onglet « Importer », choisissez le fichier .sql et validez.
• Adminer : même principe, interface plus légère, un seul fichier PHP à déposer sur le serveur web.
• Ligne de commande (sur un VPS Linux avec accès SSH) :

sudo mysql nom_de_la_base < legacy.sql

Cette commande exécute chaque query SQL du fichier contre votre base de donnée. Vérifiez les logs de sortie : s'il y a une erreur de syntaxe SQL dans le fichier, l'import s'arrête à la ligne concernée et les tables suivantes ne sont pas créées.

Étape 6 : Démarrer et tester

Faites un restart du serveur depuis votre panel ou en ligne de commande, puis surveillez les logs de la console au démarrage. Cherchez les lignes qui confirment qu'oxmysql s'est connecté à la base MySQL et qu'es_extended a chargé sans erreur.

Connectez-vous en jeu avec l'adresse IP de votre serveur (ou son nom de domaine si vous en avez configuré un via vos enregistrements DNS). 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.

Si le serveur ne démarre pas après le restart, ou si l'écran reste noir, consultez la section erreurs courantes plus bas dans ce tuto.

Quel système pour héberger un serveur FiveM ?

FXServer (le binaire serveur de FiveM) tourne sous Linux et sous Windows. Le choix de l'OS dépend de votre hébergement :

Sur un hébergement FiveM managé (comme les offres ElypseCloud), vous n'avez pas à choisir l'OS : le panel Pterodactyl gère tout, FXServer tourne dans un conteneur, et les commandes sudo ou l'accès root ne sont pas nécessaires. L'OS n'a d'importance que si vous administrez vous-même un VPS ou un serveur dédié bare metal.

Pourquoi oxmysql plutôt que mysql-async ou ghmattimysql

Donner les droits d'administration avec les permissions ACE

ESX Legacy s'appuie sur le système de permissions ACE natif de FXServer pour distinguer un joueur normal d'un administrateur du framework. Dans le fichier de config server.cfg, après avoir chargé es_extended, un principal doit recevoir les droits nécessaires, par exemple :

add_principal identifier.steam:110000112345678 group.admin
add_ace group.admin command allow

Ne donnez jamais le groupe admin à un compte partagé : chaque membre du staff (les administrateurs de votre serveur) doit avoir son propre identifiant (Steam, Discord ou licence FiveM selon ce que vous utilisez pour identifier vos joueurs), exactement comme pour les comptes txAdmin évoqués dans notre guide de sécurisation d'un serveur FiveM. Cela permet de révoquer un accès individuel sans toucher aux autres, et de tracer dans les logs qui a fait quoi sur le serveur.

Gérer la base de données après l'installation

Une fois ESX Legacy installé, vous aurez régulièrement besoin de consulter ou modifier la base MySQL : vérifier le solde d'un joueur, corriger un grade, purger un inventaire buggé. Deux interfaces web facilitent ces opérations sans passer par la ligne de commande :

• phpMyAdmin : l'interface la plus répandue pour administrer une base MySQL depuis un navigateur. Écrite en PHP, elle tourne sur n'importe quel serveur web (Apache, Nginx) avec PHP installé. Le login se fait avec vos identifiants MySQL.
• Adminer : une alternative plus légère, en un seul fichier PHP. Idéale sur un VPS où vous ne voulez pas installer un serveur web complet (Apache ou Nginx) juste pour la gestion de base de données.

Sur un VPS Linux avec accès SSH et root, vous pouvez aussi interroger la base directement en ligne de commande :

sudo mysql -u nom_utilisateur -p nom_de_la_base
SELECT identifier, firstname, lastname, job, job_grade FROM users LIMIT 10;

Cette query SQL affiche les dix premiers joueurs enregistrés dans la base de donnée avec leur métier et leur grade. C'est le moyen le plus rapide de vérifier que les données ESX sont bien en place après un restart du serveur.

Connecter un nom de domaine au serveur

Par défaut, les joueurs se connectent à votre serveur via son adresse IP et le port FiveM (par exemple 203.0.113.10:30120). Vous pouvez leur simplifier la vie en associant un nom de domaine à votre serveur via un enregistrement DNS de type SRV.

L'enregistrement DNS SRV permet de spécifier le port directement dans le DNS, ce qui évite aux joueurs de le taper manuellement. La configuration se fait chez votre registrar de nom de domaine (ou dans le panel DNS de votre hébergeur). Le serveur FiveM lui-même n'a rien à configurer de ce côté : le DNS pointe vers l'adresse IP, et FXServer écoute sur le port défini dans server.cfg.

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 de chargement dans la config server.cfg (oxmysql en premier) et que la chaîne de connexion à la base MySQL est correcte. Un restart du serveur après correction suffit généralement.

Erreur de connexion à la base (« Access denied », « Unknown database »)

Vérifiez le nom d'utilisateur, le mot de passe et le nom de base de données dans mysql_connection_string. Assurez-vous que l'utilisateur MySQL a bien les droits (GRANT) sur cette base précise et que le login fonctionne indépendamment, par exemple en testant la connexion depuis phpMyAdmin ou en ligne de commande avec sudo mysql -u utilisateur -p.

« Could not find resource » au démarrage

Une ressource listée dans la config 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. Attention : le nom est sensible à la casse sur les systèmes Unix (Linux), pas sous Windows. Vérifiez aussi vos logs pour identifier le package exact qui pose problème.

Le personnage ne spawn pas / écran noir persistant

Vérifiez que spawnmanager est bien chargé après es_extended dans la config, et regardez les logs de la console pour trouver une erreur Lua/JS plus précise avant de chercher plus loin.

Dépendance manquante déclarée dans un fxmanifest.lua

Une resource qui dépend d'une bibliothèque partagée (déclarée dans son fxmanifest.lua) refuse de démarrer si cette dépendance n'est pas elle-même présente et démarrée avant elle dans server.cfg. Le symptôme ressemble à une resource « qui ne fait rien » plutôt qu'à un plantage franc : vérifiez la liste des dépendances du script concerné dans ses logs avant de chercher plus loin dans son propre code.

Comptes de société vides ou argent d'entreprise inaccessible

Si esx_society démarre après les scripts métiers qui en dépendent (boutique, gestion d'entreprise), les comptes de société ne s'initialisent pas correctement. Vérifiez que esx_society figure bien avant ces scripts dans l'ordre du server.cfg, pas seulement après es_extended. Un restart dans le bon ordre résout le problème.

Une resource reste listée mais ne démarre jamais, sans erreur explicite

Symptôme distinct d'une dépendance manquante : la resource apparaît bien dans la liste renvoyée par le panel, mais reste inactive, sans message qui saute aux yeux dans les logs console. La cause la plus fréquente est un fxmanifest.lua qui ne déclare pas (ou déclare mal) ses deux champs obligatoires, fx_version et game : FXServer lit le manifeste avant tout le reste, et s'il est absent ou mal formé, la resource reste chargée mais jamais initialisée. Sur une resource ESX Legacy actuelle, la valeur attendue est fx_version 'cerulean' et game 'gta5'.

« Used the getSharedObject Event, this event no longer exists! »

Un script ancien qui utilise encore l'appel TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end) déclenche cette erreur sur une installation ESX Legacy actuelle : cet event a été retiré au profit de l'export ESX = exports['es_extended']:getSharedObject(). La correction consiste à remplacer ces lignes dans le script concerné, côté client comme côté serveur, plutôt qu'à chercher une rétrocompatibilité qui n'existe plus dans les versions actuelles du framework.

Comment ranger les resources ESX dans le dossier resources/

La convention de la communauté ESX Legacy range les resources par famille plutôt que de tout mettre à plat, ce qui évite de perdre le fil une fois la dizaine de scripts installée :

• resources/[core]/ : le cœur du framework, es_extended et oxmysql, tout ce qui doit démarrer avant le reste.
• resources/[standalone]/ : des scripts indépendants qui ne dépendent pas directement d'ESX (une bibliothèque de cartes ou d'interface, par exemple).
• resources/[esx_addons]/ (ou resources/[esx]/ selon les packs) : les ressources officielles ou communautaires bâties spécifiquement sur ESX (métiers, société, menus).

Le nom du dossier entre crochets n'a aucune valeur technique pour FXServer, qui charge simplement tout ce qui se trouve sous resources/ quel que soit le rangement : c'est une convention de lisibilité, pas une obligation. Mais s'y tenir dès le départ évite un dossier resources/ illisible au bout de vingt packages de scripts.

Ce que contient la base au premier démarrage

Le fichier .sql importé à l'étape 5 ne crée pas seulement des tables vides : il pré-remplit un jeu de données de départ pour que le serveur soit jouable immédiatement, avant même d'ajouter vos propres métiers :

• Table users : vide au départ, un compte y est créé automatiquement à la première connexion (login en jeu) de chaque joueur.
• Table job_grades : préremplie avec un métier unemployed (chômeur, le job par défaut de tout nouveau personnage) et, selon la version du schéma, des métiers de base comme police ou ambulance avec plusieurs échelons hiérarchiques déjà salariés.
• Table items : un socle d'objets courants (identifiant, libellé, poids), à compléter au fur et à mesure des scripts d'inventaire ajoutés.

Si votre projet n'a pas besoin de ces métiers de base, il est plus sûr de les laisser en place au premier démarrage puis de les retirer une fois le serveur stable, plutôt que de modifier le fichier .sql avant import : une erreur de syntaxe SQL à ce stade bloque l'import complet, pas seulement la ligne concernée.

Les exports ESX les plus utilisés au quotidien

Une fois ESX Legacy démarré, la quasi-totalité des scripts qui viennent se greffer dessus passent par le même objet partagé, récupéré ainsi :

ESX = exports['es_extended']:getSharedObject()

Deux exports reviennent dans la majorité des scripts métiers et valent d'être connus avant d'aller plus loin :

• ESX.GetPlayerFromId(playerId) récupère l'objet joueur complet (argent, inventaire, job) côté serveur à partir de son identifiant de session, et renvoie nil si l'identifiant ne correspond à personne, un cas à toujours gérer avant d'utiliser l'objet retourné.
• ESX.RegisterUsableItem(nomItem, callback) déclare ce qui se passe quand un joueur utilise un item de son inventaire, callback exécuté côté serveur avec l'identifiant du joueur en paramètre. C'est le point d'entrée standard pour tout objet consommable (soin, nourriture, outil).

Un détail contre-intuitif piège souvent qui découvre RegisterUsableItem pour la première fois : ESX ne retire jamais l'item automatiquement après son utilisation. C'est au script de le faire explicitement, à l'intérieur du callback, avec xPlayer.removeInventoryItem(nomItem, quantite) sur l'objet joueur récupéré via ESX.GetPlayerFromId. Oublier cet appel est une erreur fréquente : l'item reste utilisable indéfiniment, ce qui casse l'équilibrage de n'importe quel objet censé se consommer une seule fois.

Société, job et grade : trois notions distinctes à ne pas confondre

Ces trois termes reviennent partout dans la documentation ESX et désignent des choses différentes :

• Le job est le métier du personnage (police, mecano, unemployed), stocké directement sur la table users dans la base MySQL.
• Le grade est l'échelon hiérarchique du joueur au sein de ce job (de simple employé à patron), défini table job_grades avec un salaire propre à chaque échelon.
• La société est le compte bancaire partagé d'un job géré par esx_society (par exemple society_police) : seul le grade marqué comme boss dans la configuration du job voit l'argent de la société s'afficher et peut gérer les salaires des employés.

esx_society doit impérativement démarrer avant tout script qui utilise un compte de société : un ordre inversé dans server.cfg casse silencieusement la gestion d'entreprise de ces scripts, sans forcément produire d'erreur explicite dans les logs.

Backup et migration d'un serveur ESX Legacy

Une fois votre serveur ESX en production avec des joueurs, deux opérations deviennent critiques : le backup régulier et la migration éventuelle vers un autre hébergement.

Backup : sauvegardez régulièrement trois éléments : la base de données MySQL complète (export .sql via phpMyAdmin ou sudo mysqldump nom_de_la_base > backup.sql en ligne de commande), le dossier resources/ (qui contient tous vos scripts et leur configuration), et le fichier server.cfg. Sans ces trois éléments, une restauration complète est impossible.

Migration : si vous changez d'hébergeur ou passez d'un hébergement FiveM managé à un VPS Linux, la migration consiste à transférer ces mêmes trois éléments vers le nouveau serveur, importer le dump SQL dans la nouvelle base de données, et ajuster la chaîne mysql_connection_string dans server.cfg avec les nouveaux identifiants de login. Notre guide migrer son serveur FiveM d'un hébergeur à l'autre détaille la procédure pas à pas.

txAdmin et le serveur web intégré

txAdmin, l'interface de gestion la plus utilisée pour administrer un serveur FiveM, embarque son propre serveur web accessible depuis un navigateur (par défaut sur le port 40120). Ce serveur web permet aux administrateurs de gérer les resources, consulter les logs, redémarrer le serveur et modérer les joueurs sans accès SSH direct.

Si vous hébergez FiveM sur un VPS ou un serveur dédié et que vous souhaitez accéder à txAdmin depuis l'extérieur via un nom de domaine, vous pouvez configurer un reverse proxy Nginx ou Apache devant le port de txAdmin. Cela permet d'utiliser HTTPS et de ne pas exposer le port directement sur l'adresse IP publique. Cette configuration est optionnelle : txAdmin fonctionne très bien en accès direct par IP et port.

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 et de packages installés grimpe : chaque resource consomme de la mémoire, et un serveur RP chargé avec cinquante scripts peut facilement dépasser les 4 Go.
• La qualité de la liaison à la base de données sous charge, surtout sur un hébergement qui n'offre pas de ressources dédiées. C'est là que la plupart des serveurs RP se mettent à lag, pas dans ESX lui-même.

Pour aller plus loin : notre guide scripts FiveM : où les trouver, lesquels éviter vous aidera à choisir les bons packages pour compléter votre installation ESX Legacy. Et si vous êtes déjà limité par votre hébergement actuel, on a écrit une page pour ça.