ModDoctor : trouve le mod qui pose problème

Avec beaucoup de mods, il arrive que tout se bloque sans rien dans la console : le jeu se fige, un chargement ne finit jamais, ou des erreurs défilent sans dire quel mod les cause. ModDoctor surveille la partie et nomme le mod responsable, dans la console, dans un rapport et à l'écran.

Il est côté client et n'a besoin de rien chez les autres joueurs.

Ce qu'il détecte

Où lire les résultats

• Console BepInEx : chaque problème sur une ligne (en rouge s'il est grave), puis un résumé une fois les mods chargés.
• En jeu : une petite alerte en haut à gauche pendant 15 s quand un nouveau problème apparaît. F9 ouvre la liste, les plus graves d'abord. F10 masque complètement ModDoctor à l'écran (et le réaffiche) ; le choix est retenu pour les parties suivantes, et la surveillance comme le rapport continuent.
• BepInEx/ModDoctor/rapport.txt : tout le détail, plus la liste des mods chargés et celle des conflits Harmony. rapport-precedent.txt contient la session d'avant.
• BepInEx/ModDoctor/blocage-<date>.txt : un fichier par blocage, écrit pendant que le jeu est figé.

Avec r2modman, le dossier BepInEx est celui du profil (Paramètres → « Browse profile folder »).

Exemple de rapport de blocage

=== BLOCAGE : le jeu ne répond plus depuis 8 s ===
Scène : MainMenu
Suspect principal : BuggyMod › BuggyMod.BuggyBehaviour.FreezeRoutine (coroutine)
Pourquoi : le thread principal est à l'intérieur de cette méthode.

Installation

Avec r2modman / Thunderstore Mod Manager : installer ModDoctor dans le profil qui pose problème. À la main : installer BepInExPack 5.4.2305, puis copier ModDoctor.dll dans BepInEx/plugins/.

Réglages

BepInEx/config/emeric.moddoctor.cfg :

• SecondesAvantAlerte (8) : durée sans image avant de parler de blocage. Un long chargement peut déclencher une fausse alerte ; le rapport indique alors que le jeu est reparti.
• SuivreLesMods (oui) : suit l'exécution des mods pour nommer celui qui bloque (voir plus bas).
• MethodesSuiviesMax (6000), ModsExclus (GUID séparés par des virgules) : à utiliser si le suivi gêne un mod.
• ErreursEnBoucleParSeconde (20) : seuil des erreurs en boucle.
• AlerteEnJeu (mis à jour par F10), ToucheRapport (F9), ToucheMasquer (F10), DureeAlerte (15 s, 0 = jusqu'à ouverture de la liste), ConflitsDansLAlerte.

Testé

• Jeu : build Steam 22825947 (Unity 2022.3.62), BepInEx 5.4.23.5, au menu principal, en LAN.
• Test automatique avec un faux mod volontairement bogué. Vérifié :
  • blocage détecté et écrit pendant que le jeu est figé, avec la bonne coroutine ;
  • reprise après le blocage ;
  • suspect de la session précédente après une fermeture forcée ;
  • exceptions dans un Update et dans un patch Harmony, erreur du journal BepInEx et erreur en boucle, toutes attribuées au bon mod ;
  • mod non chargé (dépendance absente), plantage au démarrage, conflit Harmony ;
  • touches F9 et F10.
• Pas encore testé avec une grosse liste de vrais mods : on ne connaît pas encore le temps de mise en place du suivi, ni le risque de fausses alertes pendant les chargements longs. Pas testé non plus en partie à plusieurs : rien n'est synchronisé, chaque joueur a son propre diagnostic.

Comment ça marche (et limites)

• Suivi des mods : ModDoctor ajoute, avec Harmony, un repère d'entrée et de sortie à certaines méthodes des mods :

  • les messages Unity des MonoBehaviour (Update, LateUpdate, FixedUpdate, OnGUI, Awake, Start, OnEnable, OnDisable, OnDestroy) ;
  • les coroutines ;
  • les méthodes de patch Harmony ;
  • les hooks MonoMod On.* ;
  • les méthodes du jeu réécrites par un transpiler.

  C'est fait par petits lots juste après le chargement, puis à chaque changement de scène. Le coût par appel est très faible, mais pas nul.

• Ce que le suivi ne voit pas : un blocage dans du code de mod appelé autrement, par exemple un événement ou une méthode appelée par une autre méthode du mod. Dans ce cas, le rapport nomme le dernier mod exécuté, souvent le bon. Un blocage dans le code natif du jeu n'est pas attribuable.

• Plugins chargés avant ModDoctor : leurs erreurs de démarrage sont relues dans LogOutput.log. En revanche, un blocage pendant leur chargement n'est pas surveillé. Dans ce cas, la dernière ligne « Loading [...] » de LogOutput.log indique le coupable.

• Lenteurs : un chargement de plus de 8 s sans image (génération d'une lune avec beaucoup de mods, par exemple) est signalé comme blocage, puis comme « reparti ». Augmente SecondesAvantAlerte si ça arrive trop souvent.

• ModDoctor indique un suspect, pas une preuve. Pour confirmer, retire ce mod et relance.

Compiler, tester, empaqueter

1. La référence « publicisée » du jeu est dans lib/Assembly-CSharp.dll (copie de celle de SoundBox, même version du jeu).
2. dotnet build -c Release : produit bin/Release/netstandard2.1/ModDoctor.dll et le copie dans le profil r2modman « ModDoctor » s'il existe.
3. tests/BuggyMod : faux mod volontairement bogué, qui n'est jamais empaqueté (dotnet build -c Release dans ce dossier le copie dans le même profil). Il provoque toutes les pannes ci-dessus.
4. powershell -File autotest.ps1 : premier lancement où BuggyMod fige le jeu pour de bon (le jeu est tué après le rapport de blocage), puis second lancement qui vérifie que chaque panne est reconnue et attribuée au bon mod, ainsi que la détection de la session précédente.
5. powershell -File package.ps1 : produit dist/ModDoctor-<version>.zip.