Hello Minecraft! Build Your First Custom Item Mod
JVDesignStudio - https://jvdesignstudio.co.uk/workshops/minecraft-first-item-mod.html

Offline reference pack for this workshop.
This is a companion copy of the build steps, so you can follow along without
the website. Open the workshop online for the interactive screenshots, videos
and the copy buttons.

What you build: Hello Minecraft! Build Your First Custom Item Mod

--------------------------------------------------------------------
STEP-BY-STEP BUILD
--------------------------------------------------------------------

## Download Java JDK 21
- Go to adoptium.net in your browser. This is the free official Java download site.
- Click the big Latest LTS Release button. Make sure it says Temurin 21 on it.
- It will automatically detect your operating system. Click Download.
- Run the downloaded installer. Click Next through the steps all defaults are fine.
- On the installer screen, make sure "Add to PATH" or "Set JAVA_HOME" is ticked if you see it.
- Once installed, open a Command Prompt (Windows) or Terminal (Mac). Type: java version and press Enter.
- You should see something like openjdk version "21.0.x". If you do, Java is ready!
- Go to jetbrains.com/idea/download. Scroll down to find IntelliJ IDEA Community Edition this is the free one.
- Click Download under Community Edition (not Ultimate that costs money).
- Run the installer. Click through the defaults. On the options screen, tick "Add 'bin' folder to PATH" if you see it.
- Open IntelliJ IDEA when it finishes. You'll see the welcome screen that's perfect.
- Go to github.com/FabricMC/fabric-example-mod
- Click the green Code button, then click Download ZIP.
- Save the ZIP somewhere easy to find like your Desktop or Documents folder.
- Right-click the ZIP file and choose Extract All (Windows) or double-click it (Mac). Extract it to your Documents folder.
- Rename the extracted folder from fabric-example-mod-main to CrystalMod. This is your mod's project folder!
- Open IntelliJ IDEA. On the welcome screen, click Open.
- Navigate to your CrystalMod folder and click OK (or Open).
- A dialog may ask "Trust and open project?" click Trust Project.
- IntelliJ 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.
- On 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.
- Wait for genSources to finish (another minute or two). Done when the run panel shows BUILD SUCCESSFUL.
- 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.

## Your project structure

## Update fabric.mod.json
- In the left panel, navigate to src → main → resources → fabric.mod.json and double-click it.
- Replace the entire file contents with the code below:
- Change "YourNameHere" to your actual name!
- Save the file with Ctrl+S (Windows) or Cmd+S (Mac).
- Now 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.
- Drag ExampleMod.java into the new crystalmod folder, then rename it to CrystalMod.java (right-click → Rename).
- Open CrystalMod.java from the file tree. Delete everything inside and replace with:
- Don't worry if ModItems shows red we haven't made that file yet! We'll fix that in the next step.
- Save the file.
- In the file tree, right-click the crystalmod package folder → New → Java Class. Name it ModItems and press Enter.
- Delete everything in the new file and paste this:
- Save the file. The red error on ModItems in CrystalMod.java should disappear now.
- If you see red underlines on any imports, hover over them and click Import class or press Alt+Enter to auto-fix them.
- 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.

## Create the texture folders
- In 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.
- Also inside crystalmod create: models → inside that item.
- Also inside crystalmod create a folder called lang.

## Draw your texture
- Go 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!
- Save/export it as crystal_gem.png into the assets/crystalmod/textures/item/ folder you just created.

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

## Create the language file
- Right-click the lang folder → New → File. Name it en_us.json. Paste this:
- In 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.
- Click the green ✨ Play button next to it. This builds your mod and launches Minecraft!
- Watch the output panel at the bottom. You should see Crystal Mod loaded! 💎 in the log that's your LOGGER message!
- When Minecraft opens, click Singleplayer → Create New World. Enable Creative Mode. Click Create World.
- Press E to open your inventory, then click the Creative Search tab (compass icon). Search for Crystal Gem. It should appear!
- Alternatively, open chat with T and type: /give @p crystalmod:crystal_gem and press Enter.

## Follow the same pattern
- In ModItems.java, add a new line after CRYSTAL_GEM: public static final Item CRYSTAL_DUST = registerItem("crystal_dust", new Item(new Item.Settings()));
- Inside registerModItems(), add: entries.add(CRYSTAL_DUST);
- Create crystal_dust.json in the models/item folder (same as crystal_gem.json, just change the texture path).
- Draw a new 16✨16 texture for it and save as crystal_dust.png in textures/item/.
- Add "item.crystalmod.crystal_dust": "Crystal Dust" to your en_us.json.
- Run Minecraft again and find your new item!
- 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
