Installer des MLO et YMAP sur FiveM : comment ajouter une map personnalisée
Ce guide vous accompagne pas à pas pour ajouter une map MLO (un intérieur dans lequel on peut entrer) ou YMAP (un placement en extérieur) à votre serveur FiveM : la bonne structure de dossiers, le contenu de fxmanifest.lua, l'ordre des ensure dans server.cfg et la vérification après installation. Vous apprendrez aussi à corriger les conflits, les chutes à travers le sol et les chargements tardifs, à mesurer l'impact des maps sur les performances, et à comprendre le fonctionnement des maps payantes protégées par escrow.
Avant de commencer
- Une installation FXServer fonctionnelle. Si vous n'en avez pas encore, suivez le guide d'installation d'un serveur FiveM de zéro avec FXServer ; ce guide part du principe que votre dossier
server-dataet votre fichierserver.cfgsont prêts. - Un accès aux fichiers du serveur : sur un VDS Windows, vous vous connectez au bureau en RDP (3389) et copiez les fichiers ; sur un VDS Linux, vous utilisez un client SFTP comme WinSCP ou FileZilla via SSH (22).
- Une clé de licence obtenue sur le portail Cfx.re (portal.cfx.re) et saisie sur la ligne
sv_licenseKeydeserver.cfg. Les maps protégées par escrow sont autorisées via cette clé ; pour plus de détails, consultez le guide pour obtenir une clé de licence. - Les notes de dépendances de l'auteur de la map. Certains MLO ont besoin d'une ressource supplémentaire pour les portes, les ascenseurs ou l'éclairage ; sans elle, l'intérieur s'ouvre mais ne fonctionne pas entièrement.
- Une sauvegarde : une copie de votre fichier
server.cfget de votre dossierresources. Les offres VDS n'incluent pas de sauvegarde automatique ; conservez la copie hors du serveur. - Un serveur adapté. Les joueurs téléchargent les fichiers de la map depuis le serveur lors de leur première connexion ; la vitesse du disque et du réseau du serveur influe sur la durée de ce téléchargement. La famille que nous recommandons pour FiveM est le VDS AMD Ryzen 9 9950X, fourni avec des disques NVMe et une connexion 1 Gbit/s ; les offres se trouvent sur la page Location de serveur FiveM.
1. Comprenez la différence entre MLO et YMAP
Un YMAP est un fichier de placement qui indique où vont des modèles existants (archetypes) sur la map : arbres, barrières, props, et même l'enveloppe extérieure d'un bâtiment se placent avec un YMAP. Un YTYP contient les définitions de ces modèles : nom, distance de LOD (niveau de détail), collisions et données d'intérieur. Un MLO est un type d'archetype particulier, défini dans un YTYP comme CMloArchetypeDef : un intérieur dans lequel on peut entrer, avec des pièces, des portails et ses propres données de collision. Un pack MLO combine donc un YTYP et un YMAP avec des fichiers de modèles, de textures et de collisions.
| Caractéristique | YMAP | MLO |
|---|---|---|
| Rôle | Place des modèles existants sur la map | Définit un intérieur avec des pièces et des portes dans lequel on peut entrer |
| Contenu typique | .ymap (+ parfois .ydr, .ytd) | .ytyp, .ymap, .ydr/.ydd, .ytd, .ybn |
| Charge pour le moteur du jeu | Légère ; augmente avec le nombre de props | Plus lourde ; les données de modèles, de textures et de collisions occupent la mémoire de streaming |
| Exigence du manifeste | this_is_a_map suffit | this_is_a_map ; dans la plupart des packs, également data_file pour le ytyp et un _manifest.ymf |
| Problèmes fréquents | Z-fighting (surfaces superposées qui scintillent), props décalés | Chute à travers le sol, pièces noires, chargement tardif |
2. Téléchargez le pack et vérifiez son contenu
La documentation Cfx.re renvoie vers le Cfx Marketplace et la section « FiveM Releases » du forum pour trouver des ressources ; pour un produit payant, elle recommande de demander au vendeur, avant l'achat, s'il vend via un canal officiel (le Cfx Marketplace ou Tebex). Les packs « leakés » des sites de partage peuvent être d'anciennes versions et contenir des scripts injectés ; si vous voyez un fichier Lua que la description de l'auteur ne mentionne pas, n'utilisez pas le pack.
En extrayant l'archive, vous verrez ces types de fichiers :
| Extension | Contenu | Emplacement |
|---|---|---|
.ydr / .ydd / .yft | Modèle 3D (simple, dictionnaire, fragment) | stream/ |
.ytd | Dictionnaire de textures | stream/ |
.ybn | Limites de collision | stream/ |
.ytyp | Définitions d'archetypes et de MLO | stream/ + déclaré dans le manifeste |
.ymap | Placement | stream/ |
_manifest.ymf | Manifeste généré avec l'outil Manifest Generator de CodeWalker ; selon le guide Cfx.re, il est nécessaire au bon chargement des modèles | stream/ |
fxmanifest.lua | Définition de la ressource | Racine du dossier de la ressource |
Les fichiers .ymap et .ytyp au format XML sont aussi lus sans conversion, à condition de ne pas porter d'extension supplémentaire (non pas mh1_01.ymap.xml mais mh1_01.ymap). Comme c'est l'analyseur du jeu lui-même qui les lit, ils peuvent se comporter différemment de ce que vous voyez dans CodeWalker.
3. Créez le dossier de la ressource et le dossier stream
FXServer lit chaque dossier situé sous resources comme une ressource ; les dossiers entre crochets (comme [maps]) comptent comme des catégories et regroupent les ressources qu'ils contiennent. Dans l'installation d'exemple de Cfx.re, les chemins se présentent ainsi :
Windows: C:\FXServer\server-data\resources\[maps]\my_hospital\stream\
Linux: ~/FXServer/server-data/resources/[maps]/my_hospital/stream/
Si vous avez installé le serveur avec txAdmin à partir d'une recette, utilisez le dossier de données du serveur choisi lors de l'installation à la place de server-data. Les règles :
- Donnez au dossier de la ressource un nom composé de lettres minuscules, de chiffres, de tirets bas et de tirets ; évitez les espaces, les accents et les caractères spéciaux (é, è, à, ç). Ce nom apparaît tel quel sur la ligne
ensure. - Sous Linux, les noms de fichiers sont sensibles à la casse. Si le manifeste indique
stream/Hospital.ytypet que le fichier s'appellehospital.ytyp, le ytyp ne se chargera pas. - Les archives arrivent souvent avec des dossiers imbriqués (
my_hospital/my_hospital/stream). Le fichierfxmanifest.luadoit se trouver directement à la racine du dossier de la ressource, à côté du dossierstream. - Placez tous les fichiers du jeu dans
stream; le guide Cfx.re l'exige pour que les fichiers se chargent correctement.
4. Écrivez le fichier fxmanifest.lua
Si le pack est livré avec un manifeste prêt à l'emploi, conservez-le et vérifiez seulement les chemins. Sinon, utilisez ce modèle :
fx_version 'cerulean'
game 'gta5'
author 'Map Author'
description 'Sandy Shores hospital MLO'
version '1.0.0'
this_is_a_map 'yes'
-- If the pack includes a ytyp:
data_file 'DLC_ITYP_REQUEST' 'stream/my_hospital.ytyp'
fx_version 'cerulean': la version actuelle du manifeste FXv2. Si vous trouvez dans d'anciens packs un fichier__resource.luaet une ligneresource_manifest_version, déplacez le contenu dans un nouveau fichierfxmanifest.luaet remplacez cette ligne obsolète par les lignesfx_versionetgame.game 'gta5': indique que la ressource fonctionne dans FiveM.this_is_a_map 'yes': marque la ressource comme une map ; selon la documentation Cfx.re, le map store est rechargé au chargement de la ressource. La valeur n'a pas d'importance ; la ligne doit simplement être présente.data_file 'DLC_ITYP_REQUEST' '...': enregistre le fichier ytyp comme définition permanente dans le système de contenu supplémentaire du jeu (l'équivalent dePERMANENT_ITYP_FILEdans la documentation). S'il y a plusieurs ytyp, vous pouvez utiliser un joker :data_file 'DLC_ITYP_REQUEST' 'stream/*.ytyp'.- Si le script des portes ou de l'éclairage est une ressource séparée, ajoutez
dependency 'my_hospital'à son manifeste ; cette ligne oblige la ressource nommée à se charger en premier. La lignelua54 'yes'que l'on voit dans certains modèles est obsolète (Lua 5.4 est désormais la valeur par défaut) ; inutile de l'ajouter.
Les packs YMAP purs, qui ne contiennent qu'un .ymap et quelques props, n'ont pas besoin de la ligne data_file ; fx_version, game et this_is_a_map suffisent (author, description et version sont facultatifs).
5. Ajoutez ensure dans server.cfg et définissez l'ordre
ensure démarre une ressource si elle n'est pas lancée et la redémarre si elle l'est, c'est pourquoi on le préfère à start. Il accepte aussi un nom de catégorie :
# Maps
ensure [maps]
# or one by one
ensure my_hospital
ensure my_hospital_doors
L'ordre compte :
- Les maps ne dépendent pas du framework (
es_extended,qb-core, etc.) ; pour garder un fichier ordonné, regroupez-les dans un bloc séparé sous les lignes du framework. - Une ressource qui fournit un ytyp doit démarrer avant le ymap qui utilise ce ytyp. S'ils sont dans le même pack, aucun problème ; pour des packs séparés, fixez l'ordre avec la séquence des
ensureou avecdependency. - Placez après les maps les scripts qui en dépendent, comme les serrures de portes, les ascenseurs et les téléportations ; si un script s'appuie sur une ressource de map, verrouillez l'ordre avec
dependency.
6. Démarrez le serveur et vérifiez en jeu
Dans la console du serveur, faites rechercher le nouveau dossier puis démarrez la ressource :
refresh
ensure my_hospital
Selon la documentation Cfx.re, refresh analyse à nouveau le dossier resources et charge chaque manifeste trouvé ; une ressource que vous venez de copier ne devient visible qu'après cette commande. Si la console indique que la ressource est introuvable ou n'a pas de manifeste, fxmanifest.lua se trouve dans le mauvais dossier ; c'est généralement le problème des dossiers imbriqués. Pour les gros packs, un redémarrage complet donne le résultat le plus propre (si vous utilisez txAdmin, voir l'étape de redémarrage dans le guide txAdmin).
En jeu, rendez-vous à l'emplacement de la map et utilisez ces commandes client dans la console F8 :
strdbg true
strlist true
strdbg affiche ce que le streamer charge à cet instant ; si le monde cesse de se charger, c'est là que vous repérez le fichier en cause. strlist liste les entrées enregistrées auprès du streamer et leur état ; si votre ytyp n'apparaît pas dans la liste, le chemin du manifeste est faux. Une fois terminé, désactivez les commandes avec false.
7. Mesurez l'impact sur les performances
Les ressources de map pures ne contiennent généralement aucun script : resmon (qui affiche l'utilisation du CPU et de la mémoire par ressource) ne reflète donc pas la charge réelle d'un MLO. La charge réelle, c'est la mémoire de streaming sur l'ordinateur du joueur. Dans la console F8 :
strmem true
strmem liste l'utilisation mémoire des éléments streamés, un par un et au total. Lorsque plusieurs gros MLO sont regroupés dans la même zone, les joueurs qui ont peu de mémoire peuvent voir des textures manquantes et des chutes de FPS. Les deux paramètres que vous gérez côté serveur sont la taille des fichiers téléchargés à la première connexion et la capacité des pools. Si des joueurs plantent avec une erreur indiquant qu'un pool est plein (par exemple TxdStore), agrandissez ce pool dans server.cfg ; l'exemple tiré de la documentation Cfx.re :
increase_pool_size "TxdStore" 6000
Le nombre n'est pas le nouveau total mais la quantité à ajouter au pool. La commande n'est lue qu'au démarrage ; redémarrez le serveur après l'avoir modifiée. Pour mesurer et alléger, consultez le guide d'optimisation resmon et FPS.
8. Maps sous licence et protégées par escrow
Cfx.re Asset Escrow est le système qui empêche les autres de modifier ou de lire les fichiers d'un auteur ; il protège les fichiers Lua, YFT, YDD et YDR. Les produits protégés sont vendus uniquement sous forme de packages Tebex ; l'acheteur reçoit un lien de téléchargement par e-mail.
- Pour faire fonctionner la ressource, le propriétaire du serveur doit avoir acheté le produit. Votre serveur est identifié par le compte Cfx.re qui vous a fourni la
sv_licenseKey; si le produit a été acheté depuis un autre compte, la ressource ne démarre pas et la console affiche l'erreur «You lack the required entitlement». - Si vous cédez le serveur à quelqu'un d'autre, le nouveau propriétaire utilise sa propre clé ; si ce compte n'a pas non plus le droit d'utilisation (entitlement), la map ne démarre pas. Renseignez-vous auprès du vendeur sur les conditions de transfert.
- Lorsque l'abonnement d'un produit vendu par abonnement prend fin, le produit est retiré du compte et ne démarre plus sur le serveur.
- Vous ne pouvez pas modifier les fichiers protégés ; seuls les fichiers que l'auteur a laissés hors protection avec
escrow_ignore(par exemple des fichiers de configuration ou certains modèles) sont modifiables. - Les packs vendus comme « escrow cracked » ont été diffusés sans l'autorisation de l'auteur et ne sont pas dignes de confiance ; ne les utilisez pas.
Récapitulatif de la configuration d'exemple
| Réglage | Valeur | Emplacement |
|---|---|---|
| Dossier de la ressource | resources/[maps]/my_hospital | server-data |
| Fichiers du jeu | Sous stream/ | Dossier de la ressource |
fx_version / game | cerulean / gta5 | fxmanifest.lua |
this_is_a_map | yes | fxmanifest.lua |
data_file | DLC_ITYP_REQUEST + chemin du ytyp | fxmanifest.lua |
| Démarrage | ensure my_hospital (avant les scripts dépendants) | server.cfg |
| Agrandissement de pool | increase_pool_size "TxdStore" 6000 | server.cfg |
| Vérification en jeu | strdbg, strlist, strmem | Console F8 |
Erreurs fréquentes
- La map n'apparaît pas du tout. Vérifiez dans cet ordre : la ligne
ensure,refresh, l'avertissement de manifeste dans la console et, sous Linux, la casse des noms de fichiers. - Le joueur tombe à travers le sol. Le fichier de collision (
.ybn) manque ou le ytyp ne s'est pas chargé. Vérifiez avecstrlistque le ybn et le ytyp sont enregistrés ; corrigez le chemin dudata_file. - Deux maps se chevauchent et des surfaces scintillent. Deux packs sont placés aux mêmes coordonnées. Arrêtez temporairement le dernier pack ajouté avec
stop my_hospitalpour trouver celui qui entre en conflit, puis retirez l'un des deux. - Des props flottent ou sont décalés. Le YMAP a été conçu pour une autre modification de map que vous n'avez pas, ou le ytyp dont il dépend ne s'est pas chargé. Vérifiez les notes de dépendances de l'auteur ; démarrez en premier la ressource qui fournit le ytyp.
- L'intérieur est sombre et vide, ou le bâtiment apparaît tardivement de loin. Dans le premier cas, la définition du MLO ne s'est pas chargée ; vérifiez que le ytyp figure dans la liste
strlistet que le fichier_manifest.ymfest présent dans le pack. Dans le second cas, la distance de LOD (lodDist) est faible ou la mémoire de streaming est pleine ; vérifiez avecstrmem. - Les joueurs plantent à la connexion avec une erreur indiquant qu'un pool est plein. Agrandissez ce pool avec
increase_pool_sizeet redémarrez le serveur. - « You lack the required entitlement ». La ressource sous escrow n'est pas enregistrée sur le compte Cfx.re de la clé de votre serveur ; vérifiez la correspondance des comptes décrite à l'étape 8.
- Les textures d'une autre map sont cassées. Deux packs utilisent un dictionnaire de textures (
.ytd) ou un archetype portant le même nom ; celui ajouté en dernier remplace le précédent. Retirez l'un des packs.
Questions fréquentes
Puis-je mettre plusieurs MLO dans une seule ressource ?
Oui ; vous pouvez tous les placer dans le même dossier stream et déclarer les ytyp avec le joker 'stream/*.ytyp'. Toutefois, un seul fichier défectueux affecte alors toute la ressource ; garder chaque MLO dans sa propre ressource et les démarrer avec la catégorie [maps] est plus simple à gérer.
Combien de maps puis-je ajouter ?
Il n'y a pas de limite fixe ; la limite dépend de la mémoire de streaming des joueurs et de la taille du téléchargement à la première connexion. Après chaque nouveau pack, vérifiez l'utilisation totale avec strmem et faites un test avec un joueur équipé d'une configuration modeste. Retirer des lignes ensure les maps inutilisées est l'amélioration la plus simple.
Puis-je utiliser un MLO acheté aussi sur mon second serveur ?
Oui. Selon la documentation Cfx.re, un élément sous escrow téléchargé fonctionne sur tous les serveurs qui vous appartiennent. S'il ne fonctionne pas, la raison la plus courante est que la clé du second serveur a été obtenue depuis un autre compte Cfx.re.
Retirer une map va-t-il abîmer les données sauvegardées des joueurs ?
Une ressource de map n'écrit rien dans la base de données ; supprimer la ligne ensure et retirer le dossier suffit. Pensez seulement à mettre aussi à jour les coordonnées des scripts liés à cet intérieur (commerces, maisons, garages) ; sinon, les joueurs seront téléportés sur un terrain vide.
Guides associés
- Installer FXServer : un serveur FiveM de zéro (Windows et Linux)
- Comment ajouter des véhicules add-on à un serveur FiveM (fxmanifest et stream)
- Optimiser un serveur FiveM : lire resmon et augmenter les FPS
- Utiliser txAdmin : guide de gestion d'un serveur FiveM
- Clé de licence FiveM : enregistrer un serveur sur le portail Cfx.re
Tous les guides FiveM se trouvent dans la catégorie des guides FiveM. Sources officielles : manifeste de ressource Cfx.re, guide Cfx.re des mods de map et documentation Asset Escrow.
Commentaires0
Pas encore de commentaire
Soyez le premier à partager votre avis.
Veuillez vous connecter ou vous inscrire pour laisser un commentaire.