Create, modify, debug, or migrate Minecraft mods for current NeoForge or Fabric 26.x, legacy 1.21.x, and Forge 1.20.1. Use for loader-based gameplay code and assets; use minecraft-multiloader when one codebase must target both modern loaders.

Minecraft Modding Skill Overview Supported platforms: Platform MC Version Java Build System NeoForge 26.x current; 1.21.11 examples retained Java 25 current; Java 21 on 1.21.x Gradle + ModDevGradle Forge 1.20.1 legacy lane Java 17 Gradle + ForgeGradle 6 Fabric 26.x current; 1.21.11 examples retained Java 25 current; Java 21 on 1.21.x Gradle + Fabric Loom Architectury (multiloader) 26.x or 1.21.x Match Minecraft Gradle + Architectury Loom 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 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 ./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) 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. See references/forge 1.20.1 api.md before editing Forge 1.20.1 projects. 5. Project Layout (Fabric) 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: Type NeoForge / Mojang mappings Fabric / Yarn mappings Blocks BuiltInRegistries.BLOCK Registries.BLOCK Items BuiltInRegistries.ITEM Registries.ITEM Entity types BuiltInRegistries.ENTITY TYPE Registries.ENTITY TYPE Block entity types BuiltInRegistries.BLOCK ENTITY TYPE Registries.BLOCK ENTITY TYPE Menu / screen handler types BuiltInRegistries.MENU Registries.SCREEN HANDLER Sound events BuiltInRegistries.SOUND EVENT Registries.SOUND EVENT Biomes Registries.BIOME registry keys RegistryKeys.BIOME registry keys 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: 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](https://docs.neoforged.net/docs/gettingstarted/). references/neoforge api.md contains legacy 1.21.x / Java 21 patterns only; do not copy its dependency pins into a 26.x project. 8. Forge 1.20.1 Quick Patterns See full patterns in references/forge 1.20.1 api.md . 9. Fabric Quick Patterns Match the project's Minecraft version and mappings in the [Fabric documentation](https://docs.fabricmc.net/develop/). references/fabric api.md contains legacy 1.21.x / Java 21 patterns only. The explicitly labelled 26.x sections in references/common patterns.md use NeoForge syntax; adapt them against the exact Fabric API rather than copying loader specific classes or legacy dependency pins. Call ModBlocks.initialize() from the Fabric initializer. The Yarn named 1.21.11 examples remain in references/fabric api.md ; do not mix those names with this 26.x pattern. 10. JSON Asset Templates Always provide matching JSON assets for every registered block/item. Codex should generate or update these files alongside Java code. For Forge 1.20.1, check references/forge 1.20.1 api.md for legacy server data directory names before creating loot tables or tags. See references/common patterns.md for full JSON templates for: Blockstate JSON Block model JSON (cube, slab, stairs, fence, door, trapdoor, etc.) Item model JSON Loot table JSON Recipe JSON (crafting shaped, crafting shapeless, smelting, blasting, stonecutting) Language file ( en us.json ) entries Tag JSON 11. Data Generation Prefer data generation over hand authored JSON for maintainability. Run data generation with ./gradlew runData , then commit the generated files. For Forge 1.20.1, use the mod event bus registration, GatherDataEvent signature, provider classes, and legacy output paths from references/forge 1.20.1 api.md . 12. Common Tasks Checklist When adding a new block : [ ] Block subclass (or use vanilla Block with properties) [ ] Register in ModBlocks.BLOCKS / Registries.BLOCK [ ] Register BlockItem in ModItems.ITEMS / Registries.ITEM [ ] Blockstate JSON → assets/<modid /blockstates/<name .json [ ] Block model JSON → assets/<modid /models/block/<name .json [ ] Item model JSON → assets/<modid /models/item/<name .json (or inherits from block) [ ] 1.21.x item definition → assets/<modid /items/<name .json , pointing at the item or block model [ ] Texture PNG → assets/<modid /textures/block/<name .png [ ] Loot table JSON 1.21.x: data/<modid /loot table/blocks/<name .json ; Forge 1.20.1: data/<modid /loot tables/blocks/<name .json [ ] Tags 1.21.x: data/<modid /tags/block/ and tags/item/ ; Forge 1.20.1: data/<modid /tags/blocks/ and tags/items/ [ ] Language entry in en us.json [ ] Mine with correct tool tag if hardness 0 [ ] Do not mix Forge 1.20.1 plural server data paths with 1.21.x singular server data paths When adding a new item : [ ] Item subclass (or use new Item(properties) ) [ ] Register in ModItems / Registries.ITEM [ ] Item model JSON [ ] 1.21.x item definition → assets/<modid /items/<name .json [ ] Texture PNG [ ] Language entry [ ] Creative tab registration (NeoForge/Forge: BuildCreativeModeTabContentsEvent ; Fabric: ItemGroupEvents ) [ ] Recipe JSON if craftable ( data/<modid /recipe/ for 26.x; see the version specific recipe reference before using a 1.21.x project) When adding a new entity : [ ] Entity class (extends appropriate base: Mob , Animal , TamableAnimal , etc.) [ ] EntityType registration [ ] Renderer class ( @OnlyIn(Dist.CLIENT) ) [ ] Model class ( @OnlyIn(Dist.CLIENT) ) [ ] Register renderer in EntityRenderersEvent.RegisterRenderers (NeoForge) or EntityModelLayerRegistry (Fabric) [ ] Spawn egg item (optional) [ ] Spawn rules / biome modifier 13. Open Source Conventions License : MIT or LGPL 3.0 — include LICENSE file and SPDX License Identifier header Versioning : {mod version}+{mc version} (e.g., 2.0.0+1.21.11 ) Changelog : Keep CHANGELOG.md up to date with semver notes Publishing : Use gradle modrinth or curseforgegradle plugins for CurseForge / Modrinth CI : GitHub Actions with ./gradlew build and ./gradlew runGameTestServer PR conventions : Keep PRs scoped to a single feature; include asset files with Java changes 14. References NeoForge API patterns and event system: ./references/neoforge api.md Forge 1.20.1 API patterns and MDK workflow: ./references/forge 1.20.1 api.md Fabric API patterns and mixin guide: ./references/fabric api.md Blocks, items, recipes, commands, GUIs, datagen: ./references/common patterns.md NeoForge official docs: https://docs.neoforged.net/ Fabric developer docs: https://docs.fabricmc.net/develop/ Architectury (multiloader): https://docs.architectury.dev/ Minecraft Wiki (data formats): https://minecraft.wiki/w/Java Edition data values

minecraft-modding