Hello Minecraft! Build Your First Custom Item Mod

1

☕

Install Java JDK 21

Download and install the Java Development Kit the language Minecraft is written in

Active

🎯

Goal for this step

Get Java JDK 21 installed so your computer can run and compile Java code.

👨‍👧

Parent note: Java JDK is completely free. We need version 21 specifically because that's what Minecraft 1.21 uses. You may already have Java installed we still recommend getting JDK 21 to make sure everything matches.

Download Java JDK 21

1Go to adoptium.net in your browser. This is the free official Java download site.
2Click the big Latest LTS Release button. Make sure it says Temurin 21 on it.
3It will automatically detect your operating system. Click Download.
4Run the downloaded installer. Click Next through the steps all defaults are fine.
5On the installer screen, make sure "Add to PATH" or "Set JAVA_HOME" is ticked if you see it.
6Once installed, open a Command Prompt (Windows) or Terminal (Mac). Type: java version and press Enter.
7You should see something like openjdk version "21.0.x". If you do, Java is ready!

💡

On Windows, search for cmd in the Start menu to open Command Prompt. On Mac, search for Terminal in Spotlight (⌘+Space).

Java JDK 21 is downloaded and installed

java version shows version 21 in the terminal

2

🧠

Install IntelliJ IDEA

Set up the free code editor we'll write all our Java in

Locked

🎯

Goal for this step

Install IntelliJ IDEA Community Edition it's the best free editor for Java modding.

1Go to jetbrains.com/idea/download. Scroll down to find IntelliJ IDEA Community Edition this is the free one.
2Click Download under Community Edition (not Ultimate that costs money).
3Run the installer. Click through the defaults. On the options screen, tick "Add 'bin' folder to PATH" if you see it.
4Open IntelliJ IDEA when it finishes. You'll see the welcome screen that's perfect.

📖

IntelliJ IDEA will suggest installing plugins when you first open it. You can skip all of these for now we just need the basics.

IntelliJ IDEA Community Edition is installed

The IntelliJ welcome screen is showing

3

🧵

Download the Fabric Mod Template

Get the official Fabric starter project your mod's skeleton is already built

Locked

🎯

Goal for this step

Download the Fabric Example Mod template it gives you a complete working mod structure to start from.

👨‍👧

Parent note: Fabric provides a free starter template on GitHub. We'll download it as a ZIP file no GitHub account needed. This gives us a project already set up with all the right files and settings.

1Go to github.com/FabricMC/fabric-example-mod
2Click the green Code button, then click Download ZIP.
3Save the ZIP somewhere easy to find like your Desktop or Documents folder.
4Right-click the ZIP file and choose Extract All (Windows) or double-click it (Mac). Extract it to your Documents folder.
5Rename the extracted folder from fabric-example-mod-main to CrystalMod. This is your mod's project folder!

💡

Keep this folder somewhere safe it's your whole mod project. Don't put it inside OneDrive or iCloud folders as they can cause issues with Gradle.

ZIP file downloaded and extracted

Folder renamed to CrystalMod

4

📂

Open the Project in IntelliJ

Load your mod project and let Gradle set everything up automatically

Locked

🎯

Goal for this step

Open the CrystalMod project in IntelliJ and wait for Gradle to download all the Minecraft files it needs.

⚠️

This step downloads Minecraft libraries for the first time it can take 5–15 minutes depending on your internet speed. That's completely normal!

1Open IntelliJ IDEA. On the welcome screen, click Open.
2Navigate to your CrystalMod folder and click OK (or Open).
3A dialog may ask "Trust and open project?" click Trust Project.
4IntelliJ will open and you'll see a Gradle build running at the bottom of the screen. Wait for it to finish the progress bar will disappear when done.
5On the right side, click the Gradle tab (elephant icon). Expand Tasks → fabric → genSources and double-click it to run it. This makes Minecraft's source code readable in your editor.
6Wait for genSources to finish (another minute or two). Done when the run panel shows BUILD SUCCESSFUL.

💡

If you don't see the Gradle tab, go to View → Tool Windows → Gradle to open it.

Project is open in IntelliJ with no red errors in the file tree

Gradle sync completed (BUILD SUCCESSFUL in the output)

genSources task ran successfully

🎓 Teacher Note Step 4This is the #1 stuck point in the whole series. 90% of Gradle sync failures are: wrong JDK version (must be Java 21), school firewall blocking gradle.org, or the student didn't wait long enough. Have students check File → Project Structure → SDK. First sync can take 10–20 min on slow connections.

🚨 Stuck? Gradle sync is failing

BUILD FAILED: Could not resolve your network may be blocking Gradle downloads. Try on a different network, or ask your teacher to whitelist gradle.org and services.gradle.org.
JDK not found / wrong SDK go to File → Project Structure → SDK and make sure it shows Java 21. If not, click + and browse to your JDK 21 install folder.
Sync takes forever the first sync downloads everything it needs (~500MB). On a slow connection this can take 20+ minutes. Just wait for BUILD SUCCESSFUL.
Nothing happens when I click the elephant button try File → Reload All Gradle Projects from the top menu bar.

5

🗂️

Explore the Project & Update fabric.mod.json

Understand the folder structure and give your mod its own name and ID

Locked

🎯

Goal for this step

Rename the mod to CrystalMod and update fabric.mod.json with your mod's details.

Your project structure

CrystalMod/ src/main/ java/com/example/ ← your Java code goes here ExampleMod.java ← main mod class resources/ assets/modid/ ← textures, models, sounds data/modid/ ← recipes, loot tables fabric.mod.json ← your mod's info file

Update fabric.mod.json

1In the left panel, navigate to src → main → resources → fabric.mod.json and double-click it.
2Replace the entire file contents with the code below:

fabric.mod.json

{
  "schemaVersion": 1,
  "id": "crystalmod",
  "version": "1.0.0",
  "name": "Crystal Mod",
  "description": "My first Minecraft mod!",
  "authors": ["YourNameHere"],
  "environment": "*",
  "entrypoints": {
    "main": ["com.example.crystalmod.CrystalMod"]
  },
  "depends": {
    "fabricloader": ">=0.15.0",
    "fabric-api": "*",
    "minecraft": "~1.21"
  }
}

3Change "YourNameHere" to your actual name!
4Save the file with Ctrl+S (Windows) or Cmd+S (Mac).
5Now rename the Java package folder. In the file tree, navigate to src → main → java → com → example. Right-click the example folder → Refactor → Rename → type crystalmod → click Refactor.
6Also rename ExampleMod.java to CrystalMod.java (right-click → Rename).

fabric.mod.json updated with "crystalmod" as the mod ID

Package renamed to com.example.crystalmod

Main class renamed to CrystalMod.java

6

📝

Update the Main Mod Class

Fix CrystalMod.java so it's ready to register all our mod content

Locked

🎯

Goal for this step

Set up CrystalMod.java the class Fabric calls when your mod loads into the game.

📖

What is a class? In Java, a class is like a blueprint. CrystalMod.java is the blueprint for our whole mod it's the first thing that runs when Minecraft loads it.

1Open CrystalMod.java from the file tree. Delete everything inside and replace with:

CrystalMod.java

package com.example.crystalmod;

import net.fabricmc.api.ModInitializer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class CrystalMod implements ModInitializer {

    public static final String MOD_ID = "crystalmod";
    public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

    @Override
    public void onInitialize() {
        ModItems.registerModItems();
        LOGGER.info("Crystal Mod loaded! 💎");
    }
}

📖

What does onInitialize do? Fabric calls this method when your mod starts up. We'll call all our registration methods from here items, blocks, mobs everything goes through this method.

2Don't worry if ModItems shows red we haven't made that file yet! We'll fix that in the next step.
3Save the file.

CrystalMod.java updated with the code above

MOD_ID is set to "crystalmod"

7

💎

Create ModItems.java & Register the Crystal Gem

Write the Java code that adds your Crystal Gem item to the game

Locked

🎯

Goal for this step

Create a new Java class called ModItems and use it to register a Crystal Gem item with Minecraft.

1In the file tree, right-click the crystalmod package folder → New → Java Class. Name it ModItems and press Enter.
2Delete everything in the new file and paste this:

ModItems.java

package com.example.crystalmod;

import net.fabricmc.fabric.api.itemgroup.v1.ItemGroupEvents;
import net.minecraft.item.Item;
import net.minecraft.item.ItemGroups;
import net.minecraft.registry.Registries;
import net.minecraft.registry.Registry;
import net.minecraft.util.Identifier;

public class ModItems {

    // Our Crystal Gem item
    public static final Item CRYSTAL_GEM = registerItem(
        "crystal_gem",
        new Item(new Item.Settings())
    );

    // Helper method to register an item
    private static Item registerItem(String name, Item item) {
        return Registry.register(Registries.ITEM,
            Identifier.of(CrystalMod.MOD_ID, name),
            item);
    }

    // Add Crystal Gem to the Ingredients creative tab
    public static void registerModItems() {
        ItemGroupEvents.modifyEntriesEvent(ItemGroups.INGREDIENTS)
            .register(entries -> {
                entries.add(CRYSTAL_GEM);
            });
    }
}

📖

What does this code do?
• CRYSTAL_GEM creates the item object with default settings
• registerItem() tells Minecraft "this item exists and its ID is crystalmod:crystal_gem"
• registerModItems() adds the gem to the Ingredients creative tab so you can find it

3Save the file. The red error on ModItems in CrystalMod.java should disappear now.
4If you see red underlines on any imports, hover over them and click Import class or press Alt+Enter to auto-fix them.

ModItems.java created in the crystalmod package

No red errors in CrystalMod.java or ModItems.java

🎓 Teacher Note — Step 7Two common mistakes: (1) student creates the file outside the crystalmod package the first line must say package com.example.crystalmod;. (2) They forget to call ModItems.registerModItems() in CrystalMod.java, so the item never appears in-game even though it compiles fine.

🚨 Stuck? Item doesn't appear or red errors

Cannot find symbol: ModItems ModItems.java must be in the com.example.crystalmod package (same folder as CrystalMod.java). Check the very first line says package com.example.crystalmod;.
Item not in creative inventory open CrystalMod.java and confirm you have ModItems.registerModItems(); inside onInitialize().
Red squiggle on Registry / Registries click on the red word, press Alt+Enter, and choose Import class. You want net.minecraft.registry.Registry and net.minecraft.registry.Registries.
Red squiggle on ItemGroupEvents Alt+Enter → Import → net.fabricmc.fabric.api.itemgroup.v1.ItemGroupEvents.

8

🎨

Create the Item Texture & Model

Give your Crystal Gem a 16×16 pixel art texture so it looks right in-game

Locked

🎯

Goal for this step

Create a PNG texture and a model JSON file so your Crystal Gem has a proper appearance in Minecraft.

👨‍👧

Parent note: We need to create three files here a PNG image (16×16 pixels), a model JSON file, and a language file. Take your time with each one.

Create the texture folders

1In the file tree, navigate to src → main → resources → assets. Right-click the assets folder → New → Directory. Create these folders one at a time: crystalmod → inside it textures → inside that item.
2Also inside crystalmod create: models → inside that item.
3Also inside crystalmod create a folder called lang.

Draw your texture

4Go to our Pixel Studio tool or use any image editor. Create a 16×16 pixel image. Draw a crystal gem shape — shades of blue, cyan and white look great!
5Save/export it as crystal_gem.png into the assets/crystalmod/textures/item/ folder you just created.

Create the model JSON

6Right-click the models/item folder → New → File. Name it crystal_gem.json. Paste this inside:

assets/crystalmod/models/item/crystal_gem.json

{
  "parent": "item/generated",
  "textures": {
    "layer0": "crystalmod:item/crystal_gem"
  }
}

Create the language file

7Right-click the lang folder → New → File. Name it en_us.json. Paste this:

assets/crystalmod/lang/en_us.json

{
  "item.crystalmod.crystal_gem": "Crystal Gem"
}

crystal_gem.png texture file created (16×16 pixels)

crystal_gem.json model file created

en_us.json language file created

9

🏃

Run Minecraft with Your Mod!

Launch the game straight from IntelliJ and see your Crystal Gem in action

Locked

🎯

Goal for this step

Launch Minecraft from IntelliJ using the Fabric run configuration and find your Crystal Gem in the creative inventory.

1In IntelliJ, look at the top-right of the screen. You'll see a dropdown click it and look for Minecraft Client in the list. Select it.
2Click the green ▶ Play button next to it. This builds your mod and launches Minecraft!
3Watch the output panel at the bottom. You should see Crystal Mod loaded! 💎 in the log that's your LOGGER message!
4When Minecraft opens, click Singleplayer → Create New World. Enable Creative Mode. Click Create World.
5Press E to open your inventory, then click the Creative Search tab (compass icon). Search for Crystal Gem. It should appear!
6Alternatively, open chat with T and type: /give @p crystalmod:crystal_gem and press Enter.

🎉

You should now be holding your custom Crystal Gem in Minecraft! You just wrote your first Minecraft mod!

⚠️

If the game crashes, check the IntelliJ output panel for red error messages. The most common issue is a typo in one of the JSON files JSON is very picky about commas and quotes!

Minecraft launched from IntelliJ without crashing

"Crystal Mod loaded!" appears in the log

Crystal Gem appears in the creative inventory

10

🌟

Challenge: Add a Second Item!

Use what you've learned to add your own Crystal Dust item to the mod

Locked

🎯

Goal for this step

Add a Crystal Dust item or any item you invent using the same pattern you just learned.

🎨

This is your creative challenge! You now know exactly how to add any item to Minecraft. Use the same steps for Crystal Gem but change the name to crystal_dust (or anything you like!).

Follow the same pattern

1In ModItems.java, add a new line after CRYSTAL_GEM:
public static final Item CRYSTAL_DUST = registerItem("crystal_dust", new Item(new Item.Settings()));
2Inside registerModItems(), add: entries.add(CRYSTAL_DUST);
3Create crystal_dust.json in the models/item folder (same as crystal_gem.json, just change the texture path).
4Draw a new 16×16 texture for it and save as crystal_dust.png in textures/item/.
5Add "item.crystalmod.crystal_dust": "Crystal Dust" to your en_us.json.
6Run Minecraft again and find your new item!

💡

The key rule: for every new item, you need 3 things: 1) registration code in ModItems.java · 2) a model JSON · 3) a texture PNG. That's the pattern for everything in Fabric modding!

A second custom item is registered in ModItems.java

It appears in Minecraft's creative inventory

It has its own texture (not the same as the gem)

Hello Minecraft!Your First Custom Item

Download Java JDK 21

Your project structure

Update fabric.mod.json

Create the texture folders

Draw your texture

Create the model JSON

Create the language file

Follow the same pattern

Hello Minecraft!
Your First Custom Item