So You Want to Make a Minecraft Mod

Creating a Minecraft mod is one of the most rewarding things you can do as a player and programmer. You get to extend the game exactly how you imagine, and the skills you build apply directly to real-world Java development. This guide covers everything you need to set up your workspace and write a simple "Hello World" mod using Forge — the most widely used modding framework for Java Edition.

Prerequisites

Before you start, you'll need a few things:

  • Java Development Kit (JDK) 17 — Download from Adoptium or Oracle. Do not use JDK 8 or 21 for Forge 1.20.x.
  • IntelliJ IDEA (Community Edition is free) — The most popular IDE for Minecraft modding. Eclipse works too.
  • Git — Useful for version control and cloning the Forge MDK.
  • A basic understanding of Java — you don't need to be an expert, but knowing variables, classes, and methods will help enormously.

Step 1: Download the Forge MDK

The Mod Development Kit (MDK) is a template project provided by the Forge team that sets up everything you need. Here's how to get it:

  1. Go to files.minecraftforge.net and select your target Minecraft version.
  2. Download the MDK (not the installer) — it's a .zip file.
  3. Extract it to a dedicated folder, like C:\MinecraftMods\MyFirstMod\.

Step 2: Open the Project in IntelliJ IDEA

  1. Open IntelliJ IDEA and choose Open (not New Project).
  2. Navigate to the folder where you extracted the MDK and open it.
  3. IntelliJ will detect the build.gradle file and ask to import as a Gradle project. Click "Trust Project" and let Gradle sync — this can take several minutes as it downloads dependencies.
  4. Once synced, open the Gradle panel (right side) and run: Tasks → forgegradle runs → genIntellijRuns. This sets up the run configurations for launching Minecraft from your IDE.

Step 3: Understand the Project Structure

After setup, you'll see a structure like this:

  • src/main/java/ — Your Java source code lives here
  • src/main/resources/ — Textures, models, sounds, and data files
  • build.gradle — Your build configuration (mod name, version, dependencies)
  • src/main/resources/META-INF/mods.toml — Your mod's metadata (ID, name, description, author)

Step 4: Configure Your Mod's Identity

Open mods.toml and update the key fields:

  • modId — A unique lowercase identifier, e.g. myfirstmod
  • version — e.g. 1.0.0
  • displayName — The human-readable name shown in Minecraft's mod list
  • description — A short description of what your mod does

Also update build.gradle to match your modId and group name.

Step 5: Write Your First Event Handler

Open the main mod class (usually named something like ExampleMod.java) and look at how it's structured. A simple addition: print a message to the Minecraft log when the game loads.

@Mod("myfirstmod")
public class MyFirstMod {
    public MyFirstMod() {
        IEventBus modEventBus = FMLJavaModLoadingContext.get().getModEventBus();
        modEventBus.addListener(this::setup);
    }

    private void setup(final FMLCommonSetupEvent event) {
        System.out.println("Hello from MyFirstMod! The mod is loading.");
    }
}

This is the backbone of any Forge mod — a main class annotated with @Mod that registers event listeners.

Step 6: Run Your Mod

  1. In IntelliJ, open the Run Configurations dropdown at the top.
  2. Select runClient and click the Run button.
  3. Minecraft will launch with your mod loaded. Check the Mods screen to confirm it appears.
  4. Look at the console output — you should see your "Hello" message!

What to Learn Next

Once you've confirmed your mod loads, here are natural next steps:

  • Adding a custom item — register a new item using DeferredRegister
  • Adding a custom block — similar registration process with block state files
  • Custom crafting recipes — JSON files in resources/data/
  • Community resources — the Forge forums, the Modding Discord servers, and Mcjty's YouTube tutorials are all excellent for going deeper

Every great mod started exactly where you are now. Keep experimenting, read the source code of mods you admire, and enjoy the process.