diff --git a/.agents/skills/beatsaber-plugin-builder/SKILL.md b/.agents/skills/beatsaber-plugin-builder/SKILL.md index 633e39e..1daf24d 100644 --- a/.agents/skills/beatsaber-plugin-builder/SKILL.md +++ b/.agents/skills/beatsaber-plugin-builder/SKILL.md @@ -1,9 +1,9 @@ --- name: beatsaber-plugin-builder -description: Build, test-compile, or package Beat Saber PC BSIPA plugin source on Linux from local checkouts, GitHub branches, or pull requests. Use when asked to build a Beat Saber plugin, compile a plugin PR, produce a DLL/zip artifact, configure BeatSaberDir/local refs for dotnet builds, or diagnose Linux build failures for net472 BSIPA projects. +description: Build, test-compile, or package Beat Saber PC BSIPA plugin source on Linux from local checkouts, GitHub branches, or pull requests. Use when asked to build a Beat Saber plugin, compile a plugin PR, produce a DLL/zip artifact, configure BeatSaberDir/local refs for dotnet builds, or diagnose Linux build failures for .NET Framework BSIPA projects. --- -# Build Beat Saber Plugin +# Beat Saber Plugin Builder Use this skill to compile PC BSIPA plugin projects on this Linux host, especially from the `plugin-helper` repo. The workflow is adapted from the Setlist repo's Linux/Cursor build notes. @@ -16,18 +16,25 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b ```bash pwd git status --short + sed -n '1,220p' plugin-helper.local.toml ``` - In `plugin-helper`, run commands from repo root and keep temporary source checkouts under `.state/build/` unless the user asks for another location. Do not disturb unrelated dirty files. + In `plugin-helper`, run commands from repo root. Treat + `plugin-helper.local.toml` as the source of truth for profile + `instances_root` and `state_dir` values, and keep temporary source checkouts + under the chosen profile's `state_dir` such as + `/build/`. Do not disturb unrelated dirty files. 2. Resolve source. - For a GitHub PR, clone or reuse a checkout under `.state/build`, add/fetch the upstream remote if needed, and check out the PR head: + For a GitHub PR, clone or reuse a checkout under the selected profile's + `/build`, add/fetch the upstream remote if needed, and check out + the PR head: ```bash - git clone https://github.com//.git .state/build/ - git -C .state/build/ fetch origin pull//head:pr- - git -C .state/build/ checkout pr- + git clone https://github.com//.git /build/ + git -C /build/ fetch origin pull//head:pr- + git -C /build/ checkout pr- ``` If the PR is from a fork and the repo already has a fork remote, preserve it. Never overwrite local source changes without explicit approval. @@ -43,14 +50,19 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b 4. Choose Beat Saber references. - Prefer a BSManager instance matching the plugin or manifest `gameVersion`. Common local roots: + Prefer a BSManager instance matching the plugin or manifest `gameVersion`. + Read `plugin-helper.local.toml` and select the intended profile, then use + that profile's `instances_root` and matching `state_dir` instead of + searching default BSManager paths manually: - ```text - /home/pleb/.local/share/BSManager/BSInstances/ - /home/pleb/Windows/Users/pleb/BSManager/BSInstances/ + ```bash + PYTHONPATH=src .venv/bin/python -m plugin_helper --profile instances ``` - Use a local `.csproj.user` or MSBuild properties rather than committing machine paths. For test builds, pass `-p:DisableCopyToPlugins=True` and, for BSMT projects that expose it, `-p:DisableCopyToGame=True` so compilation does not mutate the game install. + Use a local `.csproj.user` or MSBuild properties rather than committing + machine paths. For test builds, pass `-p:DisableCopyToPlugins=True` and, for + BSMT projects that expose it, `-p:DisableCopyToGame=True` so compilation + does not mutate the game install. 5. Restore and build. @@ -61,9 +73,25 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b dotnet build -c Release -p:DisableCopyToPlugins=True -p:DisableCopyToGame=True ``` - If the project lacks .NET Framework reference assemblies on Linux, add or pass `Microsoft.NETFramework.ReferenceAssemblies.net472` as described in the reference file. + If the project lacks .NET Framework reference assemblies on Linux, add or + pass the package matching the project's target framework, usually + `Microsoft.NETFramework.ReferenceAssemblies.net48` for current BSIPA + projects, as described in the reference file. -6. Collect artifacts. +6. Verify Beat Saber API changes before patching gameplay code. + + When a Beat Saber upgrade breaks a type/member reference, first determine + whether the API moved assemblies before substituting another type. Inspect + the target game DLLs and nearby mod sources: + + ```bash + strings "/Beat Saber_Data/Managed/Main.dll" | rg 'TypeOrMemberName' + strings "/Beat Saber_Data/Managed/HMLib.dll" | rg 'TypeOrMemberName' + ilspycmd -t TypeName "/Beat Saber_Data/Managed/Main.dll" | sed -n '1,220p' + rg -n 'TypeOrMemberName|NearbyConcept' ~/src// ~/src/Auros/SiraUtil ~/src/nike4613/BeatSaber-IPA-Reloaded + ``` + +7. Collect artifacts. Find produced DLLs and release zips: @@ -71,23 +99,27 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b find -path '*/bin/*' \( -name '*.dll' -o -name '*.zip' \) -print ``` - Verify the DLL name, version, and manifest. If the result is meant for `plugin-helper`, place a copy under `.state/instances//downloads//` and use the helper plan/apply workflow rather than hand-copying into a BSManager instance. + Verify the DLL name, version, and manifest. If the result is meant for + `plugin-helper`, place a copy under + `/instances//downloads//` for the selected + profile and use the helper plan/apply workflow rather than hand-copying into + a BSManager instance. -7. Validate. +8. Validate. For skill edits inside this repo, run: ```bash python /home/pleb/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/beatsaber-plugin-builder - PYTHONPATH=src python -m compileall -q src tests - PYTHONPATH=src python -m unittest discover -s tests + PYTHONPATH=src .venv/bin/python -m compileall -q src tests + PYTHONPATH=src .venv/bin/python -m unittest discover -s tests ``` For a plugin build, at minimum report the exact `dotnet build` result and artifact paths. For live game validation, use `docs/SMOKETEST.md` and tear down Beat Saber processes afterward. ## Failure Triage -- Missing `Microsoft.NETFramework.ReferenceAssemblies`: add the net472 reference-assemblies package or pass an equivalent MSBuild/package restore fix. +- Missing `Microsoft.NETFramework.ReferenceAssemblies`: add the package matching the target framework, usually `Microsoft.NETFramework.ReferenceAssemblies.net48` for current projects, or pass an equivalent MSBuild/package restore fix. - Missing `Main.dll`, `HMUI.dll`, `IPA.Loader.dll`, `BSML.dll`, `SongCore.dll`, or similar: `BeatSaberDir` points at the wrong/unmodded instance, or dependencies are absent from `Plugins/`/`Libs/`. - BSMT copies to `IPA/Pending` or `Plugins` during build: rebuild with `-p:DisableCopyToPlugins=True -p:DisableCopyToGame=True` unless the user explicitly wants deployment. - NuGet package restore fails because a source is missing: inspect `NuGet.config` and installed package sources; use repo-local configuration where possible. diff --git a/.agents/skills/beatsaber-plugin-builder/references/linux-bsipa-build.md b/.agents/skills/beatsaber-plugin-builder/references/linux-bsipa-build.md index 58d377e..cb94817 100644 --- a/.agents/skills/beatsaber-plugin-builder/references/linux-bsipa-build.md +++ b/.agents/skills/beatsaber-plugin-builder/references/linux-bsipa-build.md @@ -6,7 +6,8 @@ This workflow comes from `/home/pleb/ops/beatsaber/setlist/docs/pc-modding.md` a ## Toolchain -- PC BSIPA plugins are usually .NET Framework `net472` class libraries. +- PC BSIPA plugins are .NET Framework class libraries; current projects + commonly target `net48`, while older projects may still target `net472`. - Linux `dotnet` SDK 6+ can build them because output DLLs are platform-agnostic CIL loaded by Beat Saber under Proton. - `BeatSaberModdingTools.Tasks` supplies the MSBuild targets normally driven by Visual Studio/Rider BSMT extensions. - On this host, `dotnet --list-sdks` should show a usable SDK. NuGet is available for package inspection. @@ -24,16 +25,13 @@ Plugins/ winhttp.dll ``` -Preferred local managed instance root: +In `plugin-helper`, prefer the profile selected from +`plugin-helper.local.toml` as the source of truth for the managed instance root +and state directory: -```text -/home/pleb/.local/share/BSManager/BSInstances/ -``` - -Windows mirror root: - -```text -/home/pleb/Windows/Users/pleb/BSManager/BSInstances/ +```bash +sed -n '1,220p' plugin-helper.local.toml +PYTHONPATH=src .venv/bin/python -m plugin_helper --profile instances ``` Use `BeatSaberVersion.txt` for the exact game version. The manifest `gameVersion` normally uses the `major.minor.patch` prefix, not the build suffix. @@ -45,7 +43,7 @@ Prefer machine-local configuration in `.csproj.user`: ```xml - /home/pleb/.local/share/BSManager/BSInstances/1.40.8 + /path/from/selected/profile/instances_root/1.44.1 ``` @@ -60,7 +58,10 @@ For those, pass `-p:LocalRefsDir=/path/to/instance` or add a local `.csproj.user When changing a project file for Linux portability, prefer the smallest explicit fix: -- Add `Microsoft.NETFramework.ReferenceAssemblies.net472` when MSBuild reports missing .NET Framework reference assemblies. +- Add the `Microsoft.NETFramework.ReferenceAssemblies.*` package matching the + project target framework, usually `Microsoft.NETFramework.ReferenceAssemblies.net48` + for current projects, when MSBuild reports missing .NET Framework reference + assemblies. - Set or pass `DisableCopyToPlugins=True` for artifact-only builds. - Keep hint paths rooted at `$(BeatSaberDir)` where possible. - Do not add broad multi-version compatibility logic unless requested. @@ -105,7 +106,9 @@ If the purpose is to install the built artifact, copy it into plugin-helper's st ## Common Reference Failures -- `MSB3644` or missing `.NETFramework,Version=v4.7.2` reference assemblies: add `Microsoft.NETFramework.ReferenceAssemblies.net472`. +- `MSB3644` or missing `.NETFramework,Version=v4.x` reference assemblies: add + the matching `Microsoft.NETFramework.ReferenceAssemblies.*` package, usually + `Microsoft.NETFramework.ReferenceAssemblies.net48` for current projects. - Missing game assemblies such as `Main.dll`, `HMUI.dll`, `UnityEngine.CoreModule.dll`: `BeatSaberDir` is wrong or incomplete. - Missing mod dependencies such as `BSML.dll`, `SongCore.dll`, `SiraUtil.dll`, `BeatSaberPlaylistsLib.dll`: install or point at an instance containing those plugins, or fetch the dependency DLL from its verified release only when appropriate. - `IPA.Loader.dll` missing: BSIPA is not bootstrapped in that instance. @@ -115,17 +118,17 @@ If the purpose is to install the built artifact, copy it into plugin-helper's st For a built plugin DLL intended for a managed instance: ```bash -mkdir -p .state/instances//downloads/ -cp //bin/Release/.dll .state/instances//downloads//.dll -sha256sum .state/instances//downloads//.dll +mkdir -p /instances//downloads/ +cp //bin/Release/.dll /instances//downloads//.dll +sha256sum /instances//downloads//.dll ``` Then update registry/lock data only if the user asked to manage/install the artifact, and use: ```bash -PYTHONPATH=src python -m plugin_helper --state-dir .state check --instance -PYTHONPATH=src python -m plugin_helper --state-dir .state plan --instance --plugin -PYTHONPATH=src python -m plugin_helper --state-dir .state apply +PYTHONPATH=src .venv/bin/python -m plugin_helper --profile check --instance +PYTHONPATH=src .venv/bin/python -m plugin_helper --profile plan --instance --plugin +PYTHONPATH=src .venv/bin/python -m plugin_helper --profile apply ``` Inspect the generated plan before applying. diff --git a/.agents/skills/beatsaber-plugin-manager/SKILL.md b/.agents/skills/beatsaber-plugin-manager/SKILL.md index 51ed61c..89bc5b4 100644 --- a/.agents/skills/beatsaber-plugin-manager/SKILL.md +++ b/.agents/skills/beatsaber-plugin-manager/SKILL.md @@ -3,7 +3,7 @@ name: beatsaber-plugin-manager description: Install or update a Beat Saber plugin in the plugin-helper repo by using the local helper workflow. Use when the user asks to add, install, update, bump, lock, bootstrap BSIPA, or manage a Beat Saber plugin release for a BSManager instance. Prefer upstream GitHub release artifacts for normal plugins; use BeatMods primarily as compatibility/dependency metadata, with CDN artifacts only for inaccessible upstream assets, BeatMods-only packages, or framework/library dependencies. --- -# Install Beat Saber Plugin +# Beat Saber Plugin Installer Use the repository's own `plugin-helper` commands to manage plugins for BSManager instances whenever the helper supports the operation. diff --git a/AGENTS.md b/AGENTS.md index 66faca5..efecf59 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,8 +26,10 @@ Guidance for coding agents working in this repo. ## Workflow Rules - Run commands from the repo root with `PYTHONPATH=src`. +- A repo-local Python virtualenv is normally available at `.venv`; prefer + `.venv/bin/python` for helper commands and tests when it exists. - For human-style inspection, prefer the menu with repo-local state: - `PYTHONPATH=src python -m plugin_helper --state-dir .state menu`. + `PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state menu`. - When targeting the local Linux BSManager install, pass `--instances-root ~/.local/share/BSManager/BSInstances` and normally `--state-dir .state`. @@ -51,9 +53,10 @@ Guidance for coding agents working in this repo. ## Validation -- Run `PYTHONPATH=src python -m unittest discover -s tests` after code changes. -- Run `PYTHONPATH=src python -m compileall -q src tests` for syntax/import - checks. +- Run `PYTHONPATH=src .venv/bin/python -m unittest discover -s tests` after + code changes when `.venv` exists; otherwise use `python`. +- Run `PYTHONPATH=src .venv/bin/python -m compileall -q src tests` for + syntax/import checks when `.venv` exists; otherwise use `python`. - For live game validation, follow `docs/SMOKETEST.md` and tear down Beat Saber processes afterward.