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 :
|
Active toutes les fonctionnalités de débogage |
|
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 :
Ouvrir
File -> Settings -> Plugins
et sélectionnezMarketplace
.Cherchez minecraft dans la barre de recherche et sélectionnez
Minecraft Development by DemonWav
.Cliquez sur le bouton
Install
(ne redémarrez pas encore IntelliJ).Allez sur https://github.com/minecraft-dev/MinecraftDev et téléchargez un fichier ZIP du dépôt.
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.
Redémarrez IntelliJ
Le plugin devrait maintenant être actif et votre projet aura des configurations utiles et des paramètres de copyright.
Utilisation
À venir !