Préparer son environnement de développement avec le MDK


  • Administrateurs

    Le code source de Minecraft n'est pas publié par Mojang et le code compilé est fortement offusqué (les variables et fonctions sont nommées de façon à être difficilement compréhensibles). Afin de pouvoir modder le jeu plus facilement, des outils ont été construits par la communauté, dont des outils de décompilation et des mappings (pour remplacer les noms illisibles par des noms anglais, plus pratiques à manipuler).
    Forge fourni donc le MDK (Mod Development Kit), une archive contenant tout ce qu'il faut pour démarrer la création d'un mod : Gradle comme moteur de production, qui va nous permettre de gérer la création de l'espace de travail pour Eclipse ou Idea, la compilation, mais aussi grâce au plugin ForgeGradle, décompiler le code de Minecraft, le dé-offusquer en appliquant des mappings et ré-offusquer après compilation.

    Sommaire du tutoriel

    Pré-requis

    Téléchargement et préparation

    Le kit de développement de mod Forge est disponible à l'adresse suivante : https://files.minecraftforge.net/maven/net/minecraftforge/forge/index_1.13.2.html
    Il s'agit d'une archive zip qu'il faudra extraire dans un dossier au choix. Le nom du dossier sera le nom du projet dans l'IDE par la suite, on nommera donc le dossier avec le nom de son futur mod (il est toujours possible de renommer après coup le nom affiché dans l'IDE). Dans les différents tutoriels publiés sur Minecraft Forge France, ce sera ModTutorial. Le terme « Dossier du MDK » sera utilisé pour désigner ce dossier dans les futurs tutoriels.

    Configuration du MDK

    Dans le dossier du MDK se trouve un fichier build.gradle gérant quelques paramètres. Il peut être ouvert avec n'importe quel éditeur de texte.
    Tout d'abord, on trouve un bloc buildscript contenant le nécessaire pour ajouter le plugin ForgeGradle.
    On y retrouve ensuite des éléments n'étant dans aucun bloc, permettant d'appliquer les plugins puis des configurations intéressantes à modifier :

    version = '1.0'
    group = 'com.yourname.modid' // http://maven.apache.org/guides/mini/guide-naming-conventions.html
    archivesBaseName = 'modid'
    

    Ces trois lignes contrôlent dans l'ordre :

    • la version du mod
    • le groupe du mod : cela correspond au package du mod, généralement un nom de domaine dans le sens inverse avec le tld en premier suivi du nom du projet mais cela peut aussi être autre chose totalement arbitraire. Attention, par-contre, tout comme un nom de package, par convention cela doit être entièrement en minuscule et séparé par des points.
    • le nom de base de l'archive : Le fichier sera nommé ainsi suivi d'un tiret et de la version après compilation. On y mettra donc le nom du mod (il est possible d'y mettre des majuscules)

    En dessous on retrouve le bloc minecraft, contenant les paramètres de mapping. On pourra choisir d'utiliser des mappings stables (versions publiées soccasionnellement) ou snapshot (génération automatique chaque jour). La liste des mappings est disponible sur le site dédié au bot mcp de bspk

    Toujours dans ce bloc, il y a diverses configurations comme celle du transformateur d'accès (son utilisation sera traitée dans un autre tutoriel, il sert à changer la visibilité des variables de classes de Minecraft) ou encore celles des configurations de lancement (inutile d'y toucher).

    Ensuite vient le bloc de dépendances. La première ligne non commenté commençant par minecraft gère la version de Forge. Elle pourra être changée ici par la suite, ce qui évitera de re-télécharger le MDK pour changer la version de Forge.
    Toujours dans ce bloc, il est possible d'ajouter des dépendances, que ce soit des bibliothèques externes ou un autre mod. L'utilisation des dépendances sera traité en détails dans un tutoriel dédié à ce sujet.

    Enfin, le dernier bloc est celui gérant la création du jar. Par défaut, une configuration contrôlant le manifeste du jar est présente, il faudra changer la valeur de Specification-Title par l'identifiant du mod puis Specification-Vendor et Implementation-Vendor par le fournisseur du mod (l'auteur du mod ou l'organisation gérant le mod).

    Fonctionnement des mappings

    Note

    Cette partie a pour but d'expliquer l'intérêt et le fonctionnement des mappings. Elle est optionnelle, mais cela peut toujours être intéressant de comprendre ces mécanismes.

    Afin de protéger le code de Minecraft, Mojang offusque ce dernier : C'est-à-dire que les noms des classes, fonctions, variables et paramètres, normalement en anglais et lisibles pour un humain sont remplacé par un nom court et n'ayant aucun sens contextuel, comme a, b, abb, xy, etc. Ainsi, seul Mojang dispose du vrai code de Minecraft, ce qui empêche les gens de prétendre de disposer du code et d'en être propriétaire. Cela reste une protection surtout juridique, car comme on va le voir cela n'empêche pas de faire de la rétro-ingénierie (étudier le fonctionnement du code) de Minecraft.

    Afin de rendre la création de mod plus agréable et plus simple (cela ne serait pas très pratique d'avoir des a ou des b comme nom de fonction dès qu'on appelle du code de Minecraft ...). C'est pourquoi MCP (Minecraft Coder Pack) et les mappings ont été créés.
    L'outil fonctionne en deux passes : une première va se charger de générer des noms uniques pour chaque variable / fonction / paramètre (car la variable a dans la classe ab n'est pas la même que la variable a de la classe ac) ce qui va aboutir sur des fonctions nommées func_xxxx, des variables nommées field_xxxx et des paramètres nommés de la même façon (où xxxx est un nombre unique). Cette étape est automatique et tout est auto-généré.

    La deuxième passe consiste à remplacer tous ces func_xxxx, field_xxxx, etc. par un nom anglais utile pour un développeur. Ce nom anglais ne peut pas être deviné automatiquement et est fait à la main par des bénévoles qui étudient le code de Minecraft pour trouver des noms en fonction du contexte.
    Tous ces noms sont stockés dans des tableaux de correspondance : les mappings.

    Il est possible de les retrouver dans le dossier $HOME/.gradle/caches/forge_gradle/maven_downloader/de/oceanlabs/mcp/ ($HOME étant le dossier de la session, C:\Users\nom d'utilisateur\ sous Windows, /home/nom d'utilisateur sous Linux et /User/nom d'utilisateur sous MacOS) puis en allant dans le dossier mcp_snapshot ou mcp_stable et enfin dans la version correspondante. Les mappings au format CSV se trouvent dans l'archive ZIP.

    Choisir des mappings plus récentes permettra d'avoir moins de noms incompréhensibles dans le code de Minecraft.
    Attention, en revanche, si des mappings conçus pour la 1.13.1 fonctionneront sans problème en 1.13.2, la compatibilité n'est pas garantie entre les versions majeures (par exemple utiliser des mappings conçus pour la 1.13 en 1.12 n'est pas une bonne idée, comme certains noms de la 1.12 ne sont plus utilisés en 1.13, ils peuvent être retirés).

    Importation du projet

    Maintenant la configuration de Gradle faite, il ne reste plus qu'à importer le projet dans l'IDE. Il suffit de lancer son IDE en choisissant un espace de travail au choix (par exemple celui par défaut) puis de suivre les étapes.

    Dans Eclipse

    Clic droit à gauche dans l'explorateur de projet puis « Import... ». Dans la catégorie « Gradle », choisir « Existing Gradle Project » puis cliquer sur suivant et dans « Project root directory » choisir le dossier du MDK.

    importation du projet Gradle sous Eclipse

    Enfin, cliquer sur « Finish » et il ne reste qu'à patienter. (Sous Windows, il faudra autoriser l'accès au réseau si le pare-feu le demande).

    Une fois cette étape terminée, le projet sera visible dans l'explorateur de package. Pour le lancer, il va être nécessaire de générer les fichiers de lancement, en se rendant dans l'onglet « Gradle tasks » (sur la partie du bas d'Eclipse) puis en choisissant le dossier du projet et enfin en double cliquant sur « genEclipseRuns » dans la catégorie « fg_runs »
    gradle tâche genEclipseRuns

    Après cela, il ne reste plus qu'à rafraîchir le projet (clic droit -> refresh sur le projet dans l'explorateur de package à gauche), les fichier runClient.launch et runServer.launch devraient être présents :
    eclipse-run.jpg

    Sélectionner un de ces derniers puis cliquer sur la flèche verte lancera le jeu et l'ajoutera à la liste des configurations de lancement.

    Note

    Il est possible d'explorer le code de Minecraft en se rendant dans « Project and External Dependencies » puis dans le fichier jar de forge. Les différents packages de Minecraft et de Forge seront dedans, contenant les classes qui peuvent être ouvertes avec un simple double clic (les sources de ces classes sont liées, on voit donc directement un code lisible).

    Dans Intellij Idea

    La démarche est légèrement différente une fois que vous êtes sur cette fenêtre :

    fenêtre de lancement d'Idea

    Il vous suffit de cliquer sur le bouton Import Project et de sélectionner le build.gradle du dossier MDK.
    Une fois fait, vous allez arriver sur cette fenêtre :

    Importation du projet Gradle sous IDEA

    Vous pouvez cocher la case Use auto-import, mais elle aura pour conséquence d'activer l'importation automatique dès que vous ferez la moindre modification dans le build.gradle.

    Après avoir validé, il vous faudra attendre quelques minutes afin que le projet soit entièrement importé.

    Une fois cette étape terminée, il faut lancer la commande genIntellijRuns présente dans le tableau de droite d'IDEA.

    Pour ouvrir le panneau de droite, il faut passer la souris sur cette icône :
    idea64_2019-02-16_13-34-10.png

    Ensuite, vous sélectionnez Gradle :

    idea64_2019-02-16_13-32-09.png

    Et vous aurez cette fenêtre :

    idea64_2019-02-16_13-36-34.png

    Ensuite, il vous suffit d'aller dans Tasks > fg_runs > genIntellijRuns et vous avez juste à double-cliquer dessus pour lancer la commande.

    Attention

    La commande genIntellijRuns est à lancer à chaque changement de version de Forge.

    Vous attendez quelques minutes que la commande se termine et vous aurez généré les configurations de lancement pour le client et le serveur.

    À l'heure où j'écris ces lignes, il faut modifier les configurations de lancement, pour ce faire, il faut cliquer sur Edit Configurations... :

    idea64_2019-02-16_13-45-53.png

    Ensuite, vous allez arriver sur cette fenêtre :

    idea64_2019-02-16_14-36-39.png

    Vous ouvrez la partie Application, puis dans runClient et runServer, vous devrez affecter le module suivant :

    idea64_2019-02-19_19-49-40.png

    Vous appliquez les changements, puis cliquez sur OK et vous pourrez désormais lancer le jeu en client ou en serveur.

    Licence et attribution

    Creative Commons

    Ce tutoriel rédigé par @robin4002 et @Superloup10, corrigé par @BrokenSwing et publié sur Minecraft Forge France est mis à disposition selon les termes de la licence Creative Commons Attribution - Pas d’Utilisation Commerciale - Partage dans les Mêmes Conditions 4.0 International

    retour Sommaire des tutoriels