| name | setup-resonite-env |
| description | Use when setting up the resonite-io dev environment on a fresh clone, configuring Gale profile, setting Steam Launch Options (WINEDLLOVERRIDES), or troubleshooting mod-load failures. Triggers: 'just init', 'Gale プロファイル', 'WINEDLLOVERRIDES', 'check-gale', 'mod が読まれない', '環境構築', 'fresh clone'. |
| version | 0.1.0 |
Setup Resonite-IO Dev Environment
resonite-io をホストで動かすために必要な準備の一覧と落とし穴の解説。ホスト側で必要なものは docker / docker compose v2 / just に加えて devcontainer を開く手段 (VS Code の Dev Containers 拡張 / Zed / @devcontainers/cli) のいずれか。.NET / uv / protoc / pre-commit はすべてコンテナ内に閉じている。
1. Docker 開発環境
開発ツール (.NET 10 SDK / uv / protoc / dotnet local tools / pre-commit) は debian:bookworm-slim ベースの単一 image に同梱し、host にはインストールしない。
compose.yml は name: resonite-io-${USER} で user 単位の名前空間 に分離 (同一ホストの複数アカウント / 複数 worktree が衝突しない)。.devcontainer/devcontainer.json がこの compose を参照する- 作業ディレクトリは host repo を
/workspace に直接 rw bind。host 側の編集が即座に container 側に反映され、container 内の build 成果物 (bin/, obj/, python/.venv/ 等) も .gitignore 経由で host 側に出る
- Resonite フォルダは
/resonite に read-only bind のみ (FrooxEngine.dll 等の HintPath 参照専用; mod の deploy 先ではない)
- Gale プロファイル (
./gale/) は /workspace/gale 経由で参照する (environment.GalePath: /workspace/gale が csproj の deploy 先を解決)
- コンテナ内
dev user の UID/GID を host user に一致 させて build (HOST_UID / HOST_GID を build-arg で渡す)。これにより deploy-mod で出力された DLL/PDB が host user 所有になり、host 側 git からそのまま見える
- NuGet / uv のキャッシュは named volume にマウントして再ビルドを高速化 (
/home/dev/.nuget / /home/dev/.cache/uv)
csharpier / tcli 等の .NET CLI ツールは .config/dotnet-tools.json の local tool として固定し、dotnet tool restore + dotnet <tool> で呼び出す
初回 setup フロー:
.env.example を .env にコピーし、ResonitePath を Steam の Resonite 実行ファイルディレクトリ絶対パスに設定。必要に応じて GaleProfile / GaleBin もjust init を host 側で実行 — docker / docker compose v2 検出 → .env 検証 → ResonitePath 検証 → Gale プロファイル確認を冪等に実施- devcontainer を開く — VS Code: 「Dev Containers: Reopen in Container」、Zed: dev container として開く、CLI (任意・headless / CI 用):
devcontainer up --workspace-folder . → devcontainer exec --workspace-folder . bash (@devcontainers/cli、既定では未インストール)
- devcontainer が自動実行する:
initializeCommand (host 側・作成前): ~/.resonite-io{,-debug}/ を 0700 で事前作成し、host UID/GID を .env に記録 (build-arg でコンテナ user に一致させ、deploy 成果物が host 所有になる)postCreateCommand (container 内・作成後): scripts/container-init.sh を実行 (deps 解決: dotnet tool restore + uv sync + pre-commit install + Claude settings symlink)
- 以降はコンテナ内ターミナルで
just gen-proto / just build / just deploy-mod 等を従来どおり実行する
2. Gale プロファイル方式
ホスト Resonite には BepisLoader を直接インストールしない (Vanilla 維持)。代わりに Gale (v1.5.4+) のカスタムプロファイル機能で repo root の ./gale/ を mod sandbox にする。
手動セットアップ手順:
- Gale で profile を新規作成し、パスを
<repo>/gale に指定 (指定先は EMPTY である必要があり、./gale/ を事前に作らない)
- profile に以下 6 個を install:
ResoniteModding-BepisLoader (>=1.5.1)ResoniteModding-BepInExResoniteShim (>=0.9.3)ResoniteModding-BepisResoniteWrapper (>=1.0.2)ResoniteModding-BepInExRenderer (>=5.4) ← Camera v2 で追加 (Renderer 側 BepInEx 5 framework、Renderer/BepInEx/core/ に framework deploy)ResoniteModding-RenderiteHook (>=1.1.1) ← Camera v2 で追加 (engine → Renderer doorstop inject)Nytra-InterprocessLib (>=3.0.0) ← Camera v2 で追加 (engine ↔ Renderer shared-mem queue)
- Gale で Resonite を起動すると
LinuxBootstrap.sh がプロファイル版に差し替わり、BepInEx が有効化される
just check-gale (または just init) で必須 DLL の在中を検証just deploy-mod で gale/BepInEx/plugins/ResoniteIO/ に DLL+PDB が配置される (deploy 先 dir は csproj の <Copy> が自動 mkdir する)
just check-gale は BepInExRenderer 検出時に Renderer/BepInEx/core/BepInEx.Preloader.dll の存在で判定する (plugin dir ではなく framework dir に deploy するため。feedback_bepinex_renderer_as_framework.md 参照)。
ホスト Resonite を Vanilla で起動 (Gale を介さず Steam から直接起動) した場合は mod は読み込まれない。注意: Gale 経由起動後にホスト Resonite ディレクトリへ hookfxr.ini (enable=true) 等が残る場合がある。Vanilla 復帰時は確認すること。
3. Steam Launch Options (Camera v2 で必須)
Steam で Resonite を選択 → Properties → Launch Options に以下を設定する:
WINEDLLOVERRIDES="winhttp=n,b" %command%
- なぜ必須: Wine は system 同梱
winhttp.dll を優先するため、RenderiteHook が deploy した hook 版 winhttp.dll (= doorstop) を読ませるには Launch Options で override が必要。これが無いと Renderer 側 BepInEx は永遠に起動せず、Camera v2 の renderer-side plugin が load されない
- debug が困難: 真の原因が Steam Launch Options 漏れであることは
/proc/<pid>/environ で確認できないと見抜けない (Wine プロセスの env を host から見るのが面倒)
- 代替経路は無い:
host_agent.py から env で WINEDLLOVERRIDES を渡しても Steam が sanitize するため通らない。Steam Launch Options が唯一の経路
4. UDS パスと pressure-vessel sandbox
- 本番 gRPC IPC は
$HOME/.resonite-io/、container ↔ host debug bridge は $HOME/.resonite-io-debug/ で host/container 同一絶対パスの bind 共有
$XDG_RUNTIME_DIR/ (= /run/user/<UID>/) は pressure-vessel sandbox が通さないため不採用/tmp/ も通らない。$HOME/ 配下のみが安全- 詳細は
reference_pressure_vessel_paths.md
5. 関連 memory
6. 実機 mod load 検証手順
just resonite-start (host-agent 経由で Resonite を起動) → just log で gale/BepInEx/LogOutput.log を tail し、Loading Plugin ResoniteIO 行が出るのを確認 → just resonite-stop の流れ。Claude が container 内から host-agent bridge 経由で完結できる。詳細な debug 経路は /debug-resonite-mod skill を参照。
