Document plugin helper agent workflow

2026-06-28 14:35:21 -07:00
parent f085bbb802
commit 17bd736e59
3 changed files with 270 additions and 6 deletions
@@ -0,0 +1,144 @@
+# Beat Saber Smoketest Workflow
+
+Use this workflow after installing or removing a plugin batch. It is adapted
+from the Setlist repo's working Proton/BSManager smoketest notes.
+
+The routine smoketest should be short: about 10 seconds wall time for launch and
+log check, followed by immediate teardown. If expected plugin log lines do not
+appear inside that window, treat that as a failure to investigate instead of
+stretching the timeout.
+
+## Preconditions
+
+- Run from the target BSManager instance directory, for example:
+
+```sh
+cd "$HOME/.local/share/BSManager/BSInstances/1.44.1"
+```
+
+- The instance should contain BSIPA (`IPA/`, `IPA.exe`, `winhttp.dll`, and
+  `Plugins/`).
+- If those files are absent, the run can still produce Unity `Player.log`
+  output, but it will not produce `Logs/_latest.log` or any IPA plugin-loading
+  evidence. Run `plugin-helper bootstrap --instance <version>` before using
+  this workflow to validate plugins.
+- On Plasma + Wayland, the shell needs working desktop session variables:
+  `DISPLAY`, `WAYLAND_DISPLAY`, and `XDG_RUNTIME_DIR`. If the IDE terminal is
+  missing them, copy values from the logged-in desktop session.
+
+## Launch
+
+Run the Proton launch in the foreground with a short watchdog. Backgrounding
+the Proton launch itself from an IDE terminal has been observed to exit early
+before Beat Saber writes useful `_latest.log` lines.
+
+Important: `timeout` may stop the launcher wrapper without killing the full
+Beat Saber/Proton process tree. Prefer a watchdog that sleeps for the smoke
+window and then kills the game process by name.
+
+```sh
+export SteamAppId=620980 SteamOverlayGameId=620980 SteamGameId=620980
+export WINEDLLOVERRIDES='winhttp=n,b'
+export STEAM_COMPAT_DATA_PATH="$HOME/.local/share/BSManager/SharedContent/compatdata"
+export STEAM_COMPAT_INSTALL_PATH="$PWD"
+export STEAM_COMPAT_CLIENT_INSTALL_PATH="$HOME/.local/share/Steam"
+export STEAM_COMPAT_APP_ID=620980
+export SteamEnv=1
+export OXR_PARALLEL_VIEWS=1
+
+(
+  sleep 10
+  pkill -TERM -f "[B]eat Saber.exe" || pkill -TERM -f "[B]eat Saber" || true
+  sleep 2
+  pkill -KILL -f "[B]eat Saber.exe" || pkill -KILL -f "[B]eat Saber" || true
+) &
+smoke_watchdog_pid=$!
+trap 'kill "$smoke_watchdog_pid" 2>/dev/null || true' EXIT
+
+steam-run "$HOME/.local/share/Steam/steamapps/common/Proton - Experimental/proton" \
+  run "$PWD/Beat Saber.exe" --no-yeet fpfc 2>&1 | tee /tmp/bs-smoke.log
+
+wait "$smoke_watchdog_pid" 2>/dev/null || true
+trap - EXIT
+```
+
+Useful launch arguments:
+
+| Argument | Use |
+| --- | --- |
+| `--verbose` | Opens the BSIPA console window. |
+| `--debug` | Promotes debug logs to console output. |
+| `--trace` | Enables very noisy BSIPA/internal traces. |
+| `fpfc` | First-Person Flying Controller, useful for non-VR menu testing. |
+| `--auto_play` | Built-in autoplayer for gameplay checks. |
+
+## Log Checks
+
+In another terminal, or immediately after the launch returns:
+
+```sh
+tail -F Logs/_latest.log
+```
+
+For a batch install, check for:
+
+- BSIPA startup reaches plugin loading.
+- the expected plugin names and versions appear in `Logs/_latest.log`.
+- there are no missing assembly or dependency-resolution failures.
+- there are no repeated unhandled exceptions from newly installed plugins.
+- the game reaches the main menu.
+
+After the first successful launch, `plugin-helper bootstrap-check --instance
+<version>` should pass. Ordinary plugin plans for lockfiles that include BSIPA
+depend on that recorded bootstrap state and the latest IPA log.
+
+For Setlist specifically:
+
+```sh
+grep Setlist Logs/_latest.log
+```
+
+Expected Setlist signals include `platformUserId=...`, playlist lines with
+`hasSyncUrl=...`, and `beatLeaderOwnerConfirmed=...`. When testing real playlist
+sync, adding a map to an owned BeatLeader-synced playlist should log an HTTP
+success line.
+
+## Teardown
+
+When the expected log lines are present before the watchdog fires, stop Beat
+Saber immediately from a second terminal instead of waiting for the smoke window
+to expire.
+
+```sh
+pkill -TERM -f "[B]eat Saber.exe" || pkill -TERM -f "[B]eat Saber" || true
+sleep 2
+pkill -KILL -f "[B]eat Saber.exe" || pkill -KILL -f "[B]eat Saber" || true
+```
+
+The bracketed pattern avoids matching the shell command that is running the
+cleanup. If Beat Saber still remains open, close the game window manually and
+then check for leftovers:
+
+```sh
+ps -eo pid,ppid,stat,comm,args | rg -i '[B]eat Saber|[P]roton.*Beat Saber|[w]ineserver|[s]team-run'
+```
+
+If the smoketest fails, kill leftover Beat Saber, Wine, or Proton processes
+before retrying, then inspect `/tmp/bs-smoke.log`, Unity `Player.log` in the
+Proton compatdata, and the timestamped files under `Logs/`.
+
+## Plugin Development Notes From Setlist
+
+These are relevant when `plugin-helper` installs locally built personal plugins.
+
+- PC BSIPA plugins are .NET Framework class libraries loaded by BSIPA. Linux
+  `dotnet build` output is CIL and can be loaded by the Proton game instance.
+- BSMT-style builds may copy the DLL directly into `<BeatSaberDir>/Plugins/`;
+  use `-p:DisableCopyToPlugins=True` when a build should not mutate the game
+  tree.
+- `BeatSaberDir` in project user files or hint paths should point at the exact
+  BSManager instance being targeted.
+- If a plugin build produces a shipped artifact, bump the plugin version before
+  the successful build so the IPA log line identifies the artifact under test.
+- Setlist depends on BeatLeader being installed and signed in, PlaylistManager,
+  and BeatSaberPlaylistsLib. Its normal install target is `Plugins/Setlist.dll`.