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:

/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 :.

Managing Multiple Installs

The helper is intended to manage both the local Linux BSManager install and the mounted Windows install. Lockfiles and registry entries are shared by Beat Saber version, but install state is target-specific. When the same instance name exists under both roots, such as 1.44.1, use an explicit --instances-root and a separate state directory for each target.

Suggested repo-local convention:

.state/          local Linux BSManager state
.state-windows/  mounted Windows BSManager state

Examples:

PYTHONPATH=src python -m plugin_helper \
  --instances-root /home/pleb/.local/share/BSManager/BSInstances \
  --state-dir .state \
  installed --instance 1.44.1

PYTHONPATH=src python -m plugin_helper \
  --instances-root /home/pleb/Windows/Users/pleb/BSManager/BSInstances \
  --state-dir .state-windows \
  installed --instance 1.44.1

Do not reuse the same state directory for both targets when their instance names match. The current state layout is keyed by instance name, so sharing one state directory would mix bootstrap records, generated plans, backups, and installed file records for different game trees.

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:

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 or are intentionally targeting the Windows install with .state-windows.

Install assets are currently expected to already exist locally, usually under:

.state/instances/<instance>/downloads/<plugin-id>/

For a second target-specific state directory, copy or re-download the same locked assets under that state root before planning. For example:

.state-windows/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:

/home/pleb/Windows/Users/pleb/AppData/LocalLow/Hyperbolic Magnetism/Beat Saber

Example manual backup after mounting Windows:

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.

restore-userdata copies those backup trees back into a target instance. It moves the current UserData and AppData trees aside first as <name>.pre-restore-<timestamp> snapshots. On Linux BSManager installs, AppData is restored into the BSManager SharedContent Proton prefix unless --appdata-path is provided. If backup-descriptor.json is present, its instance field must match --instance.

Example restore into the local Linux instance:

PYTHONPATH=src python -m plugin_helper \
  --instances-root /home/pleb/.local/share/BSManager/BSInstances \
  restore-userdata \
  --instance 1.44.1

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 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.