开发与工程 · SKILL.md

minecraft-modding

minecraft-modding

【开发与工程】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.

独立 GitHub 快照 · 自动分类 · 以原作者文档为准

Jjahrome907 / minecraft-agent-skillsMIT

技能说明

GitHub

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

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

# 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.4+ 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/
          block/
          item/

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:

// 26.x official names (NeoForge and Fabric)
Identifier id = Identifier.fromNamespaceAndPath("mymod", "my_block");

// Older Mojang mappings use ResourceLocation; keep the project's version.
// Legacy 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

Use the project's configured data providers. Current NeoForge uses GatherDataEvent.Client / .Server and event.createProvider(...); the MDK normally generates both asset and data providers with runClientData. See the version-matched resource guide before wiring providers. Keep Fabric and older projects on their own datagen entrypoints and Gradle tasks, then inspect 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:

When adding a new item:

Item subclass (or use new Item(properties))
Register in ModItems / Registries.ITEM
Item model JSON
1.21.4+ 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

MAKE IT PART OF YOUR WORKFLOW

安装技能

TERMINAL

npx skills add jahrome907/minecraft-agent-skills --skill minecraft-modding

复制命令到本地终端执行；安装前请先审查源代码和许可证。

ZIP · 完整技能目录，含资源与许可证

SKILL.md · 仅技能说明原文

仓库 Star: 未同步
许可证: MIT
版本 / 分支: HEAD · b741b26b
仓库更新时间: 未同步

安装前，请检查技能脚本与权限。

源代码