96 lines
4.7 KiB
Markdown
96 lines
4.7 KiB
Markdown
# 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.
|