Ce guide couvre le dépannage avancé des mods pour les serveurs Project Zomboid hébergés chez Legion Hosting. Si vous n'avez pas encore installé de mods, commencez par le guide d'installation de base des mods. Cet article traite des problèmes les plus courants liés aux mods rencontrés dans les tickets de support Legion Hosting, notamment la corruption du WorldDictionary, les erreurs de format de mod, les conflits d'ordre de chargement et les incompatibilités de version entre serveur et client.

Avant de commencer

• Connectez-vous à GPanel et sélectionnez votre serveur Project Zomboid.
• Arrêtez votre serveur avant d'effectuer toute modification de configuration ou de fichiers.
• Sauvegardez le dossier de votre monde (/.cache/saves/multiplayer/) via SFTP ou GPanel avant de tenter toute correction. Consultez le guide SFTP si vous n'êtes pas familier avec les transferts de fichiers.
• Ayez le chemin du fichier .ini de votre serveur à portée de main : /.cache/server/<servername>.ini (ex. : servertest.ini).

1. Erreurs de format de mod (B42 vs B41)

La raison la plus courante pour laquelle les mods ne se chargent pas est un format incorrect dans la ligne Mods= du fichier .ini de votre serveur. Build 42 et Build 41 utilisent une syntaxe différente, et les mélanger empêchera silencieusement le chargement de vos mods.

Format B42 (par défaut actuel)

Build 42 nécessite un préfixe antislash avant chaque Mod ID dans la ligne Mods= :

Mods=\ModID1;\ModID2;\ModID3;

Le format DLMP combine les Workshop ID et les Mod ID avec un séparateur antislash :

Mods=2392987841\ModID1;1550458773\ModID2;2786383654\ModID3;

La ligne WorkshopItems= utilise le même format séparé par des points-virgules sur les deux builds :

WorkshopItems=2392987841;1550458773;2786383654

Format B41 (ancien)

Build 41 utilise des Mod ID séparés par des points-virgules simples sans antislash :

Mods=ModID1;ModID2;ModID3

Comment corriger

1. Ouvrez /.cache/server/<servername>.ini dans le gestionnaire de fichiers de GPanel.
2. Trouvez la ligne Mods= et vérifiez le format par rapport aux exemples ci-dessus.
3. Si le format est incorrect pour votre version de build, corrigez-le. Utilisez le Legion Hosting Mod Organizer pour générer automatiquement des lignes correctement formatées.
4. Enregistrez le fichier et démarrez le serveur.

2. Corruption du WorldDictionary

Le WorldDictionary est un fichier (WorldDictionary.bin) qui associe les noms d'objets à des ID numériques internes. Lorsque des mods sont ajoutés ou supprimés, le dictionnaire peut se corrompre, provoquant un plantage du serveur au démarrage avec une WorldDictionaryException.

Symptômes

• La console ou le debug.log affiche des erreurs WorldDictionaryException ou WorldDictionary.
• Le serveur plante immédiatement au démarrage, spécifiquement pendant le chargement du monde.
• Le plantage a commencé après l'ajout, la suppression ou la mise à jour de mods.

Comprendre le risque

Étapes de récupération

1. Arrêtez votre serveur dans GPanel.
2. Sauvegardez l'intégralité de votre dossier de monde via SFTP : téléchargez le répertoire complet /.cache/saves/multiplayer/<YourWorldName>/ sur votre machine locale.
3. D'abord, essayez simplement d'annuler la modification de mod qui a causé l'erreur. Si vous venez d'ajouter un mod, supprimez-le de Mods= et de WorkshopItems= dans le fichier .ini. Si vous venez de supprimer un mod, rajoutez-le. Démarrez le serveur et vérifiez si le plantage est résolu.
4. Si l'annulation de la modification de mod ne fonctionne pas, connectez-vous via SFTP et naviguez vers /.cache/saves/multiplayer/<YourWorldName>/.
5. Supprimez WorldDictionary.bin.
6. Démarrez le serveur. Project Zomboid régénérera le dictionnaire au démarrage.
7. Rejoignez le serveur et inspectez le monde pour détecter des objets corrompus, des véhicules manquants ou des inventaires cassés. Si le monde est gravement endommagé, restaurez à partir de la sauvegarde créée à l'étape 2.

3. Conflits du mod Authentic Z

Authentic Z est l'une des collections de mods Project Zomboid les plus populaires, mais c'est une source fréquente de tickets de support car elle contient plusieurs sous-mods qui entrent en conflit les uns avec les autres.

La règle

Erreurs courantes

• Ajouter à la fois Authentic Z - Current et Authentic Z - Litemode en même temps.
• Ajouter des sous-mods Authentic Z conçus pour le solo en plus de la version multijoueur.
• Ne pas réaliser que différents sous-mods Authentic Z partagent le même Workshop ID mais ont des Mod ID différents, donc le téléchargement Workshop réussit mais le serveur charge des fichiers de mods conflictuels.

Comment corriger

1. Ouvrez /.cache/server/<servername>.ini dans le gestionnaire de fichiers de GPanel.
2. Recherchez dans la ligne Mods= toute entrée contenant Authentic ou AuthenticZ.
3. Ne gardez qu'un seul sous-mod Authentic Z (recommandé : Authentic Z - Current). Supprimez toutes les autres entrées Authentic Z des lignes Mods= et WorkshopItems=.
4. Enregistrez le fichier et redémarrez le serveur.

4. Problèmes de sensibilité à la casse sous Linux

Les serveurs Legion Hosting fonctionnent sous Linux, où les noms de fichiers et de dossiers sont sensibles à la casse. Un fichier nommé MyMod.lua et mymod.lua sont traités comme deux fichiers complètement différents. Cela pose des problèmes lorsque les auteurs de mods développent sous Windows (insensible à la casse) et que leurs mods contiennent des références de fichiers mal orthographiées.

Symptômes

• Un mod fonctionne parfaitement en solo sur votre PC Windows mais échoue sur le serveur.
• La console ou le debug.log affiche des erreurs FileNotFoundException ou can't find file faisant référence à un script Lua ou une texture dans un mod.
• L'erreur pointe vers un fichier qui existe bien dans le dossier du mod, mais avec une casse différente (ex. : le code fait référence à Items.txt mais le fichier réel s'appelle items.txt).

Comment diagnostiquer

1. Vérifiez la console ou les fichiers de log dans /.cache/Logs/ pour le chemin exact du fichier mentionné dans l'erreur.
2. Connectez-vous via SFTP et naviguez vers le dossier du mod à /steamapps/workshop/content/108600/<WorkshopID>/.
3. Comparez les noms de fichiers sur le disque avec le nom de fichier référencé dans le message d'erreur. Recherchez les différences de casse.

Comment corriger

• Si vous pouvez renommer le fichier : Connectez-vous via SFTP et renommez le fichier pour correspondre à la casse attendue par le code du mod. Notez que cette correction sera écrasée si le mod se met à jour sur le Steam Workshop.
• Si le problème vient du mod lui-même : Signalez le bug à l'auteur du mod sur la page Steam Workshop. Mentionnez que la référence de fichier a une incohérence de casse et que cela échoue sur les serveurs Linux. Beaucoup d'auteurs de mods ne sont pas conscients de la sensibilité à la casse sous Linux.
• En solution de contournement : Consultez les commentaires de la page Workshop du mod — d'autres opérateurs de serveurs Linux peuvent avoir publié une correction ou un fork compatible du mod.

5. Problèmes d'ordre de chargement des mods

Project Zomboid charge les mods dans l'ordre où ils apparaissent dans la ligne Mods=. Certains mods dépendent d'autres mods qui doivent être chargés en premier. Si une dépendance est chargée après le mod qui en a besoin, le mod dépendant peut échouer silencieusement ou provoquer des erreurs.

Symptômes

• Les fonctionnalités du mod fonctionnent partiellement — certains objets ou systèmes d'un mod sont présents mais d'autres manquent.
• La console affiche des erreurs NullPointerException ou attempt to index a nil value faisant référence aux scripts Lua d'un mod.
• Les erreurs n'apparaissent que lorsqu'une combinaison spécifique de mods est installée, mais chaque mod fonctionne correctement individuellement.

Comment corriger

1. Vérifiez la page Steam Workshop de chaque mod pour une section « Required Mods » ou « Load Order ». De nombreux auteurs de mods précisent quels mods doivent être chargés avant le leur.
2. Ouvrez /.cache/server/<servername>.ini et trouvez la ligne Mods=.
3. Réorganisez les entrées pour que les mods de dépendance apparaissent avant les mods qui en ont besoin. Par exemple, si le Mod B nécessite le Mod A, la ligne devrait être Mods=\ModA;\ModB; (format B42).
4. Les mods de framework et de bibliothèque (tels que ModFramework, TsarLib ou Shark's Mod Utils) doivent toujours être listés en premier dans la ligne Mods=.
5. Enregistrez le fichier et redémarrez le serveur.

6. Plantages du serveur après l'ajout de mods

Si votre serveur fonctionnait correctement et plante après l'ajout d'un ou plusieurs mods, le nouveau mod est probablement la cause. Cette section vous guide pour isoler le mod problématique.

Isolation étape par étape

1. Arrêtez le serveur dans GPanel.
2. Ouvrez /.cache/server/<servername>.ini dans le gestionnaire de fichiers.
3. Notez tous les mods que vous venez d'ajouter. Supprimez-les tous des lignes Mods= et WorkshopItems=.
4. Démarrez le serveur. S'il démarre avec succès, le problème vient de l'un des mods que vous avez supprimés.
5. Rajoutez les mods un par un, en redémarrant le serveur après chaque ajout. Lorsque le plantage revient, le dernier mod ajouté est la cause.
6. Une fois identifié, vérifiez la page Workshop du mod pour :
   • Une note sur la compatibilité B42 — de nombreux mods B41 n'ont pas été mis à jour pour B42.
   • Des conflits connus avec d'autres mods que vous utilisez.
   • Des mods de dépendance requis que vous n'avez peut-être pas installés.

Lire le journal de plantage

Avant d'effectuer le processus d'isolation, consultez le journal de plantage — il pointe souvent directement vers le mod problématique :

1. Dans GPanel, ouvrez l'onglet Console et faites défiler jusqu'à la fin de la sortie.
2. Recherchez les lignes STACK TRACE, Exception ou ERROR.
3. Les lignes juste au-dessus de la trace de pile font généralement référence à un nom de fichier ou un Mod ID — cela vous indique quel mod a déclenché le plantage.
4. Pour plus de détails, ouvrez le fichier de log complet via SFTP à /.cache/Logs/ et consultez le fichier DebugLog-server.txt ou debug.log le plus récent.

7. Incompatibilités de version des mods (serveur vs client)

Project Zomboid nécessite que le serveur et tous les clients connectés aient la même version de chaque mod. Si un mod se met à jour sur le Steam Workshop et que le serveur télécharge la nouvelle version mais qu'un joueur a encore l'ancienne version en cache (ou vice versa), des échecs de connexion ou des plantages surviendront.

Symptômes

• Les joueurs obtiennent une erreur « Mod mismatch » ou « Version mismatch » en essayant de se connecter.
• Certains joueurs peuvent se connecter mais pas d'autres — ceux qui ne peuvent pas se connecter ont une version de mod différente en cache local.
• Le serveur fonctionnait bien, puis un mod s'est mis à jour sur le Steam Workshop et soudainement certains joueurs ne peuvent plus rejoindre.
• Les joueurs voient des textures manquantes, des objets ou des éléments d'interface cassés provenant de mods récemment mis à jour.

Correction pour les opérateurs de serveur

1. Arrêtez le serveur dans GPanel.
2. Redémarrez le serveur. Au démarrage, le serveur re-télécharge les dernières versions de tous les mods Workshop. Cela garantit que le serveur exécute la version la plus récente.
3. Si le serveur a toujours une ancienne version en cache, connectez-vous via SFTP et supprimez le dossier de cache Workshop du mod spécifique à /steamapps/workshop/content/108600/<WorkshopID>/. Redémarrez le serveur pour forcer un téléchargement propre.

Correction pour les joueurs

Les joueurs qui ne peuvent pas se connecter en raison d'incompatibilités de version de mods doivent :

1. Ouvrir Steam et naviguer vers Library → Project Zomboid.
2. Faire un clic droit sur Project Zomboid, sélectionner Properties → Local Files → Verify Integrity of Game Files.
3. Naviguer également vers le dossier Steam Workshop de Project Zomboid sur leur machine locale et supprimer les fichiers de mods en cache pour forcer un re-téléchargement.
4. Lancer le jeu et se reconnecter au serveur.

8. Vider le cache Steam Workshop

Si plusieurs problèmes de mods persistent et que vous suspectez que le cache de téléchargement Workshop est corrompu, vous pouvez forcer un re-téléchargement complet de tous les mods Workshop.

1. Arrêtez le serveur dans GPanel.
2. Connectez-vous via SFTP et naviguez vers /steamapps/workshop/.
3. Supprimez l'intégralité du dossier workshop/ (ou son contenu).
4. Démarrez le serveur. Steam re-téléchargera tous les éléments Workshop depuis zéro.
5. Surveillez la console GPanel pour confirmer que tous les mods ont fini de se télécharger avant que le serveur commence le chargement du monde.

Référence de diagnostic rapide

Vous avez encore des problèmes de mods ?