Compatibilité des mods Hytale après le Chapitre I

Le Chapitre I, « Out of the Breach », est arrivé le 12 octobre 2026 avec l'Update 7, et beaucoup d'administrateurs ont découvert le même problème au redémarrage : un serveur qui refuse de démarrer, ou des mods qui ne se chargent plus. Ce guide ne revient pas sur l'installation des mods : il vous donne une méthode de diagnostic, du premier message d'erreur jusqu'à la réparation, en protégeant votre monde à chaque étape.

Pourquoi le Chapitre I casse certains mods

L'Update 7 n'est pas une simple mise à jour de contenu. Elle touche trois couches dont dépendent les mods :

Le protocole réseau a changé de version. Le client et le serveur doivent être sur la même version : un serveur resté en Update 6 refuse les joueurs à jour, et inversement. Aucun mod ne contourne cette règle.
L'API du serveur a été largement remaniée. Les notes destinées aux développeurs citent par exemple TickProcedure.onTick, dont la signature a changé, WorldChunk, qui ne contient plus de World, ou DurabilityOperator, renommé ComparisonOperator. Un mod Java (fichier .jar) compilé pour l'Update 6 qui utilise ces éléments peut refuser de se charger ou planter en cours de partie.
Les assets du jeu ont évolué. Les notes de pré-version de l'Update 7 signalent des clés renommées (ChargeAcceleration devient ChargeAccelerationDistance), des champs de planeur déplacés vers Template_Glider, des identifiants qui ne se résolvent plus (Spectre_Void) et même des fichiers PNG renommés, comme Spiwer_Web_Full.png devenu Spider_Web_Full.png. Un pack qui pointe vers un élément disparu peut échouer à la validation.

Autre point important : le format de sauvegarde a changé. Un monde est converti automatiquement au premier chargement par un serveur en Chapitre I, et un monde converti ne peut plus être ouvert par une version plus ancienne. La conversion est donc à sens unique.

Avant toute manipulation : sauvegarder

Arrêtez le serveur, puis copiez au minimum :

le dossier universe/ (vos mondes) ;
le dossier mods/ au complet, avec les dossiers de configuration des mods ;
les fichiers config.json, permissions.json, whitelist.json et bans.json.

Notez aussi la liste exacte de vos mods avec leur version. Cette liste vous servira à comparer avec les pages des auteurs. Si vous avez déjà démarré en Chapitre I, gardez quand même une copie de l'état actuel avant de modifier quoi que ce soit : ne relancez pas le serveur en boucle en espérant que l'erreur disparaisse.

Étape 1 : lire les journaux au bon endroit

La console et les journaux disent presque toujours quel mod pose problème. Encore faut-il regarder au bon endroit :

Situation	Où chercher
Serveur dédié ou hébergé	La console du panneau, puis le dossier `logs/` du serveur (un fichier par démarrage, nommé par date et heure)
Monde solo ou partagé depuis le jeu	`UserData/Saves/<monde>/logs`
Problème côté client (jeu)	`UserData/logs`

Ouvrez le journal du dernier démarrage et remontez jusqu'à la première erreur. Les suivantes ne sont souvent que des conséquences. Cherchez les mots Error, Exception, Failed, ainsi que le nom de chacun de vos mods. Sur un système Linux, une simple commande suffit pour filtrer :

grep -inE "error|exception|failed" logs/*.log | head -n 40

Sous Windows, PowerShell fait la même chose :

Select-String -Path .\logs\*.log -Pattern "error","exception","failed" | Select-Object -First 40

Un message comme Failed to load manifest file! désigne un mod dont le fichier manifest.json est absent, mal placé ou illisible. Une trace Java qui mentionne une classe ou une méthode introuvable (par exemple NoSuchMethodError) signale presque toujours un mod Java compilé pour l'ancienne API.

Étape 2 : trier le type d'erreur

Une fois la ligne fautive trouvée, classez-la. Le remède dépend de la catégorie.

Symptôme	Cause probable	Action
Le serveur s'arrête au démarrage en citant un mod	Mod Java incompatible avec la nouvelle API	Installer la version Chapitre I du mod, ou le retirer temporairement
Erreur de validation d'un asset (clé inconnue, identifiant introuvable)	Pack qui référence un élément renommé ou supprimé	Attendre ou installer la mise à jour du pack
Le mod se charge mais un effet ne marche plus	Clé renommée qui ne déclenche qu'un avertissement	Signaler à l'auteur, vérifier les avertissements du journal
Mod ignoré pour cause de dépendance	Dépendance absente ou dans une version trop ancienne	Installer ou mettre à jour la dépendance
Comportements bizarres, doublons d'objets	Deux versions du même mod dans `mods/`	Ne garder qu'un seul fichier
Les joueurs ne peuvent pas se connecter	Versions client et serveur différentes	Aligner la version et le canal de mise à jour (patchline)

Étape 3 : éliminer les doublons

C'est la cause la plus banale et la plus souvent oubliée. En mettant à jour un mod, on dépose le nouveau fichier sans supprimer l'ancien, et le dossier mods/ contient alors deux versions du même mod. Listez le dossier et cherchez les noms proches :

ls -1 mods/ | sort

Si vous voyez par exemple MonMod-1.4.2.jar et MonMod-1.5.0.jar, gardez uniquement la version prévue pour le Chapitre I. Pensez aussi aux mods livrés à la fois en pack .zip et en dossier décompressé : un seul des deux doit rester.

Étape 4 : vérifier les dépendances

Chaque mod déclare ses besoins dans son manifest.json, à la racine du fichier .jar, du .zip ou du dossier du pack. Deux champs nous intéressent :

Dependencies : les mods obligatoires, sous la forme Groupe:Nom avec une plage de versions. Si l'un manque ou ne respecte pas la plage, le mod ne se charge pas.
OptionalDependencies : les mods facultatifs. Leur absence n'empêche pas le chargement.

{
  "Group": "Exemple",
  "Name": "MonMod",
  "Version": "1.5.0",
  "ServerVersion": "...",
  "Dependencies": {
    "Exemple:LibCommune": ">=2.0.0"
  },
  "OptionalDependencies": {}
}

Le piège classique après une grosse mise à jour : le mod principal a sa version Chapitre I, mais pas encore sa bibliothèque. Dans ce cas, le mod principal ne vous sert à rien tant que la dépendance n'est pas à jour. Sur les pages de téléchargement, l'onglet des relations indique quelles dépendances sont obligatoires. Le champ ServerVersion, quand il est renseigné, dit aussi pour quelle version du serveur le mod a été publié : comparez-le avec le résultat de la commande /version.

Étape 5 : retirer temporairement le mod fautif

Si aucune version compatible n'existe, il faut décider. Deux cas très différents :

Le mod n'ajoute ni bloc ni objet

Interface, minicarte, commandes d'administration, outils de gestion : vous pouvez le retirer sans risque. Arrêtez le serveur, déplacez le fichier dans un dossier à part (par exemple mods-desactives/) plutôt que de le supprimer, puis relancez. Vous pouvez aussi le désactiver dans la section Mods du config.json du serveur, toujours serveur arrêté : le serveur réécrit ses fichiers de configuration pendant qu'il tourne, et une modification faite à chaud peut être perdue.

Le mod ajoute des blocs, des objets ou des créatures

Là, prudence. Si vous le retirez, les blocs qu'il a posés risquent d'apparaître comme inconnus ou de disparaître, et les objets concernés peuvent être perdus dans les inventaires. Chaque monde garde aussi dans sa propre configuration la liste des mods dont il a besoin : si l'un d'eux manque, le monde peut refuser de se charger. Testez donc toujours le retrait sur une copie du monde avant de toucher au monde principal. Souvent, la meilleure option est de laisser le serveur à l'arrêt, ou d'ouvrir un monde temporaire, en attendant la mise à jour du mod.

Pour identifier rapidement le mod fautif parmi une longue liste, la méthode par moitiés est la plus rapide : retirez la moitié des mods, relancez, et recommencez avec la moitié qui contient l'erreur. Avec 30 mods, cinq redémarrages suffisent pour isoler le coupable. La documentation communautaire mentionne aussi une option de démarrage, --ignore-broken-mods, qui laisse le serveur démarrer malgré un mod en erreur afin de l'identifier ; vérifiez sa disponibilité sur votre version avec --help avant de vous y fier, et ne l'utilisez jamais sur votre monde principal sans sauvegarde.

Étape 6 : attendre (et suivre) la mise à jour du mod

Pour les mods Java, la correction vient presque toujours de l'auteur : il doit recompiler son mod pour la nouvelle API. Quelques réflexes :

vérifiez la page de chaque mod et cherchez explicitement une mention « Chapter 1 » ou « Update 7 » dans le journal des versions ;
le navigateur de mods intégré au jeu permet de voir d'un coup d'œil quels mods de votre bibliothèque ont reçu une mise à jour ;
ne téléchargez pas de « version corrigée » publiée par un inconnu : un fichier .jar exécute du code sur votre serveur ;
si un mod est abandonné, cherchez une alternative maintenue plutôt que de garder une version cassée.

Tableau de compatibilité par type de mod

Tous les mods ne sont pas exposés au même risque après le Chapitre I. Ce tableau vous aide à prioriser vos vérifications :

Type de mod	Risque après l'Update 7	Ce qu'il faut vérifier
Pack purement visuel (textures, sons)	Faible	Fichiers renommés dans le jeu de base
Pack de contenu (blocs, objets, PNJ, planeurs)	Moyen	Clés et identifiants renommés ou supprimés
Mod Java de serveur (`.jar`)	Élevé	Version compilée pour le Chapitre I
Bibliothèque partagée par d'autres mods	Élevé	Version à jour avant tous les mods qui en dépendent
Mod qui génère des structures ou des mondes	Moyen à élevé	Test sur une copie du monde, compatibilité avec le nouveau format de sauvegarde

Bonne nouvelle au passage : l'Update 7 permet désormais à un mod de contenir des mondes entiers, et un monde créé à partir d'un mod survit au retrait de ce mod.

Les erreurs qui ne viennent pas des mods

Avant d'accuser vos mods, écartez ces causes, elles aussi liées au Chapitre I :

Code de sortie 11 sur un serveur installé soi-même : les données du serveur se trouvent dans le dossier d'installation du lanceur. Déplacez le serveur dans son propre dossier.
Avertissement sur MaxViewRadius : la distance de vue est désormais plafonnée à 32 chunks. Le serveur démarre quand même, mais corrigez la valeur dans config.json.
Joueurs refusés : client et serveur ne sont pas sur la même version ou le même canal de mise à jour.

Check-list rapide

Arrêter le serveur et sauvegarder universe/, mods/ et les fichiers de configuration.
Lire la première erreur du dernier journal.
Supprimer les doublons dans mods/.
Mettre à jour les dépendances avant les mods qui les utilisent.
Retirer temporairement les mods sans version Chapitre I, en testant d'abord sur une copie pour ceux qui ajoutent des blocs.
Redémarrer, vérifier que le serveur atteint l'état « en ligne », puis tester avec un seul joueur avant d'ouvrir à tout le monde.

FAQ

Puis-je revenir à l'Update 6 si mes mods ne marchent plus ?

Seulement avec une sauvegarde faite avant la mise à jour. Un monde ouvert par un serveur en Chapitre I est converti et ne peut plus être lu par une version plus ancienne.

Mon mod est à jour mais le serveur ne démarre toujours pas : pourquoi ?

Vérifiez ses dépendances et la présence d'une ancienne copie du même mod dans mods/. Une bibliothèque restée en version Update 6 suffit à bloquer le chargement.

Les packs de textures sont-ils concernés ?

Rarement, mais quelques fichiers du jeu de base ont été renommés. Si un pack visuel remplace un fichier qui a changé de nom, son remplacement ne s'appliquera plus.

Combien de temps attendre la mise à jour d'un mod ?

Cela dépend entièrement de son auteur, et aucun délai n'est garanti. Suivez sa page ou son journal des versions ; si le mod ne montre aucune activité, préparez une alternative.