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).
• docs/pc-modding.md §References (wiki paths, BSMT templates, BSIPA, SongCore, etc.) match 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.
• 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).

Smoketest (run game, check plugin log)

Use this on the host when you need to verify the Setlist plugin after a build (full env + steam-run line is in 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 20–timeout 30 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 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 25 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 ~15 seconds of a successful boot.
3. Confirm: grep Setlist Logs/_latest.log | tail -1 — expect hasSyncUrl=True, beatLeaderOwnerConfirmed=… (or your current message shape).
4. When done, timeout may already have stopped the run; if Beat Saber.exe / Wine is still running, kill that process tree.

If _latest.log does not grow within ~15s of a foreground launch, treat as failure: read /tmp/bs-smoke.log (if used) and the timestamped file under Logs/, or rerun the same block from Konsole on the desktop if the IDE shell still misbehaves.