Ressources, ConVars et réglages AMP

Ton serveur tourne, tu as un framework. Maintenant tu vas ajouter des scripts, des voitures, des MLO, et régler ce que les joueurs voient dans la liste des serveurs. Ce chapitre t'explique ce qu'est une ressource, comment FXServer la lit, et comment les réglages d'AMP deviennent server.cfg.

Rappel : sur TeamKit, server-data/server.cfg est regénéré à chaque démarrage depuis la page Configuration d'AMP. Tu ne l'édites jamais à la main.

1. Anatomie d'une ressource #

Une ressource est un dossier dans server-data/resources/ qui contient un fxmanifest.lua. Sans ce fichier, FXServer ignore le dossier. Chaque ressource se démarre, s'arrête et se redémarre seule.

Référence officielle : https://docs.fivem.net/docs/scripting-reference/resource-manifest/

Le fxmanifest.lua, clé par clé #

fx_version 'cerulean'      -- version du manifeste ; 'cerulean' est la version actuelle
game 'gta5'                -- 'gta5' pour FiveM, 'rdr3' pour RedM, 'common' pour les deux

author 'Toi'
description 'Ce que fait la ressource'
version '1.0.0'

shared_scripts { 'config.lua' }            -- chargé côté client ET serveur
client_scripts { 'client/*.lua' }          -- côté joueur (les jokers * et ** sont acceptés)
server_scripts { 'server/*.lua' }          -- côté serveur

files { 'html/index.html', 'html/style.css', 'locales/*.json' }   -- fichiers envoyés au client
ui_page 'html/index.html'                  -- interface NUI (page web affichée dans le jeu)

dependencies { 'ox_lib', 'oxmysql' }       -- ressources qui doivent être démarrées avant

Ce qu'il faut comprendre :

• fx_version : valeurs connues adamant, bodacious, cerulean ; la doc indique cerulean comme version courante. Un vieux script avec __resource.lua au lieu de fxmanifest.lua utilise l'ancien format, déprécié.
• client_script / server_script / shared_script : singulier = une chaîne, pluriel = une liste. Les jokers *.lua et **/*.lua chargent tout ce qui correspond, y compris un fichier de sauvegarde oublié (voir plus bas).
• files : ce que le client télécharge et qui n'est pas un script (HTML, JSON de traduction, images, .meta).
• ui_page : la page HTML de l'interface. Elle doit aussi être dans files.
• dependencies : FXServer refuse de démarrer la ressource si une dépendance ne tourne pas. Accepte aussi des contraintes comme /onesync ou /server:4500.
• provide 'qb-core' : la ressource se déclare remplaçante d'une autre. C'est ce que fait qbx_core pour qb-core. Piège : un exports['qb-core'] ne trouve rien, il faut le vrai nom (chapitre 08).
• data_file 'VEHICLE_METADATA_FILE' 'vehicles.meta' : déclare un fichier de données du jeu. Indispensable pour un pack de voitures addon.
• this_is_a_map : marque la ressource comme une carte. Présent dans la plupart des MLO.

✅ À retenir : une ressource = un dossier + un fxmanifest.lua. Le manifeste dit quoi charger, de quel côté, et après qui.

2. Les dossiers entre crochets #

Dans resources/, un dossier écrit [entre-crochets] n'est pas une ressource : c'est une catégorie. Elle peut contenir des ressources et d'autres catégories. C'est comme ça qu'AMP a installé la base : [system], [managers], [gameplay], [gamemodes], [local], [test].

Référence : https://docs.fivem.net/docs/scripting-manual/introduction/introduction-to-resources/

resources/
├── [system]/            ← ressources de base FiveM (ne pas toucher)
├── [framework]/
│   ├── ox_lib/
│   ├── oxmysql/
│   └── es_extended/     ← ou qb-core, ou qbx_core
├── [scripts]/
│   ├── ps-dispatch/
│   └── PolyZone/
└── [mlo]/
    └── gabz_mrpd/

Deux règles :

1. Nomme tes catégories comme tu veux, mais ne renomme pas le dossier d'une ressource : c'est le nom du ensure et celui des exports.
2. Jamais deux dossiers avec le même nom de ressource, même dans deux catégories. FXServer n'en garde qu'un, sans dire lequel.

La doc montre qu'on peut écrire start [categorie] pour démarrer tout un dossier. Sur TeamKit, évite : l'ordre compte, et un ensure par ressource est le seul moyen de le maîtriser.

✅ À retenir : les crochets rangent, ils ne démarrent rien tout seuls. Un ensure par ressource, dans l'ordre.

3. Starting Resources : l'ordre des ensure #

Configuration → FiveM → Starting Resources = une ligne par ressource. AMP transforme chaque ligne en une ligne de server.cfg. ensure démarre la ressource, ou la redémarre si elle tourne déjà.

Les règles d'ordre apprises sur un vrai serveur (230 ressources, hébergé sur ce même AMP) :

• ox_lib avant tout ce qui l'utilise.
• oxmysql avant le framework.
• le framework (es_extended, qb-core, qbx_core) avant ses scripts.
• PolyZone avant ps-dispatch.
• une ressource de traduction (locale) avant la ressource qu'elle traduit.
• les MLO de type mapdata/props avant les autres MLO du même auteur.

Exemple de tête de liste (Qbox) :

# --- ConVars d'abord (voir section 4) ---
setr ox:locale fr
setr inventory:framework qbx
set qbx:acknowledge true

# --- puis les ensure, dans l'ordre ---
ensure ox_lib
ensure oxmysql
ensure qbx_core
ensure ox_inventory
ensure ox_target
ensure PolyZone
ensure ps-dispatch

Quand une dépendance manque, la console dit Could not start resource X et souvent dependency Y is not running. Remonte Y au-dessus de X.

✅ À retenir : bibliothèques → base de données → framework → scripts → MLO. Si ça casse, remonte la dépendance.

4. set, setr, sets : les ConVars #

Un ConVar (console variable) est une valeur nommée que le serveur garde en mémoire et que les scripts lisent. Trois commandes la posent, et la différence est qui peut la lire :

Référence : https://docs.fivem.net/docs/server-manual/server-commands/

Règle simple : un mot de passe ne va jamais dans un setr ou un sets. La chaîne de connexion MySQL se met avec set.

Piège : les ConVars en tête de Starting Resources #

AMP écrit le contenu de Additional Server Settings dans server.cfg après les lignes ensure. Une ressource qui lit une convar à son démarrage (ox_inventory, la locale d'ox_lib, illenium-appearance…) la lit donc trop tôt : elle est encore vide.

Solution : Starting Resources accepte n'importe quelle ligne de server.cfg, pas seulement des ensure. Mets tes set/setr en tête de Starting Resources, avant le premier ensure. Garde Additional Server Settings pour ce qui peut arriver en dernier (chaîne MySQL, sets de présentation).

Piège : redémarrer l'instance après Configuration #

server.cfg est regénéré au démarrage. Tant que tu n'as pas fait Status → Restart, tes modifications de Configuration ne sont pas dans le fichier. Un refresh en console ne suffit pas.

Procédure après chaque modification de Configuration :

1. Clique sur Save en bas de la page Configuration.
2. Clique sur Restart dans Status.
3. Lis la console pendant le démarrage : les erreurs apparaissent dans les 30 premières secondes.

Pièges : sauvegardes et manifeste #

• Jamais de fichier .bak ou .old dans un dossier de ressource. Un manifeste avec server/** charge server/main.lua.bak comme un script. Résultat : chaque événement est enregistré deux fois, et tu récoltes des erreurs du type attempt to compare string with number. Range tes sauvegardes dans un dossier hors de resources/, par exemple server-data/sauvegardes/.
• Après avoir modifié un fxmanifest.lua, tape refresh puis restart <ressource> dans la console AMP. Un restart seul ne relit pas le manifeste.

✅ À retenir : set privé, setr partagé avec le joueur, sets public. ConVars en tête de Starting Resources. Restart de l'instance après Configuration.

5. Le game build #

Le build est la version du jeu que le serveur impose aux joueurs. Chaque build inclut tout le contenu des builds précédents : véhicules, armes, vêtements, intérieurs des DLC de GTA Online.

Référence (tableau complet des builds) : https://docs.fivem.net/docs/server-manual/server-commands/#sv_enforcegamebuild-build

Dans AMP : Configuration → FiveM → Enforce Game Build. Défaut 1604. Choix proposés : 1, 1604, 2060, 2189, 2372, 2545, 2612, 2699, 2802, 2944, 3095, 3258, 3407, 3570, 3751. AMP écrit sv_enforceGameBuild <build> dans server.cfg ; ce réglage ne se change qu'au démarrage, jamais en cours de partie.

Quelques repères tirés du tableau officiel :

Comment choisir :

1. Lis le build minimum demandé par tes scripts et packs (la page du script le dit).
2. Prends le build le plus récent que tous acceptent. Un build plus ancien fait disparaître les véhicules et intérieurs des DLC suivants : c'est la cause de l'avertissement Could not find gameName value in vehicles.meta for vehicle model X de qbx_core.
3. Ne change pas de build la veille d'une ouverture : teste d'abord tes MLO et vêtements avec le nouveau build.

✅ À retenir : le build fixe le contenu du jeu. Plus récent = plus de DLC. Choisis-le une fois, tôt, en fonction de tes scripts.

6. OneSync et les joueurs #

OneSync est le mode de synchronisation où le serveur connaît l'état des entités (joueurs, véhicules, PNJ). Sans lui, le serveur ne fait que relayer.

Références : https://docs.fivem.net/docs/scripting-reference/onesync/ et https://docs.fivem.net/docs/server-manual/server-commands/

Ce que dit la doc sur sv_maxclients : à partir de 32 joueurs, onesync doit être on ou legacy ; au-delà de 64, il doit être on. OneSync est gratuit jusqu'à 48 places ; au-delà, un palier payant du Cfx Portal est nécessaire.

Dans AMP, section FiveM :

• Player Limit : défaut 32. Au-delà, OneSync obligatoire.
• OneSync Mode : Off / On / Legacy. Prends On : ESX Legacy, QBCore et Qbox l'attendent. Legacy est un mode de compatibilité que la doc ne recommande pas.
• Enable OneSync Population (onesync_population) : active les PNJ et la circulation. Coupe-le seulement pour une ville vide.
• Vehicle Distance Culling (onesync_distanceCullVehicles) : filtre les véhicules par distance comme les autres entités. Désactivé par défaut ; peut soulager un serveur chargé.
• Forced Migration (onesync_forceMigration) : quand le joueur qui « possède » une entité part, le serveur la confie à un autre. Laisse activé.
• OneSync Workaround : contournement historique. Laisse la valeur par défaut d'AMP sauf consigne d'un script.

✅ À retenir : OneSync On, Population activée, le reste par défaut. Player Limit ≤ 48 sur TeamKit tant que tu n'as pas de palier Cfx.

7. Bloquer les fichiers modifiés : sv_pureLevel #

Configuration → FiveM → Block Modified Client Files écrit sv_pureLevel.

Référence : https://docs.fivem.net/docs/server-manual/server-commands/#sv_purelevel-level

• Rien : tout est accepté.
• sv_pureLevel 1 : bloque les fichiers clients modifiés sauf les fichiers audio et les mods graphiques connus. C'est le bon compromis : la plupart des triches sont bloquées, les packs graphiques passent.
• sv_pureLevel 2 : bloque tout, mods graphiques compris.

Ce qu'il faut prévenir aux joueurs : au premier changement de niveau, chacun doit redémarrer son jeu. Un joueur qui a modifié des fichiers du jeu de base reçoit un message qui nomme le fichier fautif (voir chapitre 08, « Modified client files »).

À côté, Allow Scripthook Plugins (sv_scriptHookAllowed) : laisse sur non. La doc le déconseille, ça ouvre la porte aux menus de triche.

✅ À retenir : niveau 1 pour un serveur public, et préviens que le jeu doit être relancé.

8. Apparaître dans la liste des serveurs #

Tout se règle dans Configuration → FiveM. Voici ce que chaque champ devient dans server.cfg et pourquoi il compte.

Procédure pour vérifier que tu es listé :

1. Renseigne au minimum la clé Cfx.re, Project Name, Project Description, tags et locale.
2. Redémarre l'instance et lis la console : Server license key authentication failed t'envoie au chapitre 08.
3. Ouvre FiveM, onglet Servers, tape ton Project Name. Compte quelques minutes.
4. Si tu ne te vois pas : la liste favorise l'activité. Connecte-toi avec un ami et regarde à nouveau.

✅ À retenir : clé + nom propre + description + tags + locale. Endpoint Privacy activé. Server Private décoché.

9. MLO et streaming #

Un MLO (intérieur) ou un pack de véhicules ne contient pas de script mais des fichiers du jeu (.ydr, .ytd, .ybn, .ymap, .ytyp, .yft) que le serveur streame aux joueurs. Ils vont dans le dossier stream/ de la ressource ; le manifeste dit au jeu comment les traiter.

Manifeste type d'un MLO :

fx_version 'cerulean'
game 'gta5'
this_is_a_map 'yes'

Manifeste type d'un véhicule addon :

fx_version 'cerulean'
game 'gta5'
files { 'data/vehicles.meta', 'data/handling.meta', 'data/carvariations.meta' }
data_file 'VEHICLE_METADATA_FILE' 'data/vehicles.meta'
data_file 'HANDLING_FILE' 'data/handling.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'

Les clés this_is_a_map et data_file sont décrites sur https://docs.fivem.net/docs/scripting-reference/resource-manifest/. Ne réécris pas un manifeste de MLO fourni par son auteur : dépose le dossier tel quel.

Ce que tu dois surveiller :

• Ordre : un auteur livre souvent une ressource « mapdata » ou « props » commune, puis des MLO qui s'en servent. Les communes passent avant dans Starting Resources.
• Assets lourds : un fichier de plus de ~16 Mo déclenche Oversized assets … WILL lead to streaming issues. Le MLO se charge, mais des textures peuvent manquer chez certains joueurs. Cherche une version optimisée chez l'auteur, ou accepte le défaut.
• Doublons : deux MLO au même endroit = intérieurs qui se chevauchent, textures qui clignotent. Un seul par lieu.
• Disque : 50 Go par serveur chez TeamKit. Regarde la taille dans Status avant d'en ajouter dix.

✅ À retenir : un MLO = dossier stream/ + manifeste de l'auteur. Communs avant dépendants. Un seul MLO par lieu.

10. Performance #

Ton conteneur a 12 Go de RAM et un CPU plafonné. Ce qui coûte, dans l'ordre :

1. Les boucles sans attente. Un script client qui fait while true do ... end sans Wait fige le jeu ; la doc est formelle : https://docs.fivem.net/docs/scripting-reference/runtimes/lua/functions/Citizen.Wait/. Wait(0) tourne à chaque image : réserve-le aux contrôles clavier. Pour tester une distance ou une zone, Wait(500) suffit.
2. Le nombre de ressources. Chaque ressource a un coût fixe, même vide. 230 tiennent sur ce profil, mais supprime ce que tu n'utilises pas plutôt que de le laisser en ensure.
3. Les MLO et packs de véhicules : disque, RAM côté joueur et temps de chargement.

Pour mesurer côté joueur, ouvre la console F8 :

• resmon true (ou resmon 1) : CPU et mémoire par ressource. La ressource en tête est ta suspecte.
• cl_drawperf : FPS, ping, pertes de paquets, charge CPU/GPU.
• netgraph true : bande passante et paquets en temps réel.

Référence : https://docs.fivem.net/docs/client-manual/console-commands/. La doc range resmon et netgraph dans les commandes « développeur » ; si elles n'affichent rien chez toi, vérifie ce point sur cette page.

Côté serveur, Status montre CPU et RAM de l'instance. Une RAM qui monte sans redescendre signale un script qui accumule des données : trouve-le avec resmon, puis signale-le à l'auteur.

✅ À retenir : Wait adapté, moins de ressources, resmon pour désigner le coupable.

✅ Checklist du chapitre #

• Chaque ressource est un dossier avec fxmanifest.lua, dans server-data/resources/ ou une catégorie […].
• Aucun doublon de nom de ressource, aucun .bak dans un dossier de ressource.
• Les set/setr sont en tête de Starting Resources, avant le premier ensure.
• Ordre : ox_lib → oxmysql → framework → scripts → MLO communs → MLO dépendants.
• La chaîne MySQL est en set, jamais en setr ni sets.
• Enforce Game Build choisi selon tes scripts, et pas changé la veille d'une ouverture.
• OneSync On, Population activée, Player Limit ≤ 48.
• Block Modified Client Files sur niveau 1, Allow Scripthook sur non.
• Clé Cfx.re, Project Name propre, description, tags, locale fr-FR/fr-BE, Endpoint Privacy activé, Server Private décoché.
• Après toute modification de Configuration : Save puis Restart de l'instance.

❓ Si ça ne marche pas #

• J'ai ajouté une ressource par SFTP, ensure dit qu'elle n'existe pas. Tape refresh, puis ensure <nom>. Vérifie que fxmanifest.lua est à la racine du dossier, pas dans un sous-dossier issu du zip. Détail au chapitre 08.
• Ma convar est vide au démarrage (langue en anglais, inventaire sans framework). Elle est dans Additional Server Settings, donc écrite trop tard. Déplace-la en tête de Starting Resources et redémarre l'instance.
• J'ai modifié Configuration, rien ne change. Tu n'as pas redémarré l'instance : server.cfg n'est réécrit qu'au démarrage.
• Les véhicules d'un pack n'apparaissent pas, la console parle de vehicles.meta. Modèle d'un DLC plus récent que ton build, ou data_file absent du manifeste. Monte le build ou vérifie le manifeste du pack.
• Le serveur n'apparaît pas dans la liste. Clé Cfx.re absente ou liée à une autre IP, Project Name non conforme, Server Private coché, ou 0 joueur depuis longtemps. Liste complète au chapitre 08.
• Une ressource fait tomber les FPS de tout le monde. resmon true côté client, note la ressource en tête, cherche une boucle Wait(0) dans son code client.