reverse-engineering

MOD のリバースエンジニアリング

ルールその 0：推測せず、実物を調べてください。 デコンパイルしたコード、実際のデータ、実行中のメモリビュー、GPU キャプチャが仕様です。調べた内容（名前、ID、オフセット、形式）は、その都度 MODLOG.md に記録してください。

デコンパイルした出力と抽出したアセットは、すべて MOD リポジトリの外（例：~/<game>-decomp/）に置き、公開しないでください。シングルプレイヤー、オフライン、またはユーザー自身が運営するサーバーに限ります。アンチチート機能があるゲームには、デバッガーやスキャナーを絶対に接続しないでください（skills/mod-any-game/references/safety.md を参照してください）。

コードの種類に応じてツールを選ぶ（um scan で確認できます）

マネージド .NET（XNA/FNA、Unity Mono、インディー C# ゲームの多く）

• dotnet tool install -g ilspycmd を実行してから、ilspycmd -p -o ~/<game>-decomp <Game>.exe（または Assembly-CSharp.dll）を実行します。検索可能な C# プロジェクト全体が生成されます。
• dnSpyEx：デバッガーでステップ実行し、ブレークポイントを設定して、メソッドを編集できます。
• MCP：ILSpy-MCP / dnspy-mcp を使うと、エージェントが型やメソッドを直接検索できます。

Unity IL2CPP

• GameAssembly.dll と global-metadata.dat に Cpp2IL（または Il2CppDumper）を実行すると、型、フィールド、メソッドのシグネチャとアドレスに加え、ILSpy 用のダミー DLL が得られます。
• メソッド本体はネイティブです。GameAssembly.dll を Ghidra/IDA に読み込み、生成されたスクリプトを適用して関数に名前を付けます。
• 実行中の調査：UnityExplorer、または il2cpp-frida-mcp。

Java（Minecraft、Slay the Spire など） Vineflower / CFR / Recaf を使います。Minecraft では、Mojang mappings を使って Loom の genSources を実行します。

ネイティブ C/C++（カスタムエンジン、Unreal のゲームコード、コンソール版の再実装）

• Ghidra（無料）または IDA を MCP 経由で操作すると、エージェントがデコンパイル、名前変更、型の再設定、クロスリファレンスの追跡を行えます。
  • Ghidra：GhidraMCP（LaurieWired）、pyghidra-mcp（ヘッドレスで、スクリプト実行ツールを備えています。小さなツールを何百個も使うより、コードを扱えるツールのほうが優れています）、ReVa。
  • IDA：公式の Hex-Rays IDA MCP（IDA 9.4+ Pro/Home。「code mode」で IDAPython を実行）、または ida-pro-mcp。
  • Binary Ninja と radare2 にも MCP サーバーがあります。
• ワークフロー：
  1. まず文字列、次にクロスリファレンス、最後に関数を調べます。
  2. 理解できたものにはすべて名前と型を付けます。名前の変更を重ねることで、読みやすいプログラムになります。
  3. 推測をもとに作業を進める前に、動的に確認してください（下記参照）。エージェントが自信満々に誤認することもあります。
• Unreal：まずリフレクションデータをダンプします（UE4SS dumper または Dumper-7）。多くのゲームプレイクラスとプロパティの名前を無料で取得できます。

動的／実行中の調査

• Cheat Engine：値をスキャン → 「このアドレスに書き込んでいるものを探す」→ 構造体 → 所有者。CheatEngine MCP サーバーもあります。
• x64dbg：ブレークポイントとトレース（x64dbg-mcp。一部のツールは既定で 0.0.0.0 にバインドするため、127.0.0.1 にバインドしてください）。
• Frida（frida-mcp、frida-game-hacking-mcp）：JavaScript から関数をフックし、引数を記録します。
• ReClass.NET は、実行中のメモリから構造体を再構築します。

グラフィックス

• RenderDoc（renderdoc-mcp）でフレームをキャプチャすると、すべての描画、レンダーターゲット、定数バッファー（ビュー／射影行列）、深度バッファーを確認できます。
• これを使えば、ジオメトリやエフェクトを挿入する場所（mashup-mods）や、どのテクスチャにスプライトアトラスが含まれているかを特定できます。

データファイルとアセット形式

まず、コミュニティ製ツールを使います。

• Unity：UABEA、AssetRipper
• Unreal：FModel、UAssetGUI
  • 完全に圧縮された UE3 .upk（UELib で Exports=0 と表示されるもの）：Gildor's decompress （UE Viewer に付属）でコピーを展開します。または、LZO パッケージの場合は unpack_upk.py を使います。
• Bethesda：xEdit、BSArch
• GameMaker：UndertaleModTool
• Genie：genieutils
• Source：VRF、Crowbar
• FromSoft：WitchyBND、Smithbox
• Godot：GDRE Tools

自分で形式を解析する前に、コミュニティのアーカイブを検索します。2000年代から 2010年代のゲーム形式のほとんどは、コミュニティで解明されています。

• XeNTaX（2023年閉鎖）：フォーラム、 Wiki、 添付ファイル は archive.org にあり、 GitHub の公開バックアップもあります。
• ZenHAX：ゲームファイルの調査と QuickBMS スクリプト（2023年初頭までの投稿）。
• ファイル形式を調べるための決定版ガイド （Mr. Mouse、XeNTaX）：未知の形式の読み取りに関する定番チュートリアルです。

ベータ版やリークされた SDK など、出所を問わず、形式の知識やツールを活用します。ただし、ゲームファイル、 リークされたコード、SDK、ライセンスキーはダウンロードしないでください。

未文書化の形式の場合：

1. 複数の未改変ファイルを集めます。サイズを比較し、ヘッダーを16進ダンプします（xxd | head）。 マジックナンバー、件数、オフセット、固定サイズレコードのテーブルを探します。
2. まずヘッダー、次にフレーム／レコードのレイアウト、最後に圧縮方式について仮説を立てます。 すべての未改変ファイルをエラーなく解析できることを確認します。
3. 表示可能な形式（PNG、JSON など）にデコードするリーダーを書き、実際に確認します。
4. ライターを書き、ラウンドトリップで検証します：デコード → エンコード → デコードし、元ファイルと比較します。 AoE2 SLD スプライトライターは、未改変の騎士スプライトを平均誤差 0.9/255 で ラウンドトリップできたときに初めて採用されました（examples/aoe2-de-civ/sld.py）。
5. その後で初めて新しいファイルを作成します。一括変換の前に、1つのアセットを使ってゲーム内でテストします。

オラクルにする

• 移植するエンジンロジック（シミュレーター、トレーナー、再実装向け）：ゲームから実際のトレース（位置、ティックごとの速度）を記録し、移植したロジックに対して再生します。Terraria のクトゥルフの目の作業では、フレーム t+1 に適用されたアクションを使うようにしたところ、目の速度が 99.9％一致しました。Float32 の定数も重要でした（0.2f ≠ 0.2）。残っていた不一致の原因は、隠しバフ（Happy!、移動速度 x1.21）でした。リプレイを使えば、コードを読むだけでは見逃す点が見つかります。
• 長時間の RE 作業では：
  • ジャーナルファイルを用意します。
  • 検証済みの小さなステップを積み重ねます。
  • 問題ごとに試行回数に上限を設けます（同じ失敗が約3回続いたら、方法を変えます）。
  • 確認できた事実はすべてコミットします。