pleb/plugin-helper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add BeatMods parsing and userdata restore

Browse Source
This commit is contained in:
pleb
2026-06-29 10:56:57 -07:00
parent 17bd736e59
commit 1f35f6b078
10 changed files with 448 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DESIGN.md
+29 -5
View File
@@ -1,16 +1,23 @@
# plugin-helper Design
`plugin-helper` is a Python CLI for managing Beat Saber plugins in a mounted Windows BSManager install. It installs from individual GitHub releases, keeps per-game-version plugin selections pinned, records exact filesystem changes, and leaves compatibility judgment visible enough for an agent to help when upstream packaging is inconsistent.
`plugin-helper` is a Python CLI for managing Beat Saber plugins in BSManager
installs. It installs from pinned release artifacts, keeps per-game-version
plugin selections locked, records exact filesystem changes, and leaves
compatibility judgment visible enough for an agent to help when upstream
packaging is inconsistent.
The initial target is the Linux side of `incineroar`, after the Windows partition has been mounted manually. The current Beat Saber instances live under:
The current targets are the local Linux BSManager install and the mounted
Windows BSManager install:
```text
/home/pleb/Windows/Users/pleb/BSManager/BSInstances
/home/pleb/.local/share/BSManager/BSInstances
```
## Goals
- Manage plugins for one BSManager Beat Saber instance at a time, such as `1.40.8`.
- Manage plugins for one BSManager Beat Saber instance at a time, such as
`1.44.1`, while supporting the same instance name under multiple roots.
- Pull plugin releases directly from configured GitHub repositories.
- Determine candidate updates while respecting the pinned Beat Saber version.
- Support selective updates and explicit pins.
@@ -25,8 +32,10 @@ The initial target is the Linux side of `incineroar`, after the Windows partitio
- Replacing BSManager as a GUI or Beat Saber instance manager.
- Downloading or downgrading Beat Saber versions.
- Running `nixos-rebuild switch`.
- Mutating the Windows partition unless the user has mounted it and explicitly runs an apply command.
- Treating Nix as the plugin installer. Nix should package `plugin-helper`; the CLI should manage the mutable mounted game tree.
- Mutating the Windows partition unless the user has mounted it and explicitly
runs an apply command targeting that root.
- Treating Nix as the plugin installer. Nix should package `plugin-helper`; the
CLI should manage mutable game trees.
## Core Model
@@ -82,6 +91,21 @@ Runtime state should not need to live inside the repository. By default, keep mu
For early development, a `--state-dir` option is useful so plans and manifests can be kept in the repo while the format settles.
When managing both local Linux and mounted Windows installs, install state must
be separated by target root as well as by instance name. The current state
layout is keyed by instance name, so two `1.44.1` installs should not share one
state directory. A practical repo-local convention is:
```text
.state/ local Linux BSManager state
.state-windows/ mounted Windows BSManager state
```
The registry and lockfile remain shared for a Beat Saber version. Downloads may
be copied or re-fetched into each target-specific state directory, but generated
plans, bootstrap records, backups, and `installed.json` belong to one target
game tree.
## Registry
The registry describes plugin sources and install behavior. It should be human-editable because many Beat Saber plugins have small packaging differences.