minecraft-modding

Minecraft Modding Skill

概要

対応プラットフォーム：

プラットフォーム	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

MOD 固有のコードを書く前に、必ず gradle.properties または build.gradle でプラットフォームと Minecraft のバージョンを確認してください。

Minecraft 26.1 では Java 25 と、難読化されていないゲーム実行ファイルが導入されました。26.x プロジェクトでは、現行のローダージェネレーターまたはサンプル MOD をベースにし、 そのビルド構成を維持してください。このスキルにある 1.21.11 のマッピング、Loom プラグイン、 リマッピングタスク、Java 21 のコード例を 26.x プロジェクトにコピーしないでください。Fabric 26.x は リマッピングなしの Loom パスと公式名を使用します。NeoForge 26.x では、現行の NeoForge ジェネレーターを使用してください。特に 26.x と明記されたセクションを除き、詳細な API リファレンスはレガシーの 1.21.x の例を対象としています。

適用範囲

• Use when：Java/Kotlin の MOD コード、レジストリやイベント処理、ネットワーク通信、データ生成の設定、ローダー API に関するタスク。
• Do not use when：バニラのコマンドのみを使うロジック（minecraft-commands-scripting）または純粋なデータパック（minecraft-datapack）に関するタスク。
• Do not use when：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 は、プロジェクトで設定されているビルドタスクを実行します。配布候補となる MOD の 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 mappings	Fabric / Yarn mappings
ブロック	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 のレジストリキー

1.21.x のコード例では古い Registry.BLOCK／Registry.ITEM 定数を使わないでください。これらの名前は、このスキルの例では古いものです。

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 に登録
• BlockItem を ModItems.ITEMS / Registries.ITEM に登録
• Blockstate 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)）
• NeoForge では EntityRenderersEvent.RegisterRenderers、Fabric では EntityModelLayerRegistry にレンダラーを登録
• スポーンエッグアイテム（任意）
• スポーンルール／バイオームモディファイア

---

13. オープンソースの規約

• ライセンス：MIT または LGPL-3.0 — LICENSE ファイルと SPDX-License-Identifier ヘッダーを含めてください
• バージョン管理：{mod_version}+{mc_version}（例：2.0.0+1.21.11）
• 変更履歴：semver の注記を記載し、CHANGELOG.md を最新の状態に保ってください
• 公開：CurseForge / Modrinth 向けに gradle-modrinth または curseforgegradle プラグインを使用してください
• CI：./gradlew build と ./gradlew runGameTestServer を実行する GitHub Actions
• 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