Cours Modding Forge 1.20.1

Appearance

Guide de Modding Minecraft 1.20.1 avec Forge ​

Module 1: Architecture Générale, Fichiers Requis et Configuration ​

Bienvenue dans ce premier module de votre auto-formation au modding Minecraft. Ce document rassemble toutes les bases théoriques et structurelles indispensables pour concevoir un mod moderne avec l'API Forge en version 1.20.1. Avant d'écrire votre première ligne de code pour un objet ou un bloc, vous devez comprendre comment un mod est structuré, configuré et reconnu par le jeu.

1. Environnement de Développement Requis ​

Pour développer un mod en 1.20.1, votre ordinateur doit disposer d'outils précis. Minecraft 1.20.1 fonctionne sous une version spécifique de Java, et Forge utilise un outil de construction automatisé appelé Gradle.

  • Java Development Kit (JDK) 17 : Indispensable. Minecraft 1.20.1 est compilé avec Java 17. Utilisez une distribution stable comme Eclipse Temurin (Adoptium) ou Amazon Corretto.

  • Un Environnement de Développement (IDE) : IntelliJ IDEA (fortement recommandé pour son excellente intégration de Gradle et du Java moderne) ou Eclipse.

  • Le MDK Forge (Mod Development Kit) : L'archive officielle fournie par Forge contenant l'arborescence de base et les scripts de configuration nécessaires pour lier votre code au code source décompilé de Minecraft.

2. Structure Globale du Projet (Arborescence) ​

Un projet Forge respecte scrupuleusement les standards de l'écosystème Java/Gradle. Voici l'arborescence type et minimale que doit posséder votre dossier de projet pour compiler correctement:

text
MonProjetMod/
├── .gradle/                          # Fichiers de cache internes à Gradle
├── build/                            # Fichiers générés lors de la compilation (généré automatiquement)
├── gradle/                           # Contient le "Gradle Wrapper" (fichiers de fonctionnement de Gradle)
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── src/                              # Le code source et les ressources de votre mod
│   └── main/
│       ├── java/                     # Votre code Java (Packages, Classes)
│       │   └── net/
│       │       └── pseudo/
│       │           └── nommod/
│       │               └── NomMod.java # Classe principale du mod
│       └── resources/                # Les textures, modèles, configurations, localisations
│           ├── META-INF/
│           │   └── mods.toml         # Fichier de métadonnées du mod (Obligatoire)
│           └── assets/
│               └── nommod/           # Votre "Namespace" (Ressources graphiques/textuelles)
│                   ├── lang/         # Fichiers de traduction (fr_fr.json, en_us.json)
│                   ├── models/       # Modèles 3D des blocs et objets (JSON)
│                   └── textures/     # Fichiers image (.png)
├── build.gradle                      # Script principal de configuration de la compilation du projet
├── gradle.properties                 # Propriétés et variables du projet (Versions, configurations)
├── gradlew                           # Script d'exécution Gradle pour Linux/macOS
└── gradlew.bat                       # Script d'exécution Gradle pour Windows

Important : Notion de Namespace > Le terme nommod (ici en minuscule) correspond à votre Mod ID. Il fait office de Namespace. C'est l'identifiant unique qui permet à Minecraft de dissocier vos ressources de celles du jeu de base ou d'autres mods (ex: nommod:mon_item).

3. Le Fichier de Métadonnées : mods.toml ​

Situé obligatoirement dans le dossier src/main/resources/META-INF/, le fichier mods.toml utilise la syntaxe TOML. Il indique à Forge le nom de votre mod, sa version, ses auteurs, et surtout ses dépendances (comme la version minimale de Forge ou de Minecraft requise).

Voici la configuration standard et nettoyée pour la version 1.20.1:

toml
# Version de la spécification du fichier TOML (Ne pas changer)
modLoader="javafml"

# Version de Forge requise pour charger le mod. Pour la 1.20.1, le loader majeur est 47
loaderVersion="[47,)"

# Licence sous laquelle vous distribuez votre mod (ex: MIT, All Rights Reserved, LGPL)
license="MIT"

[[mods]]
# L'identifiant unique de votre mod. Uniquement des minuscules, chiffres et tirets du bas (_)
modId="tutorialmod"

# Version de votre mod visible par les joueurs
version="1.0.0"

# Nom d'affichage de votre mod
displayName="Mon Mod de Tutoriel"

# URL vers la page de votre mod (optionnel)
displayURL="https://mon-site-web.com"

# Lien vers le logo du mod (optionnel, doit être placé dans les ressources)
logoFile="logo.png"

# Nom des crédits ou contributeurs
credits="Merci à la communauté Forge et à moi-même."

# Nom de l'auteur principal
authors="MonPseudo"

# Description détaillée du mod (Le triple guillemet permet le texte multi-ligne)
description='''
Ceci est la description de mon premier mod Minecraft en 1.20.1.
Ce cours me permet de comprendre les bases de la configuration.
...
'''

# Déclaration des dépendances du mod
[[dependencies.tutorialmod]]
modId="forge"
mandatory=true
versionRange="[47.1.0,)"
ordering="NONE"
side="BOTH"

[[dependencies.tutorialmod]]
modId="minecraft"
mandatory=true
versionRange="[1.20.1,1.21)"
ordering="NONE"
side="BOTH"

Attention aux Versions dans les Dépendances > La syntaxe [1.20.1,1.21) signifie "inclusif de 1.20.1 jusqu'à exclusif de 1.21". Cela garantit que votre mod ne tentera pas de se charger sur une version majeure ultérieure de Minecraft, ce qui provoquerait un plantage immédiat (Crash).

4. Le Script de Construction: build.gradle ​

Le fichier build.gradle à la racine du projet gère la compilation de votre code Java, applique les patchs nécessaires pour interagir avec le code obscurci de Minecraft, et injecte les dépendances. En 1.20.1, Forge utilise le plugin ForgeGradle.

Les éléments essentiels à configurer et comprendre à l'intérieur de ce fichier lourd sont:

  • Les Groupes et Versions : Définit l'identité de votre artefact Java.
groovy
version = '1.0.0'
group = 'com.pseudo.tutorialmod'
archivesBaseName = 'tutorialmod'
  • Le Bloc Minecraft : Indique la version du jeu et les "mappings" (la table de traduction des noms de fonctions de Minecraft, qui sont à l'origine illisibles). On utilise généralement les mappings official fournis par Mojang.
groovy
minecraft {
    mappings channel: 'official', version: '1.20.1'
    
    // Déclaration des configurations de lancement (Runs) pour tester le mod
    runs {
        client {
            workingDirectory project.file('run')
            property 'forge.logging.markers', 'REGISTRIES'
            property 'forge.logging.console.level', 'debug'
            mods { tutorialmod { source sourceSets.main } }
        }
        server {
            workingDirectory project.file('run/server')
            mods { tutorialmod { source sourceSets.main } }
        }
    }
}

5. La Classe Principale du Mod (NomMod.java) ​

C'est le point d'entrée de votre mod. Forge détecte cette classe grâce à l'annotation @Mod, qui doit correspondre exactement au modId défini dans votre mods.toml. C'est ici que l'on initialise les événements système (enregistrement des blocs, objets, configurations).

java
package net.pseudo.tutorialmod;

import net.minecraftforge.common.MinecraftForge;
import net.minecraftforge.eventbus.api.IEventBus;
import net.minecraftforge.fml.common.Mod;
import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

// L'annotation @Mod informe Forge que cette classe est le point d'entrée
@Mod(TutorialMod.MOD_ID)
public class TutorialMod {
    // Définition d'une constante globale pour le Mod ID (évite les fautes de frappe)
    public static final String MOD_ID = "tutorialmod";
    
    // Création d'un Logger pour afficher des messages dans la console de Minecraft
    private static final Logger LOGGER = LogManager.getLogger();

    public TutorialMod() {
        // Récupération du Bus d'Événements spécifique au chargement du mod
        IEventBus modEventBus = FMLJavaModLoadingContext.get().getModEventBus();
        
        // Enregistrement de la méthode de configuration commune (setup)
        modEventBus.addListener(this::commonSetup);
        
        // Enregistrement du mod auprès du bus d'événements global de Forge
        MinecraftForge.EVENT_BUS.register(this);
    }

    private void commonSetup(final net.minecraftforge.fml.event.lifecycle.FMLCommonSetupEvent event) {
        // Code exécuté durant la phase d'initialisation commune (Client + Serveur)
        LOGGER.info("Initialisation de mon mod de tutoriel réussie !");
    }
}

6. Résumé des Étapes pour Démarrer le Cours ​

Pour mettre en pratique ce premier module de votre cours autonome, suivez la procédure suivante:

  1. Téléchargez le MDK de Forge 1.20.1 sur le site officiel (files.minecraftforge.net).

  2. Extrayez les fichiers dans un dossier propre nommé selon votre projet.

  3. Ouvrez l'IDE (ex: IntelliJ IDEA) et faites "Ouvrir" en sélectionnant le fichier build.gradle. Laissez l'IDE importer le projet (cela peut prendre plusieurs minutes la première fois car Gradle télécharge les bibliothèques et décompile le jeu).

  4. Modifiez le fichier src/main/resources/META-INF/mods.toml avec vos informations.

  5. Nettoyez ou créez votre classe principale sous src/main/java/ dans un package personnalisé.

  6. Exécutez la commande Gradle genIntellijRuns (ou rafraîchissez l'onglet Gradle de l'IDE) pour générer les profils de lancement. Vous pouvez maintenant lancer le jeu en mode de test en cliquant sur "Run Client".