# Minecraft Modding > Full-stack Minecraft mod development skill for both NeoForge (1.21+) and Fabric (1.21+). Scaffolds new mods, adds custom blocks, items, entities, recipes, commands, GUIs, dimensions, and data generation. Knows the NeoForge DeferredRegister + event-bus system and the Fabric Registry + ModInitializer system. Use when the user asks to create a Minecraft mod, add a feature to an existing mod, fix a mod bug, generate JSON assets/data, or migrate between modding platforms. Prefer NeoForge unless the user specifies Fabric or Multiloader. - Skill: `jahrome907/minecraft-modding` (Agent Skill) - Install (CLI): `npx skillmds@latest add jahrome907/minecraft-modding` - Raw SKILL.md: https://api.skillmd.com/api/skills/jahrome907/minecraft-modding/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Jahrome907 (https://skillmd.com/u/jahrome907) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/jahrome907/minecraft-modding --- # Minecraft Modding Skill ## Overview This skill guides Codex through developing open-source Minecraft mods. Target platforms: | Platform | MC Version | Java | Build System | |---|---|---|---| | **NeoForge** | 1.21.1 / 1.21.4 / 1.21.5 | Java 21 | Gradle + ModDevGradle | | **Fabric** | 1.21.1 / 1.21.4 | Java 21 | Gradle + Fabric Loom | | **Architectury** (multiloader) | 1.21.x | Java 21 | Gradle + Architectury Loom | Always confirm the platform and Minecraft version from `gradle.properties` or `build.gradle` before writing any mod-specific code. ### 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 ```bash # NeoForge project signature grep -r "net.neoforged" 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 - **Fabric**: `src/main/resources/fabric.mod.json`, class implementing `ModInitializer` - **Architectury**: `common/`, `fabric/`, `neoforge/` subprojects --- ## 2. Build & Test Commands ```bash # 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 # Clean build cache ./gradlew clean # Check for dependency updates (optional) ./gradlew dependencyUpdates ``` After `./gradlew build`, the mod jar is at: `build/libs/-.jar` --- ## 3. Project Layout (NeoForge) ``` src/ main/ java/// MyMod.java ← @Mod entry point block/ ModBlocks.java ← DeferredRegister MyCustomBlock.java item/ ModItems.java ← DeferredRegister entity/ ModEntities.java ← DeferredRegister> 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// blockstates/ ← JSON blockstate definitions models/ block/ ← block model JSON item/ ← item model JSON textures/ block/ ← 16×16 PNG textures item/ lang/ en_us.json ← translation strings data// recipes/ ← crafting recipe JSON loot_table/ blocks/ ← per-block loot table JSON tags/ blocks/ items/ ``` ## 4. Project Layout (Fabric) ``` src/ main/ java/// MyMod.java ← implements ModInitializer client/ MyModClient.java ← implements ClientModInitializer block/ item/ mixin/ ← Mixin classes resources/ fabric.mod.json assets// ← same as NeoForge data// ← same as NeoForge .mixins.json ← mixin configuration ``` --- ## 5. 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. - Blocks → `Registry.BLOCK` - Items → `Registry.ITEM` - Entity types → `Registry.ENTITY_TYPE` - Block entity types → `Registry.BLOCK_ENTITY_TYPE` - Menu types → `Registry.MENU` (NeoForge) / `Registry.MENU_TYPE` (Fabric) - Sound events → `Registry.SOUND_EVENT` - Biomes → `Registry.BIOME` ### ResourceLocation / Identifier Every registry entry needs a namespaced ID: ```java // NeoForge / vanilla Java ResourceLocation id = ResourceLocation.fromNamespaceAndPath("mymod", "my_block"); // Fabric (same class, same API in 1.21) Identifier id = Identifier.of("mymod", "my_block"); ``` --- ## 6. NeoForge Quick Patterns See full patterns in `references/neoforge-api.md`. ```java // 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 } } ``` ```java // Block registration public class ModBlocks { public static final DeferredRegister BLOCKS = DeferredRegister.create(BuiltInRegistries.BLOCK, MyMod.MOD_ID); public static final DeferredBlock MY_BLOCK = BLOCKS.registerSimpleBlock("my_block", BlockBehaviour.Properties.of() .mapColor(MapColor.STONE) .strength(1.5f, 6.0f) .sound(SoundType.STONE) .requiresCorrectToolForDrops()); } ``` --- ## 7. Fabric Quick Patterns See full patterns in `references/fabric-api.md`. ```java // 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.register(); ModItems.register(); } } ``` ```java // Block registration public class ModBlocks { public static final Block MY_BLOCK = new Block( AbstractBlock.Settings.create() .mapColor(MapColor.STONE) .strength(1.5f, 6.0f) .sounds(BlockSoundGroup.STONE) .requiresTool() ); public static void register() { Registry.register(Registries.BLOCK, Identifier.of(MyMod.MOD_ID, "my_block"), MY_BLOCK); } } ``` --- ## 8. JSON Asset Templates Always provide matching JSON assets for every registered block/item. Codex should generate or update these files alongside Java code. 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 --- ## 9. Data Generation Prefer data generation over hand-authored JSON for maintainability. ```java // 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 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. --- ## 10. 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//blockstates/.json` - [ ] Block model JSON → `assets//models/block/.json` - [ ] Item model JSON → `assets//models/item/.json` (or inherits from block) - [ ] Texture PNG → `assets//textures/block/.png` - [ ] Loot table JSON → `data//loot_table/blocks/.json` - [ ] Language entry in `en_us.json` - [ ] Mine-with-correct-tool tag if hardness > 0 When adding a **new item**: - [ ] `Item` subclass (or use `new Item(properties)`) - [ ] Register in `ModItems` / `Registries.ITEM` - [ ] Item model JSON - [ ] Texture PNG - [ ] Language entry - [ ] Creative tab registration (NeoForge: `BuildCreativeModeTabContentsEvent`; Fabric: `ItemGroupEvents`) - [ ] Recipe JSON if craftable 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 --- ## 11. 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.1`) - **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 --- ## 12. References - NeoForge API patterns and event system: `.agents/skills/minecraft-modding/references/neoforge-api.md` - Fabric API patterns and mixin guide: `.agents/skills/minecraft-modding/references/fabric-api.md` - Blocks, items, recipes, commands, GUIs, datagen: `.agents/skills/minecraft-modding/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