Bootstrap completed, hello world in BSIPA logs confirmed

2026-04-18 15:09:01 -07:00
parent 96b0e143ea
commit 752419121f
23 changed files with 3561 additions and 7 deletions
@@ -0,0 +1,95 @@
+# Bootstrapping the Setlist BSIPA plugin
+
+This documents how the `Setlist/` project was created (aligned with `docs/pc-modding.md` §5). Official references: [BSMT templates repo](https://github.com/Zingabopp/UnityModdingTools.Templates.BeatSaber), [BeatSaberModdingTools.Tasks on NuGet](https://www.nuget.org/packages/BeatSaberModdingTools.Tasks), [BSIPA user install](https://nike4613.github.io/BeatSaber-IPA-Reloaded/articles/start-user.html).
+
+## 1. Choose template
+
+We used the **BSIPA Plugin (Bare)** template (smallest layout: `Plugin.cs`, `manifest.json`, `AssemblyInfo`, MSBuild wiring). The upstream folder is `BSIPA Plugin (Bare)/` in the templates repository.
+
+The guide’s relative paths (e.g. `~/src/Zingabopp/UnityModdingTools.Templates.BeatSaber`) assume a local clone; this machine had no clone, so files were taken from raw GitHub with `curl` (same content as a copy from a clone).
+
+## 2. Project layout
+
+Created under repo root:
+
+| File | Role |
+|------|------|
+| `Setlist.csproj` | `net472` library, game assembly references via `$(BeatSaberDir)`, `BeatSaberModdingTools.Tasks` package |
+| `Directory.Build.props` | `ImportBSMTTargets` + `BSMTProjectType` = BSIPA (from `Directory.Build.props.template`) |
+| `Setlist.csproj.user` | **Local only** (gitignored via `*.user`): `BeatSaberDir` → BSManager managed instance |
+| `manifest.json` | BSIPA metadata; embedded at build |
+| `Plugin.cs` | `[Plugin]` entry; `Log.Info("Hello World")` in `[OnStart]` |
+| `Properties/AssemblyInfo.cs` | Assembly identity / version |
+
+## 3. Placeholders
+
+Bare template uses `$safeprojectname$`, `$guid1$`, `$targetframeworkversion$`, etc. These were expanded by hand to:
+
+- `Setlist` (assembly / namespace / plugin id)
+- A new `ProjectGuid` and `[assembly: Guid(...)]`
+- `TargetFrameworkVersion` → `4.7.2`
+
+## 4. `manifest.json`
+
+- **id / name:** `Setlist`
+- **description:** Short line describing playlist sync intent
+- **gameVersion:** `1.40.8` — taken from the install’s `BeatSaberVersion.txt` (use the `major.minor.patch` prefix; the file may include a `_build` suffix)
+- **dependsOn.BSIPA:** `^4.3.0` (per guide; adjust if your BSIPA major differs)
+
+## 5. NuGet packages (`dotnet restore`)
+
+No separate `nuget install` was required; `dotnet restore` / `dotnet build` resolved everything from nuget.org.
+
+| Package | Purpose |
+|---------|---------|
+| `BeatSaberModdingTools.Tasks` | BSMT MSBuild targets: manifest embedding, copy to game, release zip, etc. Template used `2.0.0-beta1`; we pinned **`2.0.0-beta7`** (latest beta on NuGet at bootstrap time). |
+| `Microsoft.NETFramework.ReferenceAssemblies.net472` **`1.0.3`** | **Required on this Linux host** (Nix-provided .NET SDK): first build failed with **MSB3644** (missing .NET Framework 4.7.2 reference assemblies). Adding this package fixes that without a Windows targeting pack. The guide notes BSMT may pull reference assemblies transitively; that did not satisfy MSBuild here, so the package was added **explicitly** to `Setlist.csproj`. |
+
+## 6. `BeatSaberDir` / `GameDirectory`
+
+`Setlist.csproj.user` sets:
+
+```xml
+<BeatSaberDir>/home/pleb/.local/share/BSManager/BSInstances/1.40.8</BeatSaberDir>
+```
+
+BSMT resolves the game root as `GameDirectory` and expects `Beat Saber.exe` (or `Beat Saber`) there. Point at the **BSManager managed copy**, not the Steam tree, if that is what you mod.
+
+## 7. Build
+
+```bash
+cd Setlist
+dotnet restore
+dotnet build -c Debug
+```
+
+Expect:
+
+- `bin/Debug/Setlist.dll` (+ `.pdb`)
+- BSMT artifact layout under `bin/Debug/Artifact/Plugins/`
+
+## 8. Where the DLL lands (Linux caveat)
+
+`BeatSaberModdingTools.Tasks` runs an `IsProcessRunning` check before copying. **On Unix the task is unsupported**; with `Fallback="True"` BSMT behaves as if the game were running and copies to:
+
+`$GameDirectory/IPA/Pending/Plugins/`
+
+So you may see **`IPA/Pending/Plugins/Setlist.dll`** even when Beat Saber is not running.
+
+This repo adds a small **`CopyToPluginsOnUnixHost`** target at the end of `Setlist.csproj` that, on `$(OS) == 'Unix'`, also copies `$(OutputPath)Setlist.dll` (and `.pdb`) into **`$(BeatSaberDir)/Plugins/`**, so a normal Debug build matches the layout the game loads from **`Plugins/`**.
+
+After a successful `dotnet build -c Debug`, verify:
+
+```bash
+test -f "$BEAT_SABER_DIR/Plugins/Setlist.dll" && echo OK
+```
+
+(Replace `$BEAT_SABER_DIR` with your `BeatSaberDir`.)
+
+## 9. Seeing “Hello World”
+
+BSIPA logging uses `IPA.Logging.Logger` (exposed as `Log` in `Plugin.cs`). With **`--verbose`** (and optionally **`--debug`** for Unity logs), start the game from BSManager and check the BSIPA console or logs under the game folder (see guide §6).
+
+## 10. CI note
+
+Pass **`-p:ContinuousIntegrationBuild=true`** (or define `CIBuild` per template) to disable copying into the game directory on build agents.