# 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 this 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 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
repo-local 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).