minecraft-mixin

概要

Mixin は既存クラスの動作を変更する強力なツール。Forge/NeoForge に同梱済み（追加依存不要）。

✅ やるべきこと（優先順位順）

1. @Inject を最優先 — 元のコードを破壊しない。他Modとの競合が最も少ない。
2. @Unique を徹底 — Mixin内で追加するフィールド・メソッドには必ず付与。名前衝突を防ぐ。
3. Interface Mixin（@Accessor/@Invoker）は安全 — 元のコードを書き換えない。競合リスク極低。
4. Constructorへの@InjectはTAIL/RETURNのみ可能 — HEADや他位置への注入は不可。
5. Compatibility Level: Forge 1.20.1 → JAVA_17, NeoForge 1.21.1 → JAVA_21
6. 他Modのクラスに注入する際は@Pseudoを必ず付与 — クラスが存在しない場合のクラッシュを防ぐ。
7. 開発時は locals = LocalCapture.CAPTURE_FAILHARD — 即座にエラー検知。リリース時は CAPTURE_FAILSOFT に切替。

❌ やってはいけないこと

1. @Overwrite / @Redirect は極力避ける — 同じ箇所を他Modも書き換えると互換性破壊。どうしても必要な場合のみ priority で順序制御。
2. @Shadow したフィールドに final を付けない — @Final @Mutable @Shadow を使うこと。Mixinコンパイル時にエラーになる。
3. method = "target()V" のシグネチャを間違えない — 戻り値・引数・修飾子は必ず正確に記述。間違えると Mixin apply failed で起動時クラッシュ。
4. CallbackInfoReturnableのジェネリクス型を間違えない — 戻り値の型と一致しないと注入失敗。
5. Mixin Configの package と実際のパッケージを一致させる — 不一致は ClassNotFoundException の原因。
6. mods.toml / neoforge.mods.toml の [[mixins]] を忘れない — 忘れるとMixinが一切適用されない。
7. build.gradle の jar manifest に MixinConfigs を含める — ないと配布用jarでMixinが読み込まれない。
8. run引数に -mixin.config=mixins.<modid>.json を含める — ないと開発環境でもMixinが読み込まれない。

開発ワークフロー

• 1. build.gradle にMixin設定追加（jar manifestの MixinConfigs、run引数の -mixin.config=mixins.<modid>.json）
• 2. mods.toml / neoforge.mods.toml に [[mixins]] 追加
• 3. src/main/resources/mixins.<modid>.json 作成（Mixin Config）
• 4. Mixinクラスを src/main/java/.../mixin/ に作成
• 5. ターゲットメソッドのシグネチャを確認（obf/name/mapping）
• 6. runClient で動作確認。Mixin apply failed が出たらシグネチャ見直し

詳細リファレンス

トピック	ファイル	読むタイミング
セットアップ（build.gradle, mods.toml, mixin config）	references/SETUP.md	最初に1回
Injector一覧（@Inject, @Redirect, @Overwrite, @ModifyArg/Args/Variable...）	references/INJECTORS.md	コード挿入・変更が必要な際
Helper/Utility（@Shadow, @Accessor, @Invoker, @Unique, @Slice, @Pseudo, @Dynamic）	references/HELPERS.md	フィールドアクセス・命名・競合回避