LOOP Docs
Menu F1GuidesItems
Accueil/Installation/Installer sa base LOOP soi-même

Installer sa base LOOP soi-même

Vous n’êtes pas hébergé chez LOOP (LoopCloud) et vous montez le serveur vous-même, sur un VPS, un serveur dédié ou votre propre PC. Cette page reprend tout, dans l’ordre : la machine, les artefacts FiveM, txAdmin, l’envoi des fichiers avec WinSCP, la base de données, l’emplacement et le rôle de chaque fichier .cfg, puis le premier démarrage et le dépannage.

Les crochets sont à remplacer

Dans tous les exemples de cette page, chaque valeur entre crochets ([TA_CLE_CFX], [MOT_DE_PASSE], [IP_DU_SERVEUR]...) est à remplacer par la vôtre, crochets compris. Aucune vraie valeur n’est montrée ici. Vos clés, mots de passe et tokens ne doivent jamais sortir du serveur : ni dans Discord, ni dans un ticket, ni sur une capture d’écran.

Vue d’ensemble

  1. Préparer la machine : VPS ou PC, Windows ou Linux, avec un accès administrateur.
  2. Rassembler les quatre éléments : les artefacts FiveM, txAdmin (inclus dans les artefacts), la clé serveur Cfx et la licence LOOP.
  3. Installer MariaDB, créer la base et son utilisateur, importer base.sql.
  4. Envoyer la base sur la machine avec WinSCP et poser les fichiers .cfg à la racine du dossier serveur.
  5. Remplir les .cfg (clés, chaîne de connexion SQL, identité du serveur).
  6. Lancer txAdmin, pointer le dossier serveur, activer OneSync, démarrer.
  7. Contrôler avec loopdoctor dans la console, puis faire la recette en jeu.

1. Les prérequis

La machine

Minimum conseillé Remarque
Système Linux 64 bits (Debian 12 ou Ubuntu 22.04/24.04) ou Windows Server 2019+ / Windows 10-11 Linux est plus léger et plus stable pour un serveur ouvert en continu. Windows convient très bien pour un serveur de test sur votre PC.
Mémoire 8 Go pour un test à 15-20 joueurs, 16 Go et plus pour un serveur ouvert La base, ses interfaces et les packs de véhicules et de maps chargent beaucoup en mémoire.
Processeur 4 cœurs récents, bonne fréquence FXServer profite surtout d’une fréquence élevée. La référence mesurée de la base est d’environ 0,80 ms de temps serveur.
Disque SSD, 40 Go libres au minimum Base, packs de contenu, cache FiveM, logs et sauvegardes SQL.
Réseau IP publique fixe, bonne bande passante montante Les joueurs téléchargent les streams à la première connexion.
Sorties HTTP Autorisées vers https://loopstudios.fr La licence LOOP en a besoin. Certains hébergeurs les bloquent : vérifiez avant de louer.

PC à la maison

Un serveur sur votre PC fonctionne pour développer et tester. Pour que d’autres joueurs s’y connectent, il faut ouvrir le port du jeu sur la box (redirection de port vers l’IP locale du PC) et laisser le PC allumé. Pour un serveur ouvert au public, prenez un VPS ou un dédié.

Les quatre éléments à avoir sous la main

Élément Où l’obtenir Où il va
Artefacts FXServer (le programme serveur FiveM) runtime.fivem.net, rubrique artefacts, version recommended (Windows : build_server_windows, Linux : build_proot_linux) Un dossier à part, par exemple fxserver/
txAdmin (l’interface web de gestion) Inclus dans les artefacts, rien à télécharger en plus S’ouvre sur le port 40120
Clé serveur Cfx portal.cfx.re (anciennement keymaster), avec votre compte Cfx.re : créez une clé pour l’IP de votre serveur sv_licenseKey dans server.cfg
Licence LOOP Espace client → Compte → Licences et factures, sur la carte de la licence Afficher puis Copier loop_license dans server.cfg
La base LOOP (ZIP) Espace client → Compte → Téléchargements, LOOP Prime V2 Le dossier serveur (voir plus bas)

La licence LOOP est liée à l’identifiant Cfx de votre serveur, c’est-à-dire à la clé sv_licenseKey. Si vous changez de clé Cfx ou de machine, pensez à Réinitialiser le verrou IP sur la carte de la licence (voir Licence et erreurs).

Il vous faut aussi :

  • WinSCP (winscp.net) sur votre PC Windows, pour envoyer les fichiers vers un VPS Linux ;
  • un client SSH pour taper les commandes sur le VPS : PuTTY, ou simplement le terminal de Windows (ssh [UTILISATEUR_SSH]@[IP_DU_SERVEUR]) ;
  • un outil pour la base de données : HeidiSQL (installé avec MariaDB sous Windows), phpMyAdmin, ou la ligne de commande mariadb.

2. Préparer la machine

Sous Linux (VPS ou dédié)

Connectez-vous en SSH avec le compte fourni par l’hébergeur, puis mettez le système à jour et créez un utilisateur dédié au serveur. Ne faites jamais tourner FiveM en root.

sudo apt update && sudo apt upgrade -y
sudo apt install -y xz-utils unzip screen curl
sudo adduser [UTILISATEUR_FIVEM]
sudo mkdir -p /home/[UTILISATEUR_FIVEM]/fxserver /home/[UTILISATEUR_FIVEM]/loop
sudo chown -R [UTILISATEUR_FIVEM]:[UTILISATEUR_FIVEM] /home/[UTILISATEUR_FIVEM]

Téléchargez les artefacts dans fxserver/ (copiez le lien de la dernière version recommended depuis runtime.fivem.net) :

cd /home/[UTILISATEUR_FIVEM]/fxserver
curl -L -o fx.tar.xz "[LIEN_DES_ARTEFACTS_RECOMMENDED]"
tar xf fx.tar.xz && rm fx.tar.xz
chmod +x run.sh

Ouvrez le pare-feu : le port du jeu en TCP et UDP, et txAdmin en TCP. Le port de la base de données (3306) ne doit jamais être ouvert sur Internet.

sudo apt install -y ufw
sudo ufw allow OpenSSH
sudo ufw allow [PORT_DU_JEU]/tcp
sudo ufw allow [PORT_DU_JEU]/udp
sudo ufw allow 40120/tcp
sudo ufw enable

[PORT_DU_JEU] est celui que vous mettrez dans endpoint_add_tcp / endpoint_add_udp : 30120 par défaut dans FiveM, 10013 dans le modèle LOOP. Une fois txAdmin configuré, vous pouvez restreindre le 40120 à votre propre IP.

Sous Windows (VPS Windows ou PC)

  1. Créer les dossiers, par exemple C:\FXServer\fxserver (artefacts) et C:\FXServer\loop (serveur). Évitez le Bureau, OneDrive et les chemins avec des accents.
  2. Télécharger les artefacts Windows server.7z (version recommended) et les extraire dans C:\FXServer\fxserver avec 7-Zip. Vous devez y voir FXServer.exe.
  3. Installer le Visual C++ Redistributable x64 de Microsoft s’il manque (FXServer refuse sinon de démarrer).
  4. Ouvrir le pare-feu Windows : Pare-feu Windows Defender → Paramètres avancés → Règles de trafic entrant → Nouvelle règle → Port, une règle TCP et une règle UDP pour [PORT_DU_JEU], et une règle TCP 40120 si vous gérez txAdmin à distance.
  5. Sur un PC à la maison, ajouter la redirection du port du jeu (TCP et UDP) dans l’interface de votre box vers l’IP locale du PC.

Sur un VPS Windows, vous travaillez par le Bureau à distance : les fichiers se copient directement, WinSCP n’est utile que si un serveur OpenSSH est activé sur la machine.

3. La base de données

La base LOOP est validée sur MariaDB (loop_dev tourne sur MariaDB 11.8). MySQL 8 n’est pas encore validé : préférez MariaDB 10.6 ou plus récent. La connexion passe par oxmysql (version 2.13 livrée dans [Fivem]), qui doit démarrer avant tout le reste.

Installer MariaDB

Linux :

sudo apt install -y mariadb-server
sudo systemctl enable --now mariadb
sudo mariadb-secure-installation

À mariadb-secure-installation, répondez oui à tout : mot de passe root, suppression des comptes anonymes, interdiction de root à distance, suppression de la base de test.

Windows : téléchargez l’installateur MSI de MariaDB (mariadb.org), choisissez un mot de passe root, cochez « Use UTF8 as default server’s character set », laissez le port 3306 et le service Windows activé. HeidiSQL est installé avec : c’est l’outil le plus simple pour la suite.

XAMPP ou WAMP

Pour un simple test sur PC, XAMPP marche aussi (ligne MySQL verte dans le panneau). Son compte par défaut est root sans mot de passe, et sa configuration nécessite souvent le réglage du format de lignes décrit dans le dépannage plus bas.

Créer la base et l’utilisateur

Ouvrez la console SQL (sudo mariadb sous Linux, ou l’onglet Requête de HeidiSQL connecté en root) et créez une base vide et dédiée en utf8mb4, puis un utilisateur qui n’a de droits que sur elle :

CREATE DATABASE `[NOM_DE_LA_BASE]` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER '[UTILISATEUR_SQL]'@'localhost' IDENTIFIED BY '[MOT_DE_PASSE_SQL]';
GRANT ALL PRIVILEGES ON `[NOM_DE_LA_BASE]`.* TO '[UTILISATEUR_SQL]'@'localhost';
FLUSH PRIVILEGES;
  • utf8mb4_unicode_ci est la collation attendue par la base : c’est celle que loop_schema applique aux tables. Une autre collation donne des accents cassés et l’erreur « Illegal mix of collations ».
  • 'localhost' : l’utilisateur ne peut se connecter que depuis la machine elle-même, ce qui est le cas normal (FiveM et MariaDB sur le même serveur). Si la base est sur une autre machine, remplacez localhost par l’IP du serveur FiveM, jamais par % ouvert à tous.
  • Choisissez un mot de passe long, sans @, :, / ni ? : ces caractères cassent la chaîne de connexion (sinon, il faut les encoder, voir plus bas).

Vérifiez les réglages du serveur SQL :

SELECT @@character_set_server, @@collation_server, @@innodb_default_row_format;

Le résultat attendu est utf8mb4, une collation utf8mb4_... et dynamic. Si le format de lignes est compact, corrigez-le avant l’import (voir le dépannage).

Importer base.sql

Pour une installation neuve uniquement, importez le fichier base.sql livré avec la base. Il contient le schéma actuel et les données de référence (groupes, métiers, catalogues), sans aucune donnée de joueur. Envoyez-le d’abord sur la machine avec WinSCP (section suivante), puis :

mariadb -u [UTILISATEUR_SQL] -p [NOM_DE_LA_BASE] < base.sql

Avec HeidiSQL ou phpMyAdmin : sélectionnez d’abord votre base dans la colonne de gauche, puis Fichier → Exécuter un fichier SQL (HeidiSQL) ou l’onglet Importer (phpMyAdmin).

Les pièges de l’import

  • Ne réimportez jamais base.sql sur un serveur qui tourne déjà : les mises à jour passent par loop_schema, au démarrage. Faites toujours une sauvegarde avant de toucher à une base existante.
  • N’importez pas le .sql d’es_extended à part : l’ancien fichier commençait par CREATE DATABASE puis USE es_extended, ce qui envoie tout dans une base es_extended créée à côté de la vôtre. L’import affiche une réussite, mais le métier unemployed manque et la création de personnage échoue (« Erreur lors de la création du personnage »).
  • Votre base est celle écrite à la fin de mysql_connection_string. Si une base es_extended vide est apparue, ne la sélectionnez jamais pour un import.

Au démarrage, loop_schema complète de toute façon ce qui manque : il crée les tables absentes, ajoute les colonnes et index des mises à jour, répare les compteurs, corrige les collations et remplit les données de référence. Les données existantes ne sont jamais effacées.

Sauvegarder la base

Prenez l’habitude d’une sauvegarde avant chaque mise à jour, et d’une sauvegarde automatique quotidienne :

mariadb-dump -u [UTILISATEUR_SQL] -p --single-transaction [NOM_DE_LA_BASE] > sauvegarde-[DATE].sql

4. Envoyer les fichiers avec WinSCP

WinSCP envoie les fichiers de votre PC Windows vers le VPS par SFTP (le transfert passe par SSH, il est chiffré). N’utilisez pas de FTP simple.

Se connecter

  1. Installer WinSCP depuis winscp.net et l’ouvrir. La fenêtre Connexion s’affiche.
  2. Nouveau site : Protocole de fichier SFTP, Nom d’hôte [IP_DU_SERVEUR], Numéro de port 22 (ou celui donné par l’hébergeur), Nom d’utilisateur [UTILISATEUR_FIVEM], Mot de passe [MOT_DE_PASSE_SSH].
  3. Avec une clé SSH à la place du mot de passe : Avancé → SSH → Authentification → Fichier de clé privée, choisissez votre clé (WinSCP convertit une clé OpenSSH au format .ppk si besoin).
  4. Enregistrer le site (sans enregistrer le mot de passe si le PC est partagé), puis Connexion.
  5. Première connexion : WinSCP affiche l’empreinte de la clé du serveur. Comparez-la avec celle donnée par l’hébergeur, puis Oui pour l’accepter. Si cet avertissement réapparaît plus tard sans que vous ayez réinstallé le serveur, arrêtez-vous et vérifiez.

Connectez-vous avec l’utilisateur dédié ([UTILISATEUR_FIVEM]), pas en root : les fichiers lui appartiendront directement et le serveur pourra les lire et les écrire.

Régler le mode de transfert

Avant d’envoyer quoi que ce soit : Options → Préférences → Transfert, puis Binaire comme mode de transfert par défaut (ou, dans la boîte de transfert, Paramètres de transfert → Binaire). En mode « Texte » ou « Automatique », WinSCP réécrit les fins de ligne de certains fichiers (.cfg, .js, .sh...) : les fichiers protégés de la base doivent arriver à l’octet près.

Méthode conseillée : envoyer le ZIP et l’extraire sur le serveur

Les interfaces de la base sont faites de milliers de petits fichiers. Un transfert fichier par fichier est long, et une coupure en cours de route en oublie une partie sans prévenir (écran noir à la place de l’inventaire ou du menu). Le plus sûr :

  1. Dans le panneau de gauche (votre PC), allez dans le dossier où se trouve le ZIP de la base.
  2. Dans le panneau de droite (le serveur), ouvrez /home/[UTILISATEUR_FIVEM]/loop.
  3. Glissez le ZIP de gauche à droite et attendez la fin (barre de progression en bas).
  4. Extrayez-le sur le serveur dans le terminal SSH (ou dans WinSCP : Commandes → Ouvrir le terminal) :
cd /home/[UTILISATEUR_FIVEM]/loop
unzip [NOM_DU_ZIP].zip
rm [NOM_DU_ZIP].zip

Vérifiez ensuite qu’il n’y a pas de dossier en double : vous devez avoir loop/resources/[Script]/loop-framework/..., et non loop/[NOM_DU_ZIP]/resources/... ni loop-framework/loop-framework/.... Si le ZIP contient un dossier racine, remontez son contenu d’un niveau.

Méthode glisser-déposer (dossier par dossier)

Si vous préférez envoyer les dossiers déjà extraits :

  1. Extrayez le ZIP sur votre PC avec 7-Zip, en entier.
  2. Glissez le dossier resources et les fichiers .cfg vers /home/[UTILISATEUR_FIVEM]/loop dans le panneau de droite.
  3. Laissez le transfert aller au bout. Ne fermez pas WinSCP et ne mettez pas le PC en veille. Si la connexion coupe, recommencez la ressource concernée.
  4. Après une coupure, supprimez d’abord le dossier à moitié copié sur le serveur avant de le renvoyer, sinon les fichiers incomplets restent en place.
  5. Pour une mise à jour, utilisez plutôt Commandes → Synchroniser (de gauche vers droite) en décochant la suppression des fichiers distants : vos réglages et vos données du monde ne doivent pas être écrasés (voir l’encart en fin de section).

Les noms comptent sous Linux

Linux distingue majuscules et minuscules : [Script] et [script] sont deux dossiers différents, comme server.cfg et Server.cfg. Gardez les noms exactement comme dans le ZIP, crochets compris.

L’arborescence finale

/home/[UTILISATEUR_FIVEM]/
├── fxserver/                  ← les artefacts (run.sh sous Linux, FXServer.exe sous Windows)
├── txData/                    ← créé par txAdmin au premier lancement
└── loop/                      ← LE dossier serveur (« Server Data Folder » de txAdmin)
    ├── server.cfg             ← lancé par txAdmin, appelle tous les autres
    ├── customization.cfg
    ├── discord.cfg
    ├── resources.cfg
    ├── assets.cfg
    ├── assets_optional.cfg
    ├── loopprotect.cfg        ← optionnel (anticheat)
    ├── hardening.cfg          ← optionnel (durcissement du moteur)
    ├── icon.png               ← optionnel (icône 96×96 de la liste FiveM)
    ├── base.sql               ← à importer, puis à retirer du dossier
    └── resources/
        ├── [Fivem]/           oxmysql, es_extended, pma-voice, chat, bob74_ipl...
        ├── [ESX]/             esx_identity, esx_multicharacter, esx_society...
        ├── [OX]/              ox_lib, ox_inventory, ox_target
        ├── [Script]/          toute la base LOOP (loop-framework, loop-f1, loop-ui, phone...)
        ├── [moddings]/        packs de véhicules, maps, vêtements, sons
        └── LoopProtect/       anticheat

Sous Windows, c’est la même chose sous C:\FXServer\ : fxserver\FXServer.exe, et loop\server.cfg à côté de loop\resources\.

Les fichiers .cfg vont à la racine du dossier serveur, à côté de resources/, jamais à l’intérieur. Les modèles sont livrés dans le dossier cfg_client/ du ZIP : copiez-les à la racine (ou générez-les avec l’assistant de démarrage).

Les droits des fichiers (Linux)

Si vous vous êtes connecté avec l’utilisateur dédié, les droits sont déjà bons. Si vous avez envoyé les fichiers en root, rendez-les à l’utilisateur du serveur :

sudo chown -R [UTILISATEUR_FIVEM]:[UTILISATEUR_FIVEM] /home/[UTILISATEUR_FIVEM]/loop /home/[UTILISATEUR_FIVEM]/fxserver
find /home/[UTILISATEUR_FIVEM]/loop -type d -exec chmod 755 {} +
find /home/[UTILISATEUR_FIVEM]/loop -type f -exec chmod 644 {} +
chmod 600 /home/[UTILISATEUR_FIVEM]/loop/*.cfg
chmod +x /home/[UTILISATEUR_FIVEM]/fxserver/run.sh
Droit Pour quoi Dans WinSCP
755 sur les dossiers Le serveur peut entrer dans les dossiers et y écrire (données du monde, images, caches). Clic droit → Propriétés → Permissions, octal 0755, cocher Définir le groupe, le propriétaire et les permissions récursivement
644 sur les fichiers Lisibles par le serveur, modifiables par leur propriétaire. Octal 0644
600 sur les .cfg Les fichiers qui contiennent vos clés ne sont lisibles que par l’utilisateur du serveur. Octal 0600
+x sur run.sh Le script de lancement des artefacts doit être exécutable. Octal 0755 sur run.sh

Le serveur doit pouvoir écrire dans resources/[Script]/loop-storage/serverdata (markers, portes, zones...) et dans les dossiers d’images de loop-image (studio de capture). Si le studio ne peut pas enregistrer, la commande console greenstate affiche la commande chown exacte à lancer.

Mises à jour : ce qu’il ne faut pas écraser

Lors d’une mise à jour, ne remplacez pas vos fichiers .cfg remplis, ni resources/[Script]/loop-storage/serverdata/ (le contenu de votre monde, réécrit par le serveur), ni vos rangs dans loop-permissions/data/. Arrêtez le serveur avant d’envoyer, sauvegardez la base, puis laissez loop_schema appliquer les migrations au redémarrage.

5. Les fichiers .cfg : emplacement et rôle

Tous les fichiers sont à la racine du dossier serveur. txAdmin ne lance que server.cfg, qui appelle les autres avec exec :

Fichier Appelé par Rôle Contient des secrets
server.cfg txAdmin Réglages techniques : port, clé Cfx, licence LOOP, connexion SQL, build du jeu, places, droits ACE de base, inventaire, réservoirs du moteur. Se termine par exec resources.cfg. Oui
customization.cfg server.cfg Identité du serveur : nom, logo, couleur, écran de chargement, boutique, clés Fivemanage, accès fondateur. Oui (boutique, Fivemanage)
discord.cfg server.cfg Bot Discord, whitelist, présence, badges. Tout reste désactivé tant que token et guilde sont vides. Oui (token)
hardening.cfg server.cfg (optionnel) Durcissement du moteur, déjà réglé : ne modifiez pas les lignes commentées, elles casseraient la base. Non
resources.cfg server.cfg, en dernier Ordre de démarrage des ressources. Non
loopprotect.cfg resources.cfg (optionnel) Démarre l’anticheat et donne ses droits au groupe admin. Non
assets.cfg resources.cfg Packs de contenu standard sous [moddings]. Non
assets_optional.cfg resources.cfg Packs sous Asset Escrow (core_cinematics, fatpack6), commentés par défaut. Non

Ordre de lecture : server.cfg → customization.cfg → discord.cfg → (hardening.cfg) → resources.cfg → loopprotect.cfg, assets.cfg, assets_optional.cfg. Tous les réglages doivent être lus avant exec resources.cfg, sinon les ressources démarrent avec leurs valeurs par défaut. Si une convar est écrite deux fois, la dernière lue gagne : ne recopiez pas une ligne d’un fichier dans un autre.

Règle d’or : un secret se pose avec set (lu par le serveur seul), jamais avec setr (envoyé à tous les joueurs).

Le détail de chaque ligne est sur la page Configuration. Voici les modèles à remplir.

server.cfg

server.cfg
# Attendre la réussite des migrations avant les requêtes applicatives.
set loop_schema_required 1
set loop_schema_timeout 120000

endpoint_add_tcp "0.0.0.0:[PORT_DU_JEU]"
endpoint_add_udp "0.0.0.0:[PORT_DU_JEU]"

set sv_licenseKey "[TA_CLE_CFX]"
# LOOP Guard : licence LOOP (système intégré)
set loop_license "[TA_CLE_LOOP]"
exec customization.cfg

set mysql_connection_string "mysql://[UTILISATEUR_SQL]:[MOT_DE_PASSE_SQL]@[HOTE_SQL]:[PORT_SQL]/[NOM_DE_LA_BASE]?charset=utf8mb4"
set mysql_ui [true_OU_false]
set mysql_slow_query_warning [SEUIL_EN_MS]
set mysql_resultset_warning [NOMBRE_DE_LIGNES]
exec discord.cfg

sv_enforceGameBuild 3570
sv_maxclients [NOMBRE_DE_PLACES]
set event_size 1048576
sv_authMinTrust 1
set sv_requestParanoia 3
sv_master1 ""
set sv_pureLevel 0
# OneSync se règle dans txAdmin, pas ici (le validateur de txAdmin refuse la ligne).
# set onesync on
set resources_useSystemChat false
setr voice_enableRadioAnim 0
setr voice_useNativeAudio true
setr voice_useSendingRangeOnly true
setr voice_refreshRate 300
setr esx:locale "fr"
setr illenium-appearance:locale "fr"
sets locale "FR"
set sv_useDirectListing false

add_principal group.admin group.user
add_ace group.admin command allow
add_ace group.admin command.quit deny
add_ace resource.es_extended command.add_ace allow
add_ace resource.es_extended command.add_principal allow
add_ace resource.es_extended command.remove_principal allow
add_ace resource.es_extended command.stop allow
add_principal identifier.discord:[TON_ID_DISCORD] group.admin

setr inventory:framework "esx"
setr inventory:slots 50
setr inventory:weight 50000
setr inventory:target false
setr inventory:police ["police", "bcso"]
setr inventory:imagepath "nui://ox_inventory/web/images"
setr inventory:autoreload false
setr inventory:screenblur true
setr inventory:keys [VALEUR_DU_MODELE]
setr inventory:enablekeys [VALEUR_DU_MODELE]
setr inventory:aimedfiring false
setr inventory:giveplayerlist false
setr inventory:weaponanims true
setr inventory:itemnotify 1
setr inventory:dropprops true
setr inventory:dropmodel "v_serv_abox_02"
setr inventory:weaponmismatch true
setr inventory:ignoreweapons []
setr inventory:suppresspickups 1

set inventory:versioncheck true
set inventory:clearstashes "6 MONTH"
set inventory:webhook "[LIEN_WEBHOOK_DISCORD_LOGS_INVENTAIRE]"
set inventory:loglevel 2
set inventory:randomprices false
set inventory:randomloot false
set inventory:evidencegrade 2
setr inventory:trimplate true
set inventory:vehicleloot []
set inventory:dumpsterloot []
set inventory:accounts ["money", "black_money"]
setr ox:locale fr

increase_pool_size "ScaleformStore" 200
increase_pool_size "TxdStore" 26000
increase_pool_size "DrawableStore" 50000
increase_pool_size "FragmentStore" 14000
increase_pool_size "InteriorProxy" 450
increase_pool_size "AnimStore" 20480
setr disconnected_chars 1

# Optionnel : durcissement du moteur
# exec hardening.cfg

# Charger les ressources après TOUS les réglages.
exec resources.cfg

Ce qu’il faut remplir :

Crochet Valeur
[PORT_DU_JEU] Le port ouvert dans le pare-feu, le même dans les deux lignes endpoint_add_* (30120 par défaut).
[TA_CLE_CFX] La clé serveur créée sur portal.cfx.re.
[TA_CLE_LOOP] La licence copiée depuis l’espace client. Une valeur vide ou restée sur un exemple est refusée d’office.
[UTILISATEUR_SQL], [MOT_DE_PASSE_SQL], [NOM_DE_LA_BASE] Ceux créés à l’étape 3.
[HOTE_SQL]:[PORT_SQL] 127.0.0.1:3306 si MariaDB est sur la même machine (voir l’encart ci-dessous).
mysql_ui, mysql_slow_query_warning, mysql_resultset_warning Réglages d’oxmysql : interface de débogage (false en production), seuil d’alerte des requêtes lentes en millisecondes, alerte sur les résultats trop volumineux. Ils ne changent que les alertes.
[NOMBRE_DE_PLACES] Au-delà de 32, OneSync est obligatoire ; restez dans la limite de votre clé Cfx.
[TON_ID_DISCORD] Votre ID de compte Discord (17 à 20 chiffres) : il donne le groupe ACE admin, pas les rangs staff de la base.
[VALEUR_DU_MODELE] Gardez la valeur livrée dans cfg_client/server.cfg.
[LIEN_WEBHOOK_DISCORD_LOGS_INVENTAIRE] Optionnel : un webhook Discord (https://discord.com/api/webhooks/...) pour les journaux d’inventaire. Secret.

La chaîne de connexion mysql_connection_string

oxmysql accepte deux écritures. La forme URL, celle du modèle :

set mysql_connection_string "mysql://[UTILISATEUR_SQL]:[MOT_DE_PASSE_SQL]@127.0.0.1:3306/[NOM_DE_LA_BASE]?charset=utf8mb4"

Ou la forme par clés, plus lisible si le mot de passe contient des caractères spéciaux :

set mysql_connection_string "host=127.0.0.1;port=3306;user=[UTILISATEUR_SQL];password=[MOT_DE_PASSE_SQL];database=[NOM_DE_LA_BASE];charset=utf8mb4"
Morceau À savoir
mysql:// Toujours ce préfixe, même avec MariaDB.
[UTILISATEUR_SQL]:[MOT_DE_PASSE_SQL] Dans la forme URL, un mot de passe qui contient @, :, /, # ou ? doit être encodé (@ devient %40, : devient %3A, / devient %2F, # devient %23, ? devient %3F). Le plus simple reste un mot de passe long fait de lettres et de chiffres.
127.0.0.1 Préférez l’IP à localhost : sur certaines machines localhost part en IPv6 (::1) alors que MariaDB n’écoute qu’en IPv4, et la connexion est refusée.
:3306 Le port par défaut de MariaDB et MySQL, facultatif s’il n’a pas changé.
/[NOM_DE_LA_BASE] La base créée à l’étape 3. C’est elle qu’il faut sélectionner pour tout import SQL.
?charset=utf8mb4 À garder : sans lui, accents et emojis sont cassés dans les noms, messages et objets.
XAMPP en local mysql://root@127.0.0.1/[NOM_DE_LA_BASE]?charset=utf8mb4 (root sans mot de passe par défaut, pour un test uniquement).

La ligne commence par set, jamais setr. Si elle est absente ou restée sur l’exemple user:password, loopdoctor bloque les connexions.

customization.cfg

customization.cfg
# Personnalisation : 1 réglage = 1 convar, aucun doublon

sv_hostname "[NOM_COMPLET_DU_SERVEUR]"
sets sv_projectName "[NOM_DU_SERVEUR]"
sets sv_projectDesc "[DESCRIPTION_COURTE]"
sets tags "rp, roleplay, esx, fr"
sets Owner "[TON_PSEUDO]"
sets Développeur "[TON_PSEUDO]"
sets Discord "https://discord.gg/[TON_INVITATION]"
sets banner_detail "[LIEN_IMAGE_BANNIERE_OU_VIDE]"
sets banner_connecting "[LIEN_IMAGE_BANNIERE_OU_VIDE]"
load_server_icon "icon.png"

setr loop:serverName "[NOM_DU_SERVEUR]"
# Lien durable (Fivemanage, votre site). Pas de pièce jointe Discord : le lien expire.
setr loop:serverLogoUrl "[LIEN_DE_TON_LOGO]"
setr volta:primaryColor "[R, V, B]"
setr volta_ui_primary_gradient "0"
setr loop:clothesImgUrl ""
setr loop:vehicleImgUrl ""

setr volta_bootstrap_discord "[TON_ID_DISCORD]"
setr loop_perm_discord true

setr loadscreen_brand "[NOM_DU_SERVEUR]"
setr loadscreen_video "[LIEN_OU_ID_YOUTUBE_OU_VIDE]"
setr loadscreen_status "Connexion au serveur..."
setr loadscreen_discord "https://discord.gg/[TON_INVITATION]"
setr loadscreen_tiktok ""
setr loadscreen_guide ""

set loop_boutique_url "[LIEN_BOUTIQUE_OU_VIDE]"
set volta_boutique_token "[JETON_BOUTIQUE]"
set FIVEMANAGE_MEDIA_API_KEY "[CLE_FIVEMANAGE]"
set phone_fivemanage_api_key "[CLE_FIVEMANAGE]"
set phone_fivemanage_api_key_image "[CLE_FIVEMANAGE]"
set LPMDT_FIVEMANAGE_API_KEY "[CLE_FIVEMANAGE]"

setr loop_cash_item "money"
setr loop_bank_name "Fleeca"
setr loop_shop_name "[NOM_DE_LA_BOUTIQUE]"
setr loop_shop_currency "Coins"
setr loop_tebex_url "[LIEN_TEBEX_OU_VIDE]"
setr loop_battlepass_enabled [1_OU_0]
setr loop_plate_prefix "[PREFIXE_PLAQUES]"

setr non_roleplay 0
setr money_dm 1
setr money_l 0

Les deux lignes indispensables au premier démarrage : volta_bootstrap_discord (votre ID de compte Discord, pas un lien : ce compte reçoit toujours le rang protégé _dev, c’est votre clé de secours) et loop:serverName. Les clés Fivemanage sont facultatives : vides, les photos et vidéos du téléphone, du MDT et de la caméra restent inactives sans casser le serveur. La plupart de ces réglages se changent aussi depuis Espace client → Personnalisation, sans redémarrage.

discord.cfg

discord.cfg
# La base parle à Discord par son API : l'application n'apparaît jamais « en ligne ».
# Tant que le token et la guilde sont vides, toute la partie Discord reste désactivée.

set loop_discord_token "[TOKEN_DU_BOT_DISCORD]"
set loop_discord_guild "[ID_DU_SERVEUR_DISCORD]"
set loop_discord_invite "https://discord.gg/[TON_INVITATION]"
# Laisser vide : généré au premier démarrage et affiché une fois en console.
set loop_discord_panel_token ""

# 1 = être membre du Discord pour se connecter. Seulement APRÈS token et guilde.
setr loop_discord_require_guild [0_OU_1]
# Laisser 0 : sinon une panne chez Discord ferme votre serveur.
setr loop_discord_strict 0

setr loop_discord_cache_ttl 600
setr loop_discord_avatar_size 128

set loop_discord_citizens_role "[ID_ROLE_CITOYENS_OU_VIDE]"
setr loop_discord_allow_everyone 0
set loop_discord_reaction_mode "menu"

setr loop_presence_enabled 1
setr loop_presence_app_id "[APPLICATION_ID_OU_VIDE]"
setr loop_presence_large_asset "logo"
setr loop_presence_small_asset "fivem"
setr loop_presence_small_text "FiveM Roleplay"
setr loop_presence_discord_url "[LIEN_DISCORD_OU_VIDE]"
setr loop_presence_connect_url "[LIEN_CONNEXION_OU_VIDE]"
setr loop_presence_refresh 30

set loop_discord_perm_order "[\"user\",\"vip\",\"helper\",\"moderator\",\"staff\",\"admin\",\"superadmin\",\"owner\"]"
set loop_discord_ranks "[{\"role\":\"[ID_ROLE_OWNER]\",\"name\":\"owner\",\"label\":\"DEV\",\"priority\":100},{\"role\":\"[ID_ROLE_STAFF]\",\"name\":\"staff\",\"label\":\"Staff\",\"priority\":40}]"

Le token se crée dans le portail développeur Discord (votre application → Bot → Reset Token) ; activez sur la même page Server Members Intent, sinon aucun rôle ne se synchronise. Les ID se copient avec le mode développeur de Discord (Paramètres → Avancés), clic droit → Copier l’identifiant. Dans les deux dernières lignes, les guillemets intérieurs restent échappés (\") : ne remplacez que les crochets. loop_discord_ranks ne règle que les badges visibles en jeu, pas les droits staff.

resources.cfg

resources.cfg
ensure spawnmanager
ensure sessionmanager
ensure hardcap
ensure bob74_ipl
ensure cron
ensure oxmysql
ensure loop_schema
ensure ox_lib

ensure es_extended
# Optionnel : anticheat, juste après es_extended
# exec loopprotect.cfg
ensure pma-voice
ensure ox_inventory
ensure ox_target
# ensure ox_fuel
ensure chat
ensure [Script]
ensure [ESX]
## ensure [Streamings]
ensure NativeUI
exec assets.cfg
exec assets_optional.cfg
ensure vinewood_glass

Rien de confidentiel ici, mais l’ordre compte : oxmysql puis loop_schema (migrations) avant tout ce qui lit la base, ox_lib avant ESX, es_extended avant pma-voice et ox_inventory, puis toute la base LOOP avec ensure [Script]. ox_fuel reste commenté : le carburant est déjà géré par la base. Une ressource ajoutée par vous se place après ensure [Script].

assets.cfg, assets_optional.cfg, loopprotect.cfg, hardening.cfg

Ces fichiers se copient tels quels depuis cfg_client/ (et le ZIP pour hardening.cfg et loopprotect.cfg), sans rien à remplir :

  • assets.cfg démarre les packs de contenu sous [moddings]. S’il est vide ou si exec assets.cfg est commenté, véhicules, maps et sons disparaissent sans erreur.
  • assets_optional.cfg : ne décommentez core_cinematics et fatpack6 que si votre clé Cfx en possède les droits Asset Escrow.
  • loopprotect.cfg : ensure LoopProtect et les droits loopprotect.admin / loopprotect.bypass du groupe admin. Activez-le en décommentant exec loopprotect.cfg dans resources.cfg.
  • hardening.cfg : activez-le en décommentant exec hardening.cfg dans server.cfg. Ses lignes commentées expliquent ce qui n’est volontairement pas appliqué : ne les activez pas.

6. Premier lancement avec txAdmin

Démarrer txAdmin

Linux (dans screen pour que le serveur continue après la fermeture du terminal) :

su - [UTILISATEUR_FIVEM]
screen -S fivem
cd ~/fxserver && ./run.sh

Pour quitter l’écran sans arrêter le serveur : Ctrl + A puis D. Pour y revenir : screen -r fivem.

Windows : double-cliquez sur FXServer.exe dans C:\FXServer\fxserver (sans argument). Une console s’ouvre.

Dans les deux cas, la console affiche l’adresse de txAdmin et un code PIN à 4 chiffres.

Configurer txAdmin

  1. Ouvrir http://[IP_DU_SERVEUR]:40120 dans votre navigateur (http://localhost:40120 sur votre PC) et saisir le code PIN.
  2. Lier votre compte Cfx.re puis choisir un mot de passe administrateur txAdmin (différent de tous les autres).
  3. Assistant de déploiement : nommez le serveur, puis choisissez Données de serveur existantes (Existing Server Data). N’utilisez pas de « recette » : elle installerait une autre base.
  4. Dossier des données (Server Data Folder) : /home/[UTILISATEUR_FIVEM]/loop (ou C:\FXServer\loop). C’est le dossier qui contient resources/.
  5. Fichier CFG : server.cfg. txAdmin le vérifie ; s’il signale la ligne onesync, laissez-la commentée.
  6. Activer OneSync : Paramètres → FXServer → OneSync sur On (Infinity), puis Enregistrer. ESX, ox_lib, ox_inventory et pma-voice l’exigent.
  7. Démarrer le serveur depuis le tableau de bord (Start Server) et suivre la Live Console.

Pour un démarrage automatique au redémarrage de la machine Linux, lancez run.sh par un service systemd ou une tâche @reboot de l’utilisateur dédié ; sous Windows, par le planificateur de tâches.

Ce qui doit apparaître dans la console

  1. oxmysql se connecte à la base, sans erreur rouge.
  2. loop_schema termine avec une ligne du type « schema : X table(s) créée(s), ... 0 erreur(s) en ... ms ». Tant qu’il n’a pas fini, les ressources qui lisent la base attendent (jusqu’à 120 s).
  3. La licence est validée : les modules LOOP démarrent, le serveur apparaît En ligne dans la vue d’ensemble de l’espace client.
  4. Tapez loopdoctor dans la console : chaque contrôle doit être OK. Sinon, suivez la section « CE QU’IL FAUT FAIRE » du rapport.
  5. Connectez-vous en jeu (F8 → connect [IP_DU_SERVEUR]:[PORT_DU_JEU]), créez un personnage et vérifiez votre rang avec /myrank.

Faites ensuite la recette complète : connexion, création de personnage, apparition, inventaire, banque, métiers, téléphone, garage, permissions staff et boutique. La suite en jeu est sur Premiers pas en jeu.

7. Dépannage

Base de données

Message ou symptôme Cause Correction
ECONNREFUSED 127.0.0.1:3306 ou ::1:3306 MariaDB arrêté, mauvais port, ou localhost résolu en IPv6 sudo systemctl status mariadb (service Windows « MariaDB » sinon) ; mettre 127.0.0.1 dans la chaîne ; vérifier le port.
ER_ACCESS_DENIED_ERROR / « Access denied for user » Utilisateur, mot de passe ou hôte faux Recréer l’utilisateur pour 'localhost' (même machine) ; encoder les caractères spéciaux du mot de passe ou en changer.
ER_BAD_DB_ERROR / « Unknown database » Nom de base faux dans la chaîne Le nom après le / doit être exactement celui de la base (majuscules comprises sous Linux).
« SQL indisponible ; installation non effectuée » loop_schema n’a pas joint la base en 60 s Corriger la connexion (lignes ci-dessus), puis redémarrer.
« La ligne mysql_connection_string est restée sur l’exemple » Chaîne non remplie Remplacer chaque crochet par votre valeur.
« Illegal mix of collations » Tables importées avec une autre collation loop_schema convertit les tables en utf8mb4_unicode_ci au démarrage ; sinon recréer la base comme à l’étape 3.
Accents ou emojis remplacés par ? Base ou chaîne sans utf8mb4 Garder ?charset=utf8mb4 ; loopdoctor corrige l’encodage de la base (les textes déjà abîmés le restent).
« Specified key was too long ; max key length is 767 bytes », « Row size too large », tables qui refusent d’être créées MySQL en row_format compact Passer innodb_default_row_format en dynamic (encart ci-dessous), redémarrer MariaDB puis le serveur : les tables manquantes se recréent seules.
« Erreur lors de la création du personnage » Métier unemployed absent (import du .sql d’es_extended dans une autre base) loopdoctor réinsère la ligne ; redémarrer ensuite (les métiers sont mis en cache).
Conflit de migration, ressources SQL bloquées loop_schema a rencontré un conflit et protège vos données Faire une sauvegarde, résoudre le conflit indiqué en console, puis taper volta_schema dans la console.
« MySQL server has gone away » pendant l’import Fichier trop gros pour la limite du serveur SQL Monter max_allowed_packet (encart ci-dessous) et relancer l’import.

Réglages du serveur SQL

Sous Linux, ajoutez un fichier /etc/mysql/mariadb.conf.d/99-loop.cnf ; sous Windows, éditez my.ini dans le dossier data de MariaDB (XAMPP : C:\xampp\mysql\bin\my.ini). Puis redémarrez MariaDB.

99-loop.cnf
[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
innodb_file_per_table = 1
innodb_default_row_format = dynamic
max_allowed_packet = 256M
bind-address = 127.0.0.1

bind-address = 127.0.0.1 garde la base invisible depuis Internet. Sur les anciennes versions (XAMPP notamment), ajoutez aussi innodb_file_format = Barracuda et innodb_large_prefix = 1.

Fichiers et transfert

Symptôme Cause Correction
Écran noir à la place de l’inventaire ou du menu Fichiers manquants dans une ressource (transfert coupé) Supprimer la ressource sur le serveur et la renvoyer en entier, ou envoyer le ZIP et l’extraire sur place.
Une ressource démarre mais ne fait rien Dossier en double (loop-framework/loop-framework) Remonter le contenu d’un niveau et supprimer le dossier vide.
« Couldn’t find resource category [xxx] » ensure [Nom] d’un dossier absent Créer le dossier vide dans resources ou retirer la ligne.
« Couldn’t find resource » alors qu’elle est là Majuscules différentes sous Linux, ou dossier mal placé Respecter exactement les noms du ZIP ; la ressource doit être dans resources/ ou une catégorie entre crochets.
Permission denied dans la console Fichiers appartenant à root chown -R vers l’utilisateur du serveur (section droits).
Les .cfg semblent ignorés Fichier posé dans resources/ ou mauvais dossier serveur dans txAdmin Les .cfg vont à côté de resources/ ; vérifier le Server Data Folder dans txAdmin.
Véhicules, maps et sons disparus sans erreur assets.cfg vide ou exec assets.cfg commenté Restaurer le fichier depuis le ZIP et redémarrer complètement.

Serveur, licence et connexion

Symptôme Cause Correction
Joueurs refusés à la connexion, « Version des artefacts FXServer » en échec Artefacts trop anciens pour ESX Télécharger la dernière version recommended et remplacer seulement le contenu de fxserver/, en gardant resources, le cache et les .cfg.
« OneSync » en échec dans loopdoctor OneSync désactivé Le régler sur On dans txAdmin → Paramètres → FXServer.
Véhicules invisibles, tenues par défaut Build du jeu trop bas Garder sv_enforceGameBuild 3570 (minimum attendu : 3095).
« Aucune licence : renseignez loop_license » Convar vide ou restée sur l’exemple Coller la vraie clé dans server.cfg, redémarrer.
Ressources loop-* qui s’arrêtent seules après le démarrage Licence refusée (clé, place occupée, sorties HTTP bloquées) Voir Licence et erreurs ; Réinitialiser le verrou IP après un changement de machine.
« Identifiant Cfx différent » sv_licenseKey changée Remettre la bonne clé Cfx, ou relier la licence au nouvel identifiant.
Personne ne peut se connecter de l’extérieur Port fermé (pare-feu, box) ou ouvert seulement en TCP Ouvrir [PORT_DU_JEU] en TCP et UDP ; vérifier les deux lignes endpoint_add_*.
Aucun menu admin en jeu Aucun rang volta_bootstrap_discord avec votre ID Discord, Discord ouvert avant FiveM, redémarrage, puis /myrank.
« Discord non configuré » en console Token et guilde vides Normal tant que discord.cfg n’est pas rempli : le serveur tourne sans Discord.

Avant de demander de l’aide

Tapez loopdoctor dans la console et copiez le rapport sans vos clés : il ne les affiche pas, mais relisez avant d’envoyer. Ne joignez jamais vos fichiers .cfg remplis à un ticket : envoyez seulement les lignes utiles, crochets à la place des valeurs, comme sur cette page.

Pour aller plus loin

LOOP Studios · documentation générée depuis le serveur loop_dev le 22/10/2026 · accueil · Raccourci : Ctrl K