setlist/AGENTS.md

Agent notes — Beat Saber / this repo

Repo

• Modding workflow and references live in docs/pc-modding.md (Linux + Cursor + dotnet CLI; no VS/Rider BSMT extension).
• The References section in docs/pc-modding.md (wiki paths, BSMT templates, BSIPA, SongCore, etc.) matches local git checkouts under ~/src/… on this machine (same layout as the guide’s ../../../src/… links from here). Read those directories first; only fetch upstream (raw GitHub, bsmg.wiki) if a checkout is missing.
• BSMG wiki (Modding section): Available on disk at ~/src/bsmg/wiki (also opened via bs-modding-tools.code-workspace). Prefer that tree over web mirrors for static wiki content.

Game install (BSManager)

• Path: /home/pleb/.local/share/BSManager/BSInstances/1.40.8
• Version pin: 1.40.8 (managed copy; launch modded build from BSManager, not Steam’s live folder).
• BSIPA: Present (IPA/, IPA.exe, winhttp.dll, Plugins/).

Plugins currently in Plugins/

BeatSaverDownloader, BeatSaverUpdater, BSML, BS_Utils, PlaylistManager, SiraUtil, SongCore (+ manifests/libs as shipped).

Host toolchain

• dotnet: 9.0.312 (SDK 6+ is fine for net472 plugin builds per guide).
• ilspycmd: 9.1.0.0 (decompile/reference game or plugin assemblies from CLI).
• NuGet: Installed (per user setup).

Conventions agents should respect

• Plugin projects are .NET Framework 4.7.2 class libraries loaded by BSIPA; builds are CIL — Linux dotnet build output is valid for the Proton game instance.
• Point BeatSaberDir / game references at the BSManager instance path above when editing project user files or HintPaths.
• Single path, not compatibility layers: Prefer one straightforward implementation. Avoid backwards-compatibility boilerplate (dual code paths, “try old API then new API” probes, feature flags for multiple stack versions) unless the user explicitly asked to support more than one game or dependency version.
• Plugin version bump on compile: Whenever you run dotnet build on Setlist/ as part of agent work, increment the patch segment (the z in 0.0.z) in both Setlist/manifest.json (version) and Setlist/Properties/AssemblyInfo.cs (AssemblyVersion / AssemblyFileVersion as 0.0.z.0) before that build so IPA’s Setlist (Setlist): … log line matches the new artifact. Skip bumping if you only build to reproduce a compile error without changing shipped bits (then fix and bump once before the successful build).
• Build then validate: Whenever agent work produces a new shipped Setlist build (version bump + successful dotnet build that outputs the plugin DLL), run the Smoketest below before considering the task finished, unless the user explicitly said not to launch the game.

Smoketest (run game, check plugin log)

Budget: the whole smoketest should finish in about 15 seconds wall time (launch, log check, teardown). Do not use long timeout values such as 60s or 90s for routine validation. If Setlist lines reliably appear later than that, treat it as a plugin bug and fix startup work so the smoketest can pass — do not stretch the smoketest timeout to compensate.

Full env + exact steam-run / Proton / env vars: docs/notes.md under Testing.

Session / display: On Plasma + Wayland, the shell should have a sensible DISPLAY (often :0), WAYLAND_DISPLAY (e.g. wayland-0), and XDG_RUNTIME_DIR (e.g. /run/user/$UID). If they are empty, set them to match the logged-in desktop session before launching.

Launch (important): Wrap the steam-run … proton … Beat Saber.exe … --no-yeet fpfc invocation in timeout 15 and run it in the foreground (stdin/stdout attached). In Cursor’s integrated terminal, the same command started with & in the background has been observed to exit immediately (only Proton fsync in capture, no new _latest.log lines). A short foreground timeout caps wall time and keeps the Proton/game tree alive long enough to boot.

1. cd to the BSManager instance path, export vars from docs/notes.md (and display vars above if needed).
2. Run e.g. timeout 15 steam-run …/proton run …/Beat Saber.exe --no-yeet fpfc (optionally 2>&1 | tee /tmp/bs-smoke.log). Expect Setlist lines in Logs/_latest.log within a few seconds after a successful boot (well inside the 15s cap).
3. Confirm: grep Setlist Logs/_latest.log — expect current Setlist INFO lines (e.g. platformUserId=…, playlist lines with hasSyncUrl=…, beatLeaderOwnerConfirmed=…).
4. When the smoketest has succeeded in the log (expected Setlist lines present), stop Beat Saber immediately — do not wait for timeout 15 to expire. Kill the game / Proton tree (e.g. pkill -f "Beat Saber.exe" or pkill -f "Beat Saber", or kill the steam-run child tree if needed). If timeout 15 already terminated everything, no extra kill is required.
5. If _latest.log does not show new Setlist lines within ~15s of a foreground launch, treat as failure: read /tmp/bs-smoke.log (if used) and the timestamped file under Logs/, or rerun from Konsole on the desktop if the IDE shell misbehaves. Kill any leftover Beat Saber.exe / Wine processes after a failed run too.