1211 neoforge modding

概要

このSkillは Minecraft 1.21.1 NeoForge 向けMod開発の標準パターンと落とし穴をまとめたものです。

✅ やるべきこと

1. DeferredRegister + DeferredHolder（または型付きAPI）を使う — DeferredRegister.createBlocks(MODID), DeferredRegister.createItems(MODID) などの型付きAPIが利用可能。
2. DataGen を使う — 手書きJSONはミスとメンテナンスコストが爆発する。
3. Parchmentでパラメータ名を補完 — neoForge { parchment { ... } } で設定。無効でも動作するが可読性が下がる。
4. すべてのDeferredRegisterをメインModクラスのコンストラクタで modBus にregisterする — コンストラクタ引数 IEventBus modEventBus を使う。
5. Block登録時はBlockItemも登録する — DeferredRegister.Items.registerSimpleBlockItem("name", BLOCK) で簡易化可能。
6. ResourceLocation.fromNamespaceAndPath(MODID, "path") を使う — new ResourceLocation(...) は非推奨。
7. level.isClientSide() で論理サイド判定 — メソッド呼び出し形式（1.21.1以降）。
8. Networkingのハンドラでは context.enqueueWork() でメインスレッドに戻す — ネットワークスレッドでワールド変更を行うとクラッシュ。
9. Capability取得は直接メソッド呼び出し — LazyOptional は廃止。level.getCapability(...) / entity.getCapability(...) で直接取得。
10. BlockEntityのデータ変更時は setChanged() + level.sendBlockUpdated() を呼ぶ — どちらか欠けると保存/同期されない。
11. Data ComponentsをItemStackのデータに使う — persistent(Codec) + networkSynchronized(StreamCodec) の両方を提供する。
12. Data AttachmentはBlockEntity/Entity/Chunk用 — ItemStackには使えない。ItemStackにはData Componentを使う。
13. sourceSets.main.resources { srcDir 'src/generated/resources' } を忘れない — DataGenの出力が読み込まれなくなる。
14. @EventBusSubscriber でbus自動検出 — bus の明示が不要になったが、特定バスに限定したい場合 bus = Bus.MOD または Bus.GAME を指定。

❌ やってはいけないこと

1. @OnlyIn をModコードで使わない — NeoForge内部専用。クライアント限定は @Mod(value = MODID, dist = Dist.CLIENT) または FMLClientSetupEvent で分離。
2. new ResourceLocation(...) を使わない — ResourceLocation.fromNamespaceAndPath() を使うこと。
3. CapabilityにLazyOptionalを使わない — 1.21.1では廃止。getCapability() は直接呼び出し。
4. Data AttachmentをItemStackに使わない — ItemStackにはData Componentを使う。
5. mods.toml ではなく neoforge.mods.toml — ファイル名を間違えるとModが認識されない。
6. ModDevGradleの dependencies {} に minecraft や neoforge を書かない — neoForge { version = ... } ブロックで解決される。
7. runClientクラッシュ後は ./gradlew --stop — Daemonがポートを占有していることがある。
8. Data Componentの Codec / StreamCodec を忘れない — ないとコンパイルエラーまたは実行時エラーになる。

開発ワークフロー（新規Mod作成時）

• 1. NeoForge MDK（1.21.1）を入手し、Gradleプロジェクトとしてインポート
• 2. gradle.properties / build.gradle / neoforge.mods.toml を確認・編集
• 3. メインModクラス（@Mod）と DeferredRegister + DeferredHolder のセットアップ
• 4. Block/Item/Entity などの登録とプロパティ定義
• 5. Data Provider（Recipe, LootTable, BlockState, Tags, Data Components）の実装
• 6. 必要に応じてNetworking（Payload System）、Capability、Data Attachment、WorldGenを追加
• 7. runClient / runData で動作確認

よく使うGradleタスク

./gradlew build              # 配布用jar生成
./gradlew runClient          # クライアント起動
./gradlew runServer          # サーバー起動
./gradlew runData            # DataGen実行
./gradlew runGameTestServer  # GameTest実行
./gradlew clean              # ビルドキャッシュ削除

一般的なタスクチェックリスト

Blockを追加する

1. DeferredRegister.Blocks → DeferredBlock<Block> を登録
2. 同じ名前で DeferredRegister.Items → BlockItem を登録（registerSimpleBlockItem で簡易化）
3. BlockState JSON / Block Model / Texture（DataGen推奨）
4. 必要に応じて BlockEntity + BlockEntityType を登録
5. BlockTagsProvider でツール要件・採掘判定を追加

Itemを追加する

1. DeferredRegister.Items → DeferredItem<Item> を登録
2. Item Model / Texture（DataGen推奨）
3. 必要に応じて DataComponentType を登録
4. LanguageProvider で表示名を追加

Entityを追加する

1. DeferredRegister<EntityType<?>> → DeferredHolder<EntityType<?>, EntityType<T>> を登録
2. EntityAttributeCreationEvent で属性（HP・移動速度など）を設定
3. EntityRenderersEvent.RegisterRenderers でRendererを登録（クライアント限定）
4. Spawn Placements（自然スポーン条件）を設定

Recipeを追加する

1. RecipeProvider を継承したクラスを作成
2. buildRecipes(RecipeOutput) でレシピを定義
3. ./gradlew runData を実行してJSONを生成

詳細リファレンス

トピック	ファイル	読むタイミング
環境構築・ModDevGradle・MDK	references/SETUP.md	プロジェクト初期セットアップ時
Registry・Event・Sidednessの基礎	references/CORE_CONCEPTS.md	メインクラスを書く前
Block・Item・BlockEntity・Menu・Data Componentの実装	references/BLOCKS_AND_ITEMS.md	Block/Itemを追加する際
DataGen（Recipe, LootTable, Tags, Models, Datapack Registry）	references/DATA.md	JSONを書く必要がある際
Networking（Payload System）	references/NETWORKING.md	GUI同期・サーバー/クライアント通信が必要な際
Capability・Data Attachment・描画・WorldGen	references/ADVANCED.md	高度な機能実装時
コマンド（Brigadier）	references/COMMANDS.md	独自コマンドを追加する際
GameTest（自動テスト）	references/GAMETEST.md	統合テストを書く際
WorldGen（ワールド生成）	references/WORLDGEN.md	鉱脈・構造物・バイオームを追加する際
Resource Pack（モデル・テクスチャ・サウンド・言語）	references/RESOURCE_PACK.md	アセットファイルを手書きする際
Datapack（バニラデータ形式）	references/DATAPACK.md	ModがデータパックJSONを内包する際
Image Generation（テクスチャ・プロモーションアート）	references/IMAGEGEN.md	画像生成・ブリーフ作成時
CI・リリース・バージョン管理	references/CI_RELEASE.md	GitHub Actions・Modrinth・CurseForge連携
クラス・メソッド早見表	references/QUICK_REFERENCE.md	クラス名を忘れた際
クラッシュ対応・ログの読み方	references/TROUBLESHOOTING.md	ビルド/実行が失敗した際

Scripts

Script	Purpose
scripts/check-build.sh	JDK, Gradle, key files確認 + clean build
scripts/validate-datapack.sh	datapack JSON, pack.mcmeta, function tag参照の検証
scripts/validate-resource-pack.sh	mod asset JSON, model/texture/sound参照の検証
scripts/scaffold-asset-brief.sh	テクスチャ/プロモーションアート用Markdown brief生成
scripts/validate-test-layout.sh	JUnit 5 / GameTest / MockBukkit プロジェクトレイアウト検証