Prefer no install? Change Minecraft from a plain folder instead. Plan a crafting recipe in our browser Datapack Studio and export a real datapack zip, with no Java and no mod loader. Open the Minecraft Mod Studio →

📦

Workshop reference pack: download an offline copy of every step in this workshop: ⬇ minecraft-first-item-mod-reference.zip. Every code block also has a Copy button.

☕

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

🧠

Knowledge Check

+15 XP

Which Java version does this mod use?

AJava 8

BJava 17

CJava 21

🧠

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

🧠

Knowledge Check

+15 XP

What is IntelliJ IDEA used for?

AWriting and running the Java code

BDrawing textures

CPlaying Minecraft

🧵

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

🧠

Knowledge Check

+15 XP

What does the Fabric template give you?

AA starter project with the mod skeleton

BA finished mod

CA texture pack

📂

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.

🧠

Knowledge Check

+15 XP

What does Gradle do when the project opens?

ASets everything up automatically

BDraws the textures

CPublishes the mod

🎨

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 create a new Java package for your mod's code. In the file tree, navigate to src → main → java → com → example. Right-click the example folder → New → Package → type crystalmod → press Enter. This creates a new com.example.crystalmod folder inside example, keep the example folder itself, don't rename it.
6Drag ExampleMod.java into the new crystalmod folder, then rename it to CrystalMod.java (right-click → Rename).

🧩

Put the Steps in Order

+20 XP

Drag these steps into the correct order to set up your mod project:

Create package com.example.crystalmod

Open fabric.mod.json in resources

Move ExampleMod.java into crystalmod folder

Set the mod ID to "crystalmod"

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

New package com.example.crystalmod created (example folder kept, not renamed)

Main class moved into crystalmod and renamed to CrystalMod.java

🧠

Knowledge Check

+15 XP

What do you change in fabric.mod.json?

AThe mod name and ID

BThe Java version

CThe recipe

📝

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"

🧠

Knowledge Check

+15 XP

Why update CrystalMod.java?

ASo it is ready to register mod content

BTo draw the item

CTo set the texture

💎

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.

🧠

Knowledge Check

+15 XP

What does this step register?

AThe Crystal Gem item

BA Crystal Block

CA Crystal Sword

🎨

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

🧠

Knowledge Check

+15 XP

What size is the Crystal Gem texture?

A8x8

B16x16

C32x32

🏃

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

🧠

Knowledge Check

+15 XP

How do you launch the game with your mod?

AStraight from IntelliJ

BFrom the website

CFrom a texture file

🌟

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)

🧠

Knowledge Check

+15 XP

What does the challenge ask you to add?

AA Crystal Dust item

BA Crystal Block

CA new mob

🎓

What you just learned:

Installing Java JDK 21 and IntelliJ IDEA Community Edition for Minecraft modding
Setting up a Fabric mod project with Gradle sync and genSources
Updating fabric.mod.json with your mod's ID, name and entry point
Writing Java classes: ModInitializer, item registration with Registry.register()
Creating item textures (16×16 PNG), model JSON files and language files for display names

🎉💎⛏️🎊✨

You Made Your First Mod!

You installed Java, set up Fabric, wrote real Java code and added a brand-new item to Minecraft. That's genuinely impressive. Episode 2 adds a custom block!

🪨 Episode 2: Custom Block → ⭐ View My Progress & Certificates

This workshop was free and took many hours to build. If it helped you learn something new, consider supporting the project.

☕ Support on Ko-fi

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