Déboguer les Mixins

Astuce

La section Mixins de Meilleures Pratiques traite des mixins, des coremods et d’autres définitions de bas niveau.

Mixin de SpongePowered est le sous-système qui permet à SpongeAPI et à d’autres programmes de s’interfacer avec Minecraft. Cet article n’a pas pour bbut de fournir une explication complète de Mixin. Veuillez voir le wiki de Mixin pour sa documentation et ses options de support.

Note

Mixin a son propre dépôt que vous pouvez cloner et importer dans IntelliJ pour trouver des messages d’erreur et des problèmes de recherche. Alternativement, vous pouvez spécifier votre clone local du dépôt Mixin en tant que Module dans les paramètres de projet de votre implémentation de Sponge et déboguer Mixin.

Sortie

Par défaut, un dossier nommé .mixin.out est créé dans le dossier run. Le dossier contient un sous-dossier nommé audit avec des rapports vides et des fichiers au format avec des valeurs séparées par des virgules. Ces fichiers sont utilisés si l’option mixin.checks.interfaces est activée.

Cependant, Mixin supporte les Java System Properties pour activer diverses fonctionnalités de débogage et d’audit. Il y a des moments où vous avez besoin ou voulez voir les résultats du processus. Vous pouvez voir la sortie de mixin en fournissant une des options VM suivantes :

-Dmixin.debug=true

Active toutes les fonctionnalités de débogage

-Dmixin.debug.export=true

Active seulement la fonctionnalité qui envoie la sortie sur le disque

Dans IntelliJ, ouvrez la fenêtre Run/Debug Configurations en cliquant sur Run -> Edit Configurations.... Assurez-vous d’ajouter les options à l’application appropriée (Minecraft Client, Minecraft Server, ou les deux).

Un nouveau dossier nommé classes est créé dans le dossier .mixin.out lorsque l’une de ces options est utilisée. Ce dossier contient le nouveau contenu de la classe du processus de mixin avec une structure standard de package/classe.

Note

Ces options ne sont pas nécessitent pas d’avoir cloné le dépôt Mixin, ajouté Mixin en tant que module, ou utilisé le plugin Minecraft Development pour IntelliJ fait par DemonWav.

Astuce

Voir Mixin Java System Properties pour plus d’options VM mixin avec des explications pour chaque option.

Décompiler

Il y a plusieurs façons de voir les fichiers de classe depuis le processus mixin.

  • IDE

    Ouvrir le fichier dans votre IDE le décompilera et affichera le source codee

  • Fernflower

    Le fait d’avoir le jar de fernflower dans le classpath d’exécution entraînera la décompilation des fichiers de classe lorsqu’ils sont créés.

  • JD-Gui est un utilitaire graphique autonome qui affiche le code source Java de fichiers de classe.

Phases et Environnements

Il est important pour comprendre Mixin de savoir que l’exécution du jeu est divisée en deux phases distinctes : pre-init et default. La phase pre-init se produit entre le démarrage du jeu (en utilisant une commande, un script, en double-cliquant sur un raccourci, en cliquant sur un bouton « lancer » ou quelconque méthode que vous utilisez pour dire à votre ordinateur de lancer Minecraft) et le lancement du jeu (toutes les modifications sont complètes et le jeu démarre et entre dans sa boucle pncipale). La phase default commence lorsque le jeu est dans son état « prêt à être chargé » et est le même que simplement lancer Minecraft.

Les modifications se produisent aux classes d’infrastructure (loader, transformers, etc.) pendant la phase pre-init. Mixin récupère également des informations relatives à tous les autres mixins durant la phase pre-init et les applique durant la phase default.

Les phases sont gérées en les séparant en environnements, où la phase pre-init est l”environnement PREINIT, et la phase default est l”environnement DEFAULT.

Astuce

Les environnements font partie des propriétés spécifiées dans les fichiers de configuration mixin. Exemples de comment ils sont spécifiés : "target": "@env(PREINIT)" et "target": "@env(DEFAULT)"

Configurations

Le Mixin de la ressource principale nécessite le(s) fichier(s) de configuration. Chaque fichier de configuration définit un ensemble de mixin - les mixins à appliquer avec cette configuration. Tout mixin non spécifié par une configuration n’est pas appliqué, même si le mixin existe dans le code. Une application peut avoir un à plusieurs ensembles; cependant, chaque ensemble doit contenir des mixins pour seulement un environnement. Il est également utile de séparer les configurations en plusieurs fichiers pour des raisons d’organisation.

Chaque ensemble de mixin (fichier de configuratin) est subdivisé en trois zones distinctes : common, client et serveur. Les mixins common sont mélangés en premier, suivis par les clients ou les serveurs, selon le côté détecté.

Qui l’a démarré ?

Le sous-système Mixin interagit avec tous les programmes à travers une instance unique du sous-système, indépendamment du fichier, de l’auteur ou de l’organisation. Pourtant, seul l’un d’entre eux démarre le sous-système, et il détermine quelle version de Mixin sera utilisée. Un problème peut survenir plusieurs fois à cause d’une ancienne version de Mixin démarrée. Donc, l’ordre dans lequel les fichiers seront lancés est important. Idéalement, Sponge devrait se lancer en premier, juste après Forge, et avant les autres tweakers et coremods.

Un Mixin Cassé

Le jeu plantera quand une classe ne peut pas être chargée, et cette condition est connue sous le nom de mixin cassé. Un mixin cassé signifie généralement qu’il y a un problème avec les annotations et/ou la signature. Par exemple, regardez l’extrait de log suivant :

MixinSpongeSmeltingRecipe.java:41: error: No obfuscation mapping for @Overwrite method
    default String getId() {
                   ^

Cette erreur a été corrigée en changeant l’annotation @Overwrite en @Overwrite(remap = false). Mettre l’élément de remappage à false demandera au processeur d’annotation d’ignorer cette annotation quand il essayera de construire la table d’obfuscation pour le mixin.

L’analyse du code source peut mener à penser que le mot-clé default dans la déclaration de la méthode est le problème. Changer le mot-clé en static entraîne les logs suivants :

MixinSpongeSmeltingRecipe.java:41: error: getId() in MixinSpongeSmeltingRecipe clashes with getId() in
    static String getId() {
                  ^
  overriding method is static

MixinSpongeSmeltingRecipe.java:40: error: method does not override or implement a method from a supertype
    @Override
    ^

MixinSpongeSmeltingRecipe.java:42: error: non-static variable this cannot be referenced from a static context
        return CustomSmeltingRecipeIds.getDefaultId((SmeltingRecipe) this);
                                                                     ^

Comme vous pouvez le voir, trois erreurs différentes se sont produites au lieu d’une seule. Le bon correctif est l’ajout de l’élément remap comme décrit ci-dessus. Cependant, gardez en tête que le but de cet exemple n’est pas de montrer comment résoudre ce problème, mais de montrer à quoi ressemble un mixin cassé, et de souligner que la plupart des mixins cassés sont le résultat d’annotations ou de signatures incorrectes.

Note

Voir le Wiki de Mixin pour une description sur les signatures de méthodes

Cette section sera étendue dans le futur pour lister les causes courantes de mixins cassés et les solutions pour les réparer. Si vous sentez que vous pouvez aider, vous pouvez le faire sur notre dépôt GitHub.

Minecraft Development pour IntelliJ

Un outil utile pour travailler avec Mixin est le plugin Minecraft Development pour IntelliJ. Vous pouvez déboguer et passer pas-à-pas dans le code de mixin sans avoir à gérer les fichiers de classe sortis du class loader de mixin.

Note

Le site web du plugin fournit des informations sur l’installation et les options de support. Vous y trouverez également un lien vers son dépôt GitHub, où vous pourrez contribuer et/ou en apprendre davantage sur le projet.

Installation

Pour utiliser le plugin sans cloner les sources :

  1. Ouvrir File -> Settings -> Plugins et sélectionnez Marketplace.

  2. Cherchez minecraft dans la barre de recherche et sélectionnez Minecraft Development by DemonWav.

  3. Cliquez sur le bouton Install (ne redémarrez pas encore IntelliJ).

  4. Allez sur https://github.com/minecraft-dev/MinecraftDev et téléchargez un fichier ZIP du dépôt.

  5. Effectuez l’une des opérations suivantes :

    • Ouvrez le programme de votre choix pour extraire les fichiers zip. Naviguez dans le dossier idea-configs et copiez/extrayez le contenu de ce dossier dans le dossier .idea de votre espace de travail Sponge.

    • Extrayez le fichier zip n’importe où sur votre disque. Naviguez dans le dossier idea-configs et copiez le contenu de ce dossier dans le dossier .idea de votre espace de travail Sponge.

  6. Redémarrez IntelliJ

Le plugin devrait maintenant être actif et votre projet aura des configurations utiles et des paramètres de copyright.

Utilisation

À venir !