Installer ESX Legacy sur un serveur FiveM

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 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. 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.

É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, même sur un hébergement mutualisé où plusieurs bases cohabitent sur le même serveur. 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.

1. Téléchargez la dernière release d'oxmysql depuis son dépôt officiel.
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

É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_list

Ajoutez 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"

É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.

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 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 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 : ça permet de révoquer un accès individuel sans toucher aux autres.

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.

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é 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.

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 en 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' ; une resource ancienne récupérée telle quelle, écrite pour un format de manifeste antérieur, est une source fréquente de ce symptôme précis.

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

Un script ancien, ou une ressource tierce pas mise à jour, qui utilise encore l'ancien 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 utilisé plus haut dans ce guide, 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 compatibilité 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/ qui devient illisible au bout de vingt 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 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 chez un débutant : 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.
• 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 en console.

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, 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. Si vous êtes déjà dans ce cas sur votre hébergement actuel, on a écrit une page pour ça.