minecraft-modding

Minecraft Modding 技能

概述

支持的平台：

平台	MC 版本	Java	构建系统
NeoForge	当前为 26.x；保留 1.21.11 示例	当前为 Java 25；1.21.x 使用 Java 21	Gradle + ModDevGradle
Forge	旧版支持 1.20.1	Java 17	Gradle + ForgeGradle 6
Fabric	当前为 26.x；保留 1.21.11 示例	当前为 Java 25；1.21.x 使用 Java 21	Gradle + Fabric Loom
Architectury（多加载器）	26.x 或 1.21.x	与 Minecraft 版本一致	Gradle + Architectury Loom

编写任何特定于模组的代码前，务必先从 gradle.properties 或 build.gradle 确认平台和 Minecraft 版本。

Minecraft 26.1 引入了 Java 25 和未混淆的游戏可执行文件。对于 26.x 项目，请从当前加载器生成器或示例模组开始，并保留其构建布局。不要将此技能中的 1.21.11 映射、Loom 插件、重映射任务或 Java 21 代码片段复制到 26.x 项目中。Fabric 26.x 使用 非重映射的 Loom 路径和官方名称；NeoForge 26.x 应从当前 NeoForge 生成器开始。除非某一节明确注明适用于 26.x，否则详细 API 参考涵盖的是旧版 1.21.x 示例。

适用范围

• 使用场景：任务涉及 Java/Kotlin 模组代码、注册表/事件工作、网络、数据生成接线和加载器 API。
• 不适用场景：任务仅涉及原版命令逻辑（minecraft-commands-scripting）或纯数据包（minecraft-datapack）。
• 不适用场景：任务针对 Paper/Bukkit 插件（minecraft-plugin-dev）。

---

1. 识别平台

# 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

各平台的关键文件：

• NeoForge：src/main/resources/META-INF/neoforge.mods.toml，带注解的 @Mod 主类
• Forge 1.20.1：src/main/resources/META-INF/mods.toml，net.minecraftforge:forge 依赖项
• Fabric：src/main/resources/fabric.mod.json，实现 ModInitializer 的类
• Architectury：common/、fabric/、neoforge/ 子项目

---

2. 构建与测试命令

# 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 会运行项目配置的构建任务。候选模组 jar 通常位于 build/libs/ 下，但任务名称和文件名因项目而异。 检查构建结果，然后在发布前确定目标 分发文件。

---

3. 项目布局（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. 项目布局（Forge 1.20.1）

仅当 minecraft_version=1.20.1 且项目依赖 net.minecraftforge:forge 时使用此布局。Forge 1.20.1 并非 NeoForge：请保留 mods.toml、 net.minecraftforge.* 导入、Java 17 和 ForgeGradle 6 模式。

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

编辑 Forge 1.20.1 项目前，请参阅 references/forge-1.20.1-api.md。

5. 项目布局（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. 核心概念速查表

端

• 物理客户端 – 游戏客户端 JAR（包含渲染代码）
• 物理服务端 – 专用服务端 JAR（不含渲染）
• 逻辑客户端 – 客户端线程（处理渲染和输入）
• 逻辑服务端 – 服务端线程（处理世界模拟）
• 使用 @OnlyIn(Dist.CLIENT)（NeoForge）或 @Environment(EnvType.CLIENT)（Fabric）标注的代码 绝不能在服务端运行。

注册表

Minecraft 中的所有内容都位于注册表中。始终注册对象；绝不要在注册表调用之外的字段初始化器中构造对象。请使用与你正在编辑的加载器相匹配的注册表常量：

类型	NeoForge / Mojang 映射	Fabric / Yarn 映射
方块	BuiltInRegistries.BLOCK	Registries.BLOCK
物品	BuiltInRegistries.ITEM	Registries.ITEM
实体类型	BuiltInRegistries.ENTITY_TYPE	Registries.ENTITY_TYPE
方块实体类型	BuiltInRegistries.BLOCK_ENTITY_TYPE	Registries.BLOCK_ENTITY_TYPE
菜单 / 屏幕处理器类型	BuiltInRegistries.MENU	Registries.SCREEN_HANDLER
声音事件	BuiltInRegistries.SOUND_EVENT	Registries.SOUND_EVENT
生物群系	Registries.BIOME 注册表键	RegistryKeys.BIOME 注册表键

不要将旧版 Registry.BLOCK / Registry.ITEM 常量复制到 1.21.x 代码中；这些名称对于本技能中的示例来说已经过时。

ResourceLocation / Identifier

每个注册表条目都需要带命名空间的 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 快速模式（26.x）

对于 26.x，请使用 references/common-patterns.md 中明确标注为 26.x 的部分，并在 NeoForge 文档中选择项目的确切版本。references/neoforge-api.md 仅包含适用于旧版 1.21.x / Java 21 的模式；不要将其中的依赖版本固定项复制到 26.x 项目中。

// 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 快速模式

完整模式请参阅 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 快速模式

请根据项目的 Minecraft 版本和映射，参阅 Fabric 文档。references/fabric-api.md 仅包含适用于旧版 1.21.x / Java 21 的模式。references/common-patterns.md 中明确标注为 26.x 的部分使用 NeoForge 语法；请参照确切的 Fabric API 进行适配，而不要照搬加载器专属类或旧版依赖版本固定项。

// 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() {}
}

从 Fabric 初始化器中调用 ModBlocks.initialize()。Yarn 命名的 1.21.11 示例仍保留在 references/fabric-api.md 中；不要将这些名称与此 26.x 模式混用。

---

10. JSON 资源模板

务必为每个已注册的方块 / 物品提供匹配的 JSON 资源。Codex 应与 Java 代码一并生成或更新这些文件。 对于 Forge 1.20.1，在创建战利品表或标签之前，请查阅 references/forge-1.20.1-api.md，确认旧版服务器数据目录名称。

完整 JSON 模板请参阅 references/common-patterns.md：

• 方块状态 JSON
• 方块模型 JSON（立方体、台阶、楼梯、栅栏、门、活板门等）
• 物品模型 JSON
• 战利品表 JSON
• 配方 JSON（crafting_shaped、crafting_shapeless、smelting、blasting、stonecutting）
• 语言文件（en_us.json）条目
• 标签 JSON

---

11. 数据生成

使用项目配置的数据提供器。当前版本的 NeoForge 使用 GatherDataEvent.Client / .Server 和 event.createProvider(...)；MDK 通常会通过 runClientData 同时生成资源和数据提供器。接入提供器之前，请参阅与版本相匹配的资源指南。Fabric 和旧版项目应继续使用各自的数据生成入口点和 Gradle 任务，然后检查生成的文件。 对于 Forge 1.20.1，请使用 references/forge-1.20.1-api.md 中的模组事件总线注册方式、GatherDataEvent 签名、提供器类和旧版输出路径。

---

12. 常见任务检查清单

添加新方块时：

• Block 子类（或使用带属性的原版 Block）
• 在 ModBlocks.BLOCKS / Registries.BLOCK 中注册
• 在 ModItems.ITEMS / Registries.ITEM 中注册 BlockItem
• 方块状态 JSON → assets/<modid>/blockstates/<name>.json
• 方块模型 JSON → assets/<modid>/models/block/<name>.json
• 物品模型 JSON → assets/<modid>/models/item/<name>.json（或继承自方块）
• 1.21.4+ 物品定义 → assets/<modid>/items/<name>.json，指向物品或方块模型
• 纹理 PNG → assets/<modid>/textures/block/<name>.png
• 战利品表 JSON -> 1.21.x：data/<modid>/loot_table/blocks/<name>.json；Forge 1.20.1：data/<modid>/loot_tables/blocks/<name>.json
• 标签 -> 1.21.x：data/<modid>/tags/block/ 和 tags/item/；Forge 1.20.1：data/<modid>/tags/blocks/ 和 tags/items/
• 在 en_us.json 中添加语言条目
• 若硬度 > 0，添加所需工具挖掘标签
• 不要混用 Forge 1.20.1 复数服务器数据路径与 1.21.x 单数服务器数据路径

添加新物品时：

• Item 子类（或使用 new Item(properties)）
• 在 ModItems / Registries.ITEM 中注册
• 物品模型 JSON
• 1.21.4+ 物品定义 → assets/<modid>/items/<name>.json
• 纹理 PNG
• 语言条目
• 创造模式物品栏注册（NeoForge/Forge：BuildCreativeModeTabContentsEvent；Fabric：ItemGroupEvents）
• 若可合成，添加配方 JSON（26.x 使用 data/<modid>/recipe/；对 1.21.x 项目，请先参阅对应版本的配方参考）

添加新实体时：

• 实体类（继承适当的基类：Mob、Animal、TamableAnimal 等）
• 注册 EntityType
• 渲染器类（@OnlyIn(Dist.CLIENT)）
• 模型类（@OnlyIn(Dist.CLIENT)）
• 在 EntityRenderersEvent.RegisterRenderers（NeoForge）或 EntityModelLayerRegistry（Fabric）中注册渲染器
• 生成蛋物品（可选）
• 生成规则 / 生物群系修改器

---

13. 开源约定

• 许可证：MIT 或 LGPL-3.0 — 包含 LICENSE 文件和 SPDX-License-Identifier 标头
• 版本号：{mod_version}+{mc_version}（例如：2.0.0+1.21.11）
• 变更日志：及时更新 CHANGELOG.md，记录语义化版本说明
• 发布：使用 gradle-modrinth 或 curseforgegradle 插件发布到 CurseForge / Modrinth
• CI：使用 GitHub Actions 运行 ./gradlew build 和 ./gradlew runGameTestServer
• PR 约定：每个 PR 限定为单一功能；Java 代码更改时一并提交资源文件

---

14. 参考资料

• NeoForge API 模式和事件系统：./references/neoforge-api.md
• Forge 1.20.1 API 模式和 MDK 工作流：./references/forge-1.20.1-api.md
• Fabric API 模式和 Mixin 指南：./references/fabric-api.md
• 方块、物品、配方、命令、GUI、数据生成：./references/common-patterns.md
• NeoForge 官方文档：https://docs.neoforged.net/
• Fabric 开发者文档：https://docs.fabricmc.net/develop/
• Architectury（多加载器）：https://docs.architectury.dev/
• Minecraft Wiki（数据格式）：https://minecraft.wiki/w/Java_Edition_data_values