| name | debug-resonite-mod |
| description | Use when debugging resonite-io mod runtime — adding logs, decompiling Resonite DLLs, starting/stopping Resonite from container, tailing BepInEx logs. Triggers: 'just log', 'just decompile', 'host-agent', 'Resonite を起動', 'Resonite を停止', 'BepInEx LogOutput', 'AssemblyLoadContext', 'mod の挙動を確認', 'TypeLoadException', 'Renderer の挙動'. |
| version | 0.1.0 |
Debug Resonite-IO Mod
mod は Resonite (host プロセス) に in-process でロードされるため、container 内から直接 attach する経路はない。基本戦略は print-debug + ログ tailing。
1. ログ追従 (print-debug の主経路)
- C# 側は
ResoniteIOPlugin.Log (BepInEx ManualLogSource) から LogInfo / LogDebug 等を出す
- 出力先: Gale 経由起動時
gale/BepInEx/LogOutput.log (プロファイル側)
- host 側で
just log を別ターミナルで走らせ、tail -F で追従 (Resonite 再起動・ログローテーションを跨いで再 attach)
- Python 側は通常の
logging でクライアント側の挙動を確認
.NET debugger attach (host IDE → Resonite プロセス) は必要になった時に整備する (print-debug + just log で多くは足りる)。PDB は deploy-mod 時に DLL と一緒に配置済みなのでシンボル解決の前提は満たしている。
2. Renderite IPC のドキュメント不足対策 (decompile)
Camera readback など Renderite 周辺の実装は decompile を読みながら進める前提:
just decompile で decompiled/ 配下に Resonite first-party DLL を ILSpy (ilspycmd) で project 形式に展開できる (gitignore 済み)- Renderite Unity DLL も対象に含まれる
.env の ResonitePath 必須- 手探りで判った仕様はコメントではなく
memory/feedback_*.md に残すこと
3. Container → Host bridge (Resonite start/stop)
container 内 shell から host の Resonite を Gale 経由で起動・停止する debug 経路。print-debug (just log) と並ぶ二本目の debug 経路。
- host 側: GUI session の端末で
just host-agent を foreground 常駐させる
- gale CLI は
--no-gui 指定時もディスプレイを要求する ため、SSH only / TTY only セッションでは起動できない (Python 内で DISPLAY/WAYLAND_DISPLAY を検査して fail-fast する)
- Ctrl+C で停止、socket は自動 unlink
- container 側:
just resonite-start [--profile NAME] で起動just resonite-stop で停止 (Resonite.exe / Renderite.Renderer.exe を SIGTERM → 3 秒待ち → SIGKILL の二段構え)just resonite-status で実行状態を JSON 表示
- 設定:
.env の GaleProfile=<name> を既定 profile に使う (--profile で都度 override 可)。gale バイナリが PATH 上に無い場合 (AppImage 等) は .env の GaleBin=/abs/path/to/Gale.AppImage で絶対パス指定
- トランスポート: 本番 gRPC IPC の
$HOME/.resonite-io/ とは分離した $HOME/.resonite-io-debug/host-agent.sock を使う (両方とも pressure-vessel が通す $HOME 配下を採用)。mod 側 socket 探索ロジック (resonite-*.sock) と命名衝突しない設計
- kill 範囲: 名前ベース pkill のみで Proton / pressure-vessel / reaper は触らない (Steam セッションを壊さないため Steam reaper の自走回収に委ねる)
4. 典型的な debug シナリオ
TypeLoadException / MissingMethodException が出る
Google.Protobuf 3.15+ API (UnsafeByteOperations 等) を Core 側で使うと、Resonite 同梱の 3.11.4 と衝突して TypeLoadException で死ぬ。PluginAssemblyResolver でも救えないケースあり。詳細: feedback_protobuf_3_11_4_in_resonite.md
Camera v2 / Renderer 側 plugin が load されない
- まず Steam Launch Options に
WINEDLLOVERRIDES="winhttp=n,b" %command% が入っているか確認 (これが無いと Renderer 側 BepInEx は起動しない)
gale/Renderer/BepInEx/LogOutput.log を確認 (Renderer 側ログは engine 側と別ファイル)- InterprocessLib の callback signature は
Action<T[]?> で、namespace は DLL 名と独立して InterprocessLib。static event は Dispose で必ず -=。詳細: feedback_interprocesslib_callback_signature.md
mod がそもそも load されない
just check-gale で必須 plugin 6 個 (+ BepInExRenderer framework) を確認gale/BepInEx/plugins/ResoniteIO/ に DLL + PDB が居るか- Vanilla 起動 (Steam 直起動) になっていないか — Gale 経由でなければ mod は読まれない
- 詳細な setup 周りは
setup-resonite-env skill 参照
Camera readback / Renderite の挙動が不明
just decompile で decompiled/ を生成し、Renderite Unity DLL を直接読む。
詳細な制約集約は feedback_camera_v2_constraints.md。
5. 関連 memory
