pleb
109 lines
4.1 KiB
Markdown
109 lines
4.1 KiB
Markdown
# plugin-helper
|
|
|
|
`plugin-helper` is an early Python CLI for managing Beat Saber plugins in BSManager installs.
|
|
|
|
The first implementation focuses on safe local workflows:
|
|
|
|
- discover BSManager instances
|
|
- scan existing `Plugins/` and `Libs/` files
|
|
- read checked-in registry and per-version lockfiles
|
|
- generate a machine-readable install plan from local release assets
|
|
- apply exactly that plan and record install state
|
|
- uninstall only files recorded in install state
|
|
|
|
Default BSManager instance roots:
|
|
|
|
```text
|
|
/home/pleb/Windows/Users/pleb/BSManager/BSInstances
|
|
/home/pleb/.local/share/BSManager/BSInstances
|
|
```
|
|
|
|
Override with `--instances-root` or `PLUGIN_HELPER_INSTANCES_ROOT`. To search
|
|
multiple explicit roots, separate them with `:`.
|
|
|
|
## Commands
|
|
|
|
For normal use, run the menu from the repo root. Use repo-local state so the
|
|
menu sees the same plans, downloads, and install records used by the helper
|
|
workflow:
|
|
|
|
```sh
|
|
PYTHONPATH=src python -m plugin_helper --state-dir .state menu
|
|
```
|
|
|
|
The individual subcommands are mostly for automation and debugging. If you use
|
|
them, pass `--state-dir .state` unless you intentionally want the default live
|
|
state outside this repo.
|
|
|
|
Install assets are currently expected to already exist locally, usually under:
|
|
|
|
```text
|
|
.state/instances/<instance>/downloads/<plugin-id>/
|
|
```
|
|
|
|
## Beat Saber Data Backups
|
|
|
|
`backup-userdata` copies the mounted Windows `UserData` folder and Beat Saber
|
|
Windows app data into the adjacent `../backups` repo. With the Windows mount at
|
|
`~/Windows`, the helper infers Beat Saber's Windows app data as:
|
|
|
|
```text
|
|
/home/pleb/Windows/Users/pleb/AppData/LocalLow/Hyperbolic Magnetism/Beat Saber
|
|
```
|
|
|
|
Example manual backup after mounting Windows:
|
|
|
|
```sh
|
|
PYTHONPATH=src python -m plugin_helper \
|
|
--instances-root /home/pleb/Windows/Users/pleb/BSManager/BSInstances \
|
|
backup-userdata \
|
|
--instance 1.44.1
|
|
```
|
|
|
|
By default the backup repo receives plain copied files under
|
|
`../backups/beat-saber/UserData` and `../backups/beat-saber/AppData`, plus
|
|
`../backups/beat-saber/backup-descriptor.json` describing the source paths from
|
|
the latest backup run. Use
|
|
`--appdata-path <path>` if the Windows profile path ever differs, `--no-appdata`
|
|
for a `UserData`-only sync, or `--backup-root <path>` to choose a different
|
|
destination.
|
|
|
|
The backup intentionally omits bulky/generated data:
|
|
|
|
- `UserData/BeatLeader/Replays`
|
|
- `UserData/BeatLeader/ReplayerCache`
|
|
- `UserData/BeatLeader/LeaderboardsCache`
|
|
- `UserData/BeatLeader/ReplayHeadersCache`
|
|
- `UserData/ScoreSaber/Replays`
|
|
- `UserData/BeatSaberPlus/Cache`
|
|
- `UserData/BeatSaverNotifier.json`
|
|
- `UserData/Accsaber/PlayerScoreCache.json`
|
|
- `UserData/NalulunaAvatars/cache`
|
|
- `UserData/SongDetailsCache.proto`
|
|
- `AppData/com.unity.addressables`
|
|
- `*.log`
|
|
|
|
Other large folders seen in the 1.44.1 `UserData` tree are
|
|
`Custom Campaigns`, `SongCore`, `AssetBundleLoadingTools`, `NalulunaMenu`, and
|
|
`NalulunaSkybox`. Those are not skipped by default because they can contain
|
|
custom content or non-obvious user choices rather than pure cache data.
|
|
|
|
## Operational notes
|
|
|
|
- BSManager can inherit launch arguments configured in Steam for Beat Saber.
|
|
Check both places before debugging black screens or startup hangs. Duplicating
|
|
arguments such as `--no-yeet fpfc` can make the game fail command-line
|
|
parsing after BSIPA and plugins have already loaded.
|
|
- BSIPA is managed as a first-class bootstrap phase. The `bootstrap` command
|
|
applies the locked `bsipa` root archive, runs `IPA.exe -n` through Proton, and
|
|
records every bootstrap-relevant file under root `IPA.exe*`, `winhttp.dll`,
|
|
`Libs/`, and `IPA/`, including backups created during patching.
|
|
- If an instance lockfile includes `bsipa`, ordinary plugin plans require a
|
|
recorded bootstrap state plus a `Logs/_latest.log` that shows BSIPA startup.
|
|
Use `bootstrap-check` before planning a batch when you want a quick gate.
|
|
- Use [`docs/SMOKETEST.md`](docs/SMOKETEST.md) after installing or removing a
|
|
plugin batch. It documents the short Proton/BSManager launch loop, IPA log
|
|
checks, and teardown commands.
|
|
- The 1.44.1 migration tracker lives in
|
|
[`docs/notes/install-and-verify-plugins-1.44.1.md`](docs/notes/install-and-verify-plugins-1.44.1.md).
|