Minecraft Modding

Minecraft Modding Skill

Overview

Supported platforms:

Always confirm the platform and Minecraft version from gradle.properties or build.gradle before writing any mod-specific code.

Minecraft 26.1 introduced Java 25 and unobfuscated game executables. For 26.x projects, start from the current loader generator or example mod and preserve its build layout. Do not copy the 1.21.11 mapping, Loom plugin, remapping task, or Java 21 snippets in this skill into a 26.x project. Fabric 26.x uses the non-remapping Loom path and official names; NeoForge 26.x should start from the current NeoForge generator. The detailed API references cover legacy 1.21.x examples unless a section explicitly says 26.x.

Routing Boundaries

• Use when: the task is Java/Kotlin mod code, registry/event work, networking, datagen wiring, and loader APIs.
• Do not use when: the task is command-only vanilla logic (minecraft-commands-scripting) or pure datapacks (minecraft-datapack).
• Do not use when: the task targets Paper/Bukkit plugins (minecraft-plugin-dev).

1. Identifying the Platform

# NeoForge project signature
grep -r "net.neoforged" gradle.properties build.gradle settings.gradle 2>/dev/null | head -5

# Forge 1.20.1 project signature
grep -r "net.minecraftforge" gradle.properties build.gradle settings.gradle 2>/dev/null | head -5

# Fabric project signature
grep -r "fabric" gradle.properties build.gradle settings.gradle 2>/dev/null | head -5

# Read mod ID and version
cat gradle.properties

Key files per platform:

• NeoForge: src/main/resources/META-INF/neoforge.mods.toml, annotated @Mod main class
• Forge 1.20.1: src/main/resources/META-INF/mods.toml, net.minecraftforge:forge dependency
• Fabric: src/main/resources/fabric.mod.json, class implementing ModInitializer
• Architectury: common/, fabric/, neoforge/ subprojects

2. Build & Test Commands

# Build the mod jar
./gradlew build

# Run the Minecraft client to test
./gradlew runClient

# Run a dedicated server to test
./gradlew runServer

# Run game tests (NeoForge JUnit-style game tests)
./gradlew runGameTestServer

# Run data generation (generates JSON assets automatically)
./gradlew runData

# Remove this project's generated build outputs before a fresh rebuild
./gradlew clean

# Check for dependency updates (optional)
./gradlew dependencyUpdates

./gradlew build runs the project's configured build tasks. Candidate mod jars are usually under build/libs/, but task names and file names are project-specific. Check the build result, then identify the intended distributable before publishing it.

3. Project Layout (NeoForge)

src/
  main/
    java/<groupId>/<modid>/
      MyMod.java               ← @Mod entry point
      block/
        ModBlocks.java         ← DeferredRegister.Blocks
        MyCustomBlock.java
      item/
        ModItems.java          ← DeferredRegister.Items
      entity/
        ModEntities.java       ← DeferredRegister.Entities
      menu/                    ← custom GUI containers
      recipe/
      worldgen/
      datagen/
        ModDataGen.java        ← GatherDataEvent handler
        providers/
    resources/
      META-INF/
        neoforge.mods.toml     ← mod metadata (renamed from mods.toml in NeoForge 1.20.5+)
      assets/<modid>/
        blockstates/           ← JSON blockstate definitions
        models/
          block/               ← block model JSON
          item/                ← item model JSON
        items/                 ← 1.21.x item-definition JSON
        textures/
          block/               ← 16×16 PNG textures
          item/
        lang/
          en_us.json           ← translation strings
      data/<modid>/
        recipe/                ← crafting recipe JSON (26.x)
        loot_table/
          blocks/              ← per-block loot table JSON
        tags/
          blocks/
          items/

4. Project Layout (Forge 1.20.1)

Use this layout only when minecraft_version=1.20.1 and the project depends on net.minecraftforge:forge. Forge 1.20.1 is not NeoForge: keep mods.toml, net.minecraftforge.* imports, Java 17, and ForgeGradle 6 patterns.

src/
  main/
    java/<groupId>/<modid>/
      MyMod.java               <- @Mod entry point
      block/
        ModBlocks.java         <- DeferredRegister.Blocks
      item/
        ModItems.java          <- DeferredRegister.Items
      datagen/
        ModDataGen.java        <- GatherDataEvent handler
    resources/
      META-INF/
        mods.toml              <- Forge metadata
      assets/<modid>/          <- client assets
      data/<modid>/            <- server data using 1.20.1 paths

See references/forge-1.20.1-api.md before editing Forge 1.20.1 projects.

5. Project Layout (Fabric)

src/
  main/
    java/<groupId>/<modid>/
      MyMod.java               ← implements ModInitializer
      client/
        MyModClient.java       ← implements ClientModInitializer
      block/
      item/
      mixin/                   ← Mixin classes
    resources/
      fabric.mod.json
      assets/<modid>/          ← same as NeoForge
      data/<modid>/            ← same as NeoForge
      <modid>.mixins.json      ← mixin configuration

6. Core Concepts Cheatsheet

Sides

• Physical client – the game client JAR (has rendering code)
• Physical server – the dedicated server JAR (no rendering)
• Logical client – the client thread (handles rendering, input)
• Logical server – the server thread (handles world simulation)
• Code decorated with @OnlyIn(Dist.CLIENT) (NeoForge) or @Environment(EnvType.CLIENT) (Fabric) must NEVER run on the server.

Registries

Everything in Minecraft lives in a registry. Always register objects; never construct them at field initializer time outside a registry call. Use the mapping-appropriate registry constants for the loader you are editing:

Do not copy older Registry.BLOCK / Registry.ITEM constants into 1.21.x code; those names are stale for the examples in this skill.

ResourceLocation / Identifier

Every registry entry needs a namespaced ID:

// NeoForge / vanilla Java
ResourceLocation id = ResourceLocation.fromNamespaceAndPath("mymod", "my_block");

// Fabric with Yarn mappings
Identifier id = Identifier.of("mymod", "my_block");

7. NeoForge Quick Patterns (26.x)

For 26.x, use the explicitly labelled 26.x sections in references/common-patterns.md and select the project's exact version in the NeoForge documentation. references/neoforge-api.md contains legacy 1.21.x / Java 21 patterns only; do not copy its dependency pins into a 26.x project.

// Main mod class
@Mod(MyMod.MOD_ID)
public class MyMod {