pleb/setlist
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
setlist/docs/bootstrap.md

4.7 KiB
Raw Permalink Blame History

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, BeatSaberModdingTools.Tasks on NuGet, BSIPA user install.

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:

<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

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:

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.