minecraft-modding

name minecraft-modding description 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 This skill guides Codex through developing open-source Minecraft mods. Target 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. Treat the detailed API references here as the legacy 1.21.x lane 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. Treat the build output as compilation evidence, 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: 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: // 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 { public static final String MOD_ID = "mymod" ; public MyMod (IEventBus modEventBus) { ModBlocks.BLOCKS.register(modEventBus); ModItems.ITEMS.register(modEventBus); modEventBus.addListener( this ::commonSetup); } private void commonSetup (FMLCommonSetupEvent event) { // runs after all mods are registered } } // Block registration public class ModBlocks { public static final DeferredRegister. Blocks BLOCKS = DeferredRegister.createBlocks(MyMod.MOD_ID); public static final DeferredBlock<Block> MY_BLOCK = BLOCKS.registerSimpleBlock( "my_block" , BlockBehaviour.Properties.of() .mapColor(MapColor.STONE) .strength( 1.5f , 6.0f ) .sound(SoundType.STONE) .requiresCorrectToolForDrops()); } 8. Forge 1.20.1 Quick Patterns See full patterns in references/forge-1.20.1-api.md . // Main mod class @Mod(MyMod.MOD_ID) public class MyMod { public static final String MOD_ID = "mymod" ; public MyMod (FMLJavaModLoadingContext context) { IEventBus modEventBus = context.getModEventBus(); ModBlocks.BLOCKS.register(modEventBus); ModItems.ITEMS.register(modEventBus); modEventBus.addListener( this ::commonSetup); MinecraftForge.EVENT_BUS.register( this ); } private void commonSetup (FMLCommonSetupEvent event) { // runs after registries are prepared } } // Block registration public class ModBlocks { public static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MyMod.MOD_ID); public static final RegistryObject<Block> MY_BLOCK = BLOCKS.register( "my_block" , () -> new Block ( BlockBehaviour.Properties.of() .mapColor(MapColor.STONE) .strength( 1.5f , 6.0f ) .sound(SoundType.STONE) .requiresCorrectToolForDrops())); } 9. Fabric Quick Patterns Match the project's Minecraft version and mappings in the Fabric documentation . 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. // Main mod class public class MyMod implements ModInitializer { public static final String MOD_ID = "mymod" ; public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID); @Override public void onInitialize () { ModBlocks.initialize(); ModItems.register(); } } // Fabric 26.x with official Mojang mappings. Create the key before the object // so its properties receive the required id during construction. public final class ModBlocks { public static final ResourceKey<Block> MY_BLOCK_KEY = ResourceKey.create( Registries.BLOCK, Identifier.fromNamespaceAndPath(MyMod.MOD_ID, "my_block" ) ); public static final Block MY_BLOCK = register( MY_BLOCK_KEY, Block:: new , BlockBehaviour.Properties.of() .mapColor(MapColor.STONE) .strength( 1.5f , 6.0f ) .sound(SoundType.STONE) .requiresCorrectToolForDrops() ); private static Block register (ResourceKey<Block> key, Function<BlockBehaviour.Properties, Block> factory, BlockBehaviour.Properties properties) { Block block = factory.apply(properties.setId(key)); return Registry.register(BuiltInRegistries.BLOCK, key, block); } public static void initialize () {} } 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. // NeoForge – register data gen providers in GatherDataEvent @SubscribeEvent public static void gatherData (GatherDataEvent event) { DataGenerator gen = event.getGenerator(); PackOutput output = gen.getPackOutput(); ExistingFileHelper helper = event.getExistingFileHelper(); CompletableFuture<HolderLookup.Provider> lookupProvider = event.getLookupProvider(); gen.addProvider(event.includeClient(), new ModBlockStateProvider (output, helper)); gen.addProvider(event.includeClient(), new ModItemModelProvider (output, helper)); gen.addProvider(event.includeServer(), new ModRecipeProvider (output, lookupProvider)); gen.addProvider(event.includeServer(), new ModLootTableProvider (output, lookupProvider)); gen.addProvider(event.includeServer(), new ModBlockTagsProvider (output, lookupProvider, helper)); } 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