Sommaire des tutoriels
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, Idea ou VS Code, 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
- Configuration du MDK
- Fonctionnement des mappings
- Importation du projet
- Licence et attribution
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/
Prennez le “Mdk” recommandée si vous souhaitez la version stable, ou la dernière version en date si vous souhaitez les dernières fonctionnalités (ou s’il n’y a pas version recommandée).
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 la suite et 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ée 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.
L’avant 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).
Enfin vient un dernier bloc gérant la publication du mod vers un dépôt maven. Par défaut il publie dans le dossier mcmodsrepo du dossier du projet, mais on peut également modifier ce script pour publier sur un dépôt distant.
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.
Pour 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 …), 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 (ou encore, celles de la 1.14.3 fonctionnent en 1.14.4), la compatibilité n’est pas garantie entre les versions majeures (par exemple utiliser des mappings conçus pour la 1.14 en 1.13 n’est pas une bonne idée, comme certains noms de la 1.13 ne sont plus utilisés en 1.14, 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
Faites un 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.
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 »
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 :
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 :
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 :
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 cela, passer votre souris sur l’icone tout en bas à gauche puis sélectionnez Gradle :
Sur la partie gauche d’IDEA, la section gradle va s’ouvrir :
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... :
Ensuite, vous allez arriver sur cette fenêtre :
Vous ouvrez la partie Application, puis dans runClient et runServer, vous devrez affecter le module suivant :
Vous appliquez les changements, puis cliquez sur OK et vous pourrez désormais lancer le jeu en client ou en serveur.
Dans VS Code
Assurez-vous de bien avoir le pack d’extension Java puis importez le dossier du MDK en allant dans le menu « Fichier » puis « Ouvrir le dossier ».
L’extension Java va automatiquement détecter le fichier build.gradle et commmencer l’importation. La progression est visible tout en bas à gauche:
Une fois celle-ci terminée, allez sur le menu « Terminal » puis cliquez sur « Nouveau terminal ».
Dans ce dernier entrez la commande ./gradlew genVSCodeRuns puis patientez jusqu’à la fin.
Tout est désormais en place pour le développement, vous pouvez lancez le jeu en vous rendant sur le menu debug (icône de scarabé à gauche) puis choisir la configuration à lancer (client ou serveur). Il est également possible de lancer le jeu en utilisant le raccourci clavier F5.
Licence et attribution
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