⛏️ My First Minecraft Mod Setup Guide
Starter Files &
Project Setup
Prefer no install? You can 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 → Everything you need before Episode 1 the complete folder structure, tool downloads, and what every file does. Bookmark this page!
✓ Free
⏱️ ~30 min setup
☕ Java 21 Required
← Back to All Episodes
🛠️ Tools You Need to Install
Install these before opening Episode 1. All are free. You only need to do this once.
⚠️
JDK version matters! Fabric 1.21.1 requires Java 21 exactly. Java 17 is too old and Java 22+ may have issues. When in doubt, download from Adoptium and choose the LTS release for Java 21.
📚 What You'll Build Series Overview
| Episode | What You Add | Key Concept | Badge |
|---|
| Ep 1 Crystal Gem |
A custom item you can hold and collect |
Registry.register, ModItems, Item.Settings |
💎 Item |
| Ep 2 Crystal Block |
A glowing placeable block with loot table |
Block, BlockItem, blockstate JSON, loot tables |
🪨 Block |
| Ep 3 Magic Cookie |
Food that gives Speed + Jump Boost effects |
FoodComponent.Builder, StatusEffectInstance |
🍪 Food |
| Ep 4 Crystal Tools |
Crystal Pickaxe and Crystal Sword |
ToolMaterial enum, PickaxeItem, SwordItem, mining tags |
⚒️ Tools |
| Ep 5 Crystal Frog |
A custom mob with AI, model, and loot |
AnimalEntity, EntityType, Renderer, Client entry point |
🐸 Mob |
| Ep 6 Lucky Block |
A block with 5 random events on break |
onBreak() override, random events, ServerWorld |
🍀 Capstone |
📁 Complete Project Folder Structure
This is what your project looks like after completing all 6 episodes. Green files are ones you create everything else comes from the Fabric template.
crystalmod/ (your project root)
src/main/
java/com/example/crystalmod/
CrystalMod.java main entry point (modify in Ep 1)
CrystalModClient.java client entry point (create in Ep 5)
ModItems.java all item registrations (create in Ep 1)
ModBlocks.java all block registrations (create in Ep 2)
ModToolMaterials.java tool stats enum (create in Ep 4)
ModEntities.java entity type registration (create in Ep 5)
ModEntityRenderers.java renderer registration (create in Ep 5)
CrystalFrogEntity.java frog brain / AI (create in Ep 5)
CrystalFrogModel.java frog 3D model (create in Ep 5)
CrystalFrogRenderer.java frog texture renderer (create in Ep 5)
LuckyCrystalBlock.java lucky block logic (create in Ep 6)
resources/
fabric.mod.json mod metadata (modify in Ep 1 & 5)
assets/crystalmod/
lang/en_us.json item/block display names
textures/
item/crystal_gem.png 16✨16 gem texture (Ep 1)
item/magic_cookie.png 16✨16 cookie texture (Ep 3)
item/crystal_pickaxe.png 16✨16 pickaxe texture (Ep 4)
item/crystal_sword.png 16✨16 sword texture (Ep 4)
item/crystal_frog_spawn_egg.png (uses template no PNG needed)
block/crystal_block.png 16✨16 block texture (Ep 2)
block/lucky_crystal_block.png 16✨16 lucky block texture (Ep 6)
entity/crystal_frog.png 32✨32 frog skin (Ep 5)
models/
item/crystal_gem.json
item/magic_cookie.json
item/crystal_pickaxe.json
item/crystal_sword.json
item/crystal_frog_spawn_egg.json
item/crystal_block.json
item/lucky_crystal_block.json
block/crystal_block.json
block/lucky_crystal_block.json
blockstates/
crystal_block.json
lucky_crystal_block.json
data/crystalmod/
loot_table/
blocks/crystal_block.json drops crystal_gem (Ep 2)
blocks/lucky_crystal_block.json drops nothing events are reward (Ep 6)
entities/crystal_frog.json drops 1-3 crystal gems (Ep 5)
recipe/
crystal_block.json 9 gems → 1 block (Ep 2)
magic_cookie.json shapeless: wheat+sugar+gem → 4 cookies (Ep 3)
crystal_pickaxe.json shaped GGG·S·S (Ep 4)
crystal_sword.json shaped ·G··G··S· (Ep 4)
lucky_crystal_block.json 8 blocks + 1 gem (Ep 6)
data/minecraft/tags/block/mineable/
pickaxe.json adds crystal blocks to pickaxe tag (Ep 4)
💡
Green = files you create. Everything else (build.gradle, settings.gradle, gradle wrapper, ExampleMod.java) comes from the Fabric template and you'll either modify or ignore it.
🚀 Quick Setup Walkthrough
Follow these steps once before starting Episode 1. This uses the official Fabric template generator, a faster alternative to Episode 1's Steps 1-3 (which download the template as a plain ZIP from GitHub instead). Either way gets you the same starting project, pick whichever feels easier. If you use this generator method, set Package Name = com.example.crystalmod exactly as shown below so it matches every code sample in the series, then skip straight to Episode 1 Step 5.
1
Install Java JDK 21 from
Adoptium. Run the installer and follow the defaults. When done, open a terminal and type
java -version you should see
openjdk 21.
2
Install IntelliJ IDEA Community from
JetBrains. Scroll down to the Community Edition (it's free). Install with defaults.
3
Generate a Fabric mod template at
fabricmc.net/develop/template. Settings to use: Mod Name =
Crystal Mod, Package Name =
com.example.crystalmod, Minecraft Version =
1.21.1, check
Use Kotlin = OFF. Click Generate and download the ZIP.
4
Extract the ZIP and open the folder in IntelliJ: File → Open → select the extracted folder. When asked "Trust project?" click Trust Project.
5
Wait for Gradle sync. IntelliJ will automatically start downloading dependencies (the elephant icon in the bottom right spins). This takes 5-20 minutes on the first run. Wait for BUILD SUCCESSFUL in the Build panel.
6
Run genSources (optional but recommended): open the Gradle panel (right side) → Tasks → fabric → double-click genSources. This lets IntelliJ show you Minecraft's source code when you Ctrl+click things.
7
You're ready! Head to
Episode 1 and start at Step 5.
📄 Final fabric.mod.json
After Episode 5, your fabric.mod.json should look like this (with both main and client entry points):
fabric.mod.json complete version
{
"schemaVersion": 1,
"id": "crystalmod",
"version": "1.0.0",
"name": "Crystal Mod",
"description": "A crystal-themed mod with gems, blocks, food, tools, and a frog!",
"authors": ["YourName"],
"entrypoints": {
"main": ["com.example.crystalmod.CrystalMod"],
"client": ["com.example.crystalmod.CrystalModClient"]
},
"depends": {
"fabricloader": ">=0.15.0",
"fabric-api": "*",
"minecraft": "~1.21.1",
"java": ">=21"
}
}
❓ Common Questions
Why Fabric and not Forge?
Fabric is lighter, faster to set up, and has a cleaner API for beginners. Forge is more powerful for large mods but has a steeper learning curve. Most modern modding tutorials for 1.21+ use Fabric.
Can I use a different Minecraft version?
The code in this series is written for Minecraft 1.21.1. Other 1.21.x versions should mostly work but some class names and method signatures changed between minor versions. If you get errors, check the Fabric wiki for the specific version you're using.
Do I need to own Minecraft to mod it?
You need a legitimate copy of Minecraft Java Edition to run the mod in-game. However, you can write, compile, and build the mod without owning it the runClient Gradle task handles launching a test copy.
How do I share my mod with friends?
Build it with the Gradle task: Tasks → build → build. This creates a .jar file in build/libs/. Your friends need Fabric Loader and Fabric API installed, then they drop your .jar into their mods/ folder.
Where can I learn more after this series?
The Fabric Wiki is the best reference. The Fabric Discord has a #mod-dev channel where you can ask questions. Also check out the fabric-example-mod on GitHub for more example code.
🎓
Teachers: Each step includes a teacher's note with common mistakes to watch for and how to help students who are stuck, no extra setup needed.
