plugin-helper/docs/notes/install-and-verify-plugins-1.44.1.md

Beat Saber 1.44.1 Plugin Install and Verification

Tracking document for installing plugins into the Beat Saber 1.44.1 instance with plugin-helper, then verifying the game loads and the IPA log stays clean enough to continue.

Goal for this pass: get a working 1.44.1 plugin set. If a plugin blocks startup, breaks song loading, or produces serious IPA errors, omit it and record the failure. Do not fix incompatible plugins today.

Source Baseline

Use docs/notes/mods-used-in-1.40.8.md as the starting inventory.

• 1.40.8 was installed through bs-manager plus some manual/private plugin drops.
• 1.44.1 was installed through bs-manager for the game only.
• 1.44.1 plugins should be installed through plugin-helper, not bs-manager.
• BeatMods and GitHub release metadata may differ from the 1.40.8 set, so every selected plugin needs an explicit source/version recorded before install.
• Prefer upstream GitHub releases as the artifact source for normal plugins. Use BeatMods as compatibility/dependency metadata by default, and as an artifact source only when the upstream artifact is inaccessible, the package is effectively BeatMods-only, or the package is a framework/library dependency such as the .NET assemblies.

Current 1.44.1 Instance Observation

As of 2026-06-28, the BSManager-managed 1.44.1 instance at ~/.local/share/BSManager/BSInstances/1.44.1 appears to be an unpatched vanilla game tree:

• root IPA/, IPA.exe, winhttp.dll, Libs/, Logs/, and UserData are absent
• root Plugins/ exists only because it was created manually and is empty
• the only pre-existing Plugins directory was Beat Saber_Data/Plugins, which contains Unity/runtime native DLLs and must not be treated as the BSIPA mod folder

By contrast, the Steam install for the same game version 1.44.1_20239 has BSIPA instrumentation and support files at the game root:

• IPA/, IPA.exe, winhttp.dll
• Libs/
• populated root Plugins/
• Logs/_latest.log
• UserData/

This means BSManager's mod installation step does more than place user-selected plugin DLLs. It also materializes the BSIPA loader and shared library substrate that make IPA logs and BSIPA plugin loading possible. plugin-helper needs to model that bootstrap layer separately from ordinary plugin batches.

The vanilla BSManager 1.44.1 launch did not produce an IPA log because BSIPA was not present. It did produce a Unity Player.log under BSManager's shared Proton compatdata and reached Steam/game initialization. So the missing bootstrap layer is not proven to be required for vanilla Beat Saber to execute, but it is required for the modded workflow and may affect the BSManager launch behavior we are trying to reproduce.

Verification Loop

Use the canonical smoketest workflow in docs/SMOKETEST.md.

For each batch:

1. Back up or snapshot the current 1.44.1 plugin state.
2. Install the selected batch with plugin-helper.
3. Start Beat Saber 1.44.1 with the foreground timeout 10 Proton/FPFC launch.
4. Watch the IPA log during launch and first menu load.
5. Load a known-good custom song if the batch affects songs, playlists, maps, or leaderboards.
6. Record result in this document.
7. If the game fails to load or logs serious plugin errors, remove the failing plugin or batch and retry.

Suggested log checks:

• startup reaches main menu
• no plugin dependency resolution failures
• no repeated unhandled exceptions
• no missing assembly errors
• no hard failures from BSIPA, SiraUtil, BSML, SongCore, or CustomJSONData
• custom songs still enumerate
• playlist and downloader UI still opens when relevant

Status Legend

• todo: not attempted
• planned: source selected, ready to install
• installed: copied into the instance
• verified: game launched and basic behavior checked
• verified with warning: game launched, but the log had a non-blocking warning to track
• omitted: skipped for this 1.44.1 pass due to failure or missing compatible release
• defer: intentionally left for a later pass

plugin-helper Work Needed

Track the tool work discovered while using it for 1.44.1.

Item	Status	Notes
Add or generate a 1.44.1 lockfile	todo	Need exact versions, sources, hashes, and target paths.
Model BSIPA/bootstrap installation separately	todo	BSManager creates root IPA/, IPA.exe, winhttp.dll, Libs/, Logs, UserData, and root Plugins/.
Resolve BeatMods dependency closure	todo	Use as metadata/advisory input even when downloading plugin artifacts from upstream GitHub.
Install BeatMods library payloads into Libs/	todo	Include framework-library cases when required; these are likely exceptions to GitHub-preferred sourcing.
Support local/private plugin payloads	todo	Needed for paid closed-source and manual plugins.
Record install state for every copied file	todo	Required for rollback and clean omission testing.
Add a batch install workflow or documented command sequence	todo	Useful for two-or-three-at-a-time validation.
Add IPA log inspection helper	todo	Nice-to-have; manual log watching via docs/SMOKETEST.md is acceptable today.

Batch Plan

Install in small batches. Dependencies may be installed earlier than the plugin that made them necessary, but record that relationship when it is known.

Batch 0: Game and Loader Baseline

Purpose: verify the clean 1.44.1 game and loader before adding gameplay mods.

Plugin	Status	Source/version	Verification notes
BSIPA	verified	GitHub nike4613/BeatSaber-IPA-Reloaded tag 4.3.7, asset BSIPA-net472-x64.zip; BeatMods version id 2561, zipHash 947774ef1010ff809ae05e345e269a90	GitHub asset is byte-identical to the BeatMods CDN zip used for initial bootstrap. Smoketest produced Logs/_latest.log; IPA reported game version 1.44.1 and BSIPA 4.3.7.

Batch 1: Core Song Loading

Purpose: get custom song loading working before UI, leaderboard, or cosmetic mods are added.

Plugin	Status	Source/version	Verification notes
SongCore	verified	BeatMods 3.16.0, version id 2564, zipHash 0af9c0a03074c17ca15c1b667a0e30c8; BeatMods preferred repo Kylemc1413/SongCore currently has no matching 3.16.0 GitHub release asset	IPA loaded SongCore; full song refresh loaded 2 songs from CustomLevels. Keep as BeatMods CDN fallback until a matching upstream asset is found.
BeatSaberMarkupLanguage	verified	GitHub monkeymanboy/BeatSaberMarkupLanguage tag v1.14.1, asset BeatSaberMarkupLanguage-v1.14.1+bs.1.41.1-RELEASE.zip; BeatMods version id 2567, zipHash 46149d03f8549e07f2c88fefde4337b2	GitHub asset is byte-identical to the BeatMods CDN zip used for initial bootstrap. IPA loaded BSML; font fallback warnings only.
SiraUtil	verified	GitHub Auros/SiraUtil tag v3.3.1, asset SiraUtil-v3.3.1+bs.1.42.0.zip; BeatMods version id 2565, zipHash ae14f7d3192a919d5d996c802fbde037	GitHub asset is byte-identical to the BeatMods CDN zip used for initial bootstrap. IPA loaded SiraUtil and installed app/menu installers.

Batch 2: Custom Map Capabilities

Purpose: enable common map extensions after basic song loading is proven.

Plugin	Status	Source/version	Verification notes
CustomJSONData	verified	GitHub Aeroluna/CustomJSONData tag v2.6.8, asset CustomJSONData-2.6.8+1.40.0-bs1.40.0-7c2c32c.zip; BeatMods version id 2327, zipHash fed31638bbb678580ef760ec83cfd486	GitHub asset is byte-identical to the BeatMods CDN zip. IPA loaded CustomJSONData 2.6.8+1.40.0; game reached main initialization; SongCore still loaded 2 custom songs.
Heck	omitted	No BeatMods verified 1.44.1 entry found on 2026-06-28	Required by Chroma/NoodleExtensions/Vivify; skip until a compatible source is identified.
Chroma	omitted	No BeatMods verified 1.44.1 entry found on 2026-06-28	Skip until Heck and a compatible Chroma source are identified.
NoodleExtensions	omitted	No BeatMods verified 1.44.1 entry found on 2026-06-28	Skip until Heck and a compatible NoodleExtensions source are identified.
Vivify	omitted	No BeatMods verified 1.44.1 entry found on 2026-06-28	Skip until Heck and a compatible Vivify source are identified.

Batch 3: Downloaders and Playlists

Purpose: restore in-game song discovery and playlist management.

Plugin	Status	Source/version	Verification notes
BeatSaverDownloader	verified with warning	BeatMods 6.0.7, version id 2217, zipHash a740c6e68a9b5d1dfda3cc8e81f7cf06; BeatMods preferred repo Top-Cat/BeatSaverDownloader exposes no release assets through the GitHub releases API	IPA loaded BeatSaver Downloader 6.0.7 and started its internal webserver. Warning: it probed for missing BetterSongList.dll with IPA library-loader CRITICAL lines, then continued.
PlaylistManager	omitted	No BeatMods verified 1.44.1 entry found on 2026-06-28	Skip until a compatible source is identified.
BeatSaverUpdater	verified	GitHub ibillingsley/BeatSaverUpdater tag 1.2.11, asset BeatSaverUpdater-1.2.11-bs1.39.1-3698f98.zip; BeatMods version id 2352, zipHash d9ea8dd0cbaac66cbb02fa59a548e42b	GitHub asset is byte-identical to the BeatMods CDN zip. IPA loaded BeatSaverUpdater 1.2.11.
BeatSaverVoting	omitted	No BeatMods verified 1.44.1 entry found on 2026-06-28	Skip until a compatible source is identified.
BeatSaberPlaylistsLib	verified	BeatMods 1.7.2, version id 2175, zipHash a3418b75ed7294a3856f3eca12bbd672; BeatMods preferred repo Meivyn/BeatSaberPlaylistsLib exposes no release assets through the GitHub releases API	IPA loaded BeatSaberPlaylistsLib 1.7.2.
BeatSaverSharp	verified	BeatMods 3.4.5, version id 1831, zipHash be37e13e93d9ac7da4efbdc3f514fa8f; BeatMods preferred repo lolPants/BeatSaverSharp was inaccessible through the GitHub releases API	IPA loaded BeatSaverSharp 3.4.5.
ScoreSaberSharp	verified with warning	BeatMods 0.1.0, version id 445, zipHash 8713168c598577ee7c73fa3cf0e26f5c; BeatMods lists scoresaber.com rather than a GitHub release source	IPA loaded ScoreSaberSharp 0.1.0. Warning: bare manifest does not declare files.
BS Utils	verified	BeatMods 1.14.3, version id 2563, zipHash 918d13ac2821a3a17b2819f8861453e9; BeatMods preferred repo Kylemc1413/Beat-Saber-Utils exposes no matching 1.14.3 GitHub release asset	IPA loaded BS Utils 1.14.3.
Ini Parser	verified	BeatMods 2.5.9, version id 1352, zipHash 5df74ad1c6b120fecdc615dd55f15b88	IPA loaded INI Parser 2.5.9.
ImageSharp	verified	BeatMods 2.0.0, version id 1428, zipHash b642fec88b0f84a0643ebd401d08da35	IPA loaded ImageSharp 2.0.0.
System.IO.Compression	verified with warning	BeatMods 4.6.57, version id 1763, zipHash a4e9e26f61967e56168e08eecb01ab88	IPA loaded System.IO.Compression 4.6.57. Warning: duplicate-library notice because the game also ships this assembly.
System.IO.Compression.FileSystem	verified	BeatMods 4.7.3056, version id 1762, zipHash e19f6fd395d54de7bfcbbbe3084dea28	IPA loaded System.IO.Compression.FileSystem 4.7.3056.

Batch 4: Leaderboards and Ranking

Purpose: add online leaderboard/ranking integrations after core song behavior is stable.

Plugin	Status	Source/version	Verification notes
ScoreSaber	todo	TBD	Verify menu panel and song leaderboard.
BeatLeader	todo	TBD	Verify menu panel and song leaderboard.
LeaderboardCore	todo	TBD	Dependency for BeatLeader.
AccSaber	todo	TBD	Manual/plugin-helper registry candidate.
SongRankedBadge	todo	TBD	Verify song-list badges.

Batch 5: Practice and Gameplay Tweaks

Purpose: add small gameplay helpers two or three at a time.

Plugin	Status	Source/version	Verification notes
IntroSkip	todo	TBD	Verify song start behavior.
FailButton	todo	TBD	Verify practice/fail UI behavior.
EasyOffset	todo	TBD	Verify settings UI opens.
GottaGoFast	todo	TBD	Verify startup and song load.
HitsoundTweaks	todo	TBD	Verify settings and audio behavior.
KeepMyOverridesPls	todo	TBD	Verify startup only unless override test is easy.
SoundReplacer	todo	TBD	Verify startup and settings.
KeyRemapper	todo	TBD	Manual install candidate.
SquatToBegin	todo	TBD	Manual install candidate.
JDFixer	todo	TBD	Manual install candidate.

Batch 6: UI and Song Browser

Purpose: restore song-list, menu, and visualization conveniences.

Plugin	Status	Source/version	Verification notes
BetterSongList	todo	TBD	Verify song browser opens and filters work.
HitScoreVisualizer	todo	TBD	Verify settings UI and in-song display.
DiTails	todo	TBD	Verify details panel.
HideTheLogo	todo	TBD	Verify menu loads.
SongChartVisualizer	todo	TBD	Verify chart UI.
WhyIsThereNoLeaderboard	todo	TBD	Source TBD from 1.40.8 install.
Setlist	todo	local build or release	Requires BeatLeader signed in, PlaylistManager, and BeatSaberPlaylistsLib; verify Setlist log lines.
Custom Campaigns	todo	TBD	Manual install candidate.

Batch 7: Cosmetic, Camera, and Lighting

Purpose: add visual and stream-facing mods after functional mods are stable.

Plugin	Status	Source/version	Verification notes
AdBlocker	todo	TBD	Verify startup.
HighlightBombs	todo	TBD	Verify in-song visuals.
PitchBlack	todo	TBD	Verify lighting behavior.
Dimmer	todo	TBD	Manual install candidate.
ReeCamera	todo	TBD	Manual install candidate.
ReeSabers	todo	TBD	Manual install candidate.

Batch 8: Paid or Closed-Source Plugins

Purpose: restore private plugin set only after public/dependency-heavy mods are known good.

Plugin	Status	Source/version	Verification notes
BeatSaberPlus_Chat	todo	local/private	Verify startup and module UI.
BeatSaberPlus_ChatEmoteRain	todo	local/private	Verify startup.
BeatSaberPlus_ChatIntegrations	todo	local/private	Verify startup.
BeatSaberPlus_ChatRequest	todo	local/private	Verify startup.
BeatSaberPlus_GameTweaker	todo	local/private	Verify startup.
BeatSaberPlus_MenuMusic	todo	local/private	Verify startup.
BeatSaberPlus_Multiplayer	todo	local/private	Verify startup.
BeatSaberPlus_NoteTweaker	todo	local/private	Verify startup.
BeatSaberPlus_SongChartVisualizer	todo	local/private	Verify startup.
BeatSaberPlus_SongOverlay	todo	local/private	Verify startup.
NalulunaMenu	todo	local/private	Verify startup and menu.
NalulunaCounters	todo	local/private	Verify in-song counters.
NalulunaLevelDetail	todo	local/private	Verify song detail panel.
NalulunaSliceVisualizer	todo	local/private	Verify in-song visuals.
NalulunaSongPreview	todo	local/private	Verify song preview.
NalulunaMissIndicator	todo	local/private	Verify in-song visuals.
NalulunaEnergy	todo	local/private	Verify in-song HUD.
NalulunaFps	todo	local/private	Verify overlay.
NalulunaPPCoin	todo	local/private	Verify startup.
NalulunaRewinder	todo	local/private	Verify startup.
NalulunaAvatars	todo	local/private	Verify avatar load.
NalulunaShaders	todo	local/private	Verify dependency for Naluluna visuals.
NalulunaSkybox	todo	local/private	Verify skybox sample manifest and skybox load.
NalulunaUtils	todo	local/private	Verify dependency load.

Shared Libraries and Dependency Packages

These should be installed because selected plugins require them, not because they are user-facing features.

Package	Status	Required by	Source/version	Verification notes
AssetBundleLoadingTools	todo	Vivify	TBD	Usually Libs/.
BS Utils	verified	BeatSaverDownloader, BeatLeader	BeatMods 1.14.3, version id 2563, zipHash 918d13ac2821a3a17b2819f8861453e9	IPA loaded BS Utils 1.14.3.
CameraUtils	todo	Vivify	TBD	Verify no missing assembly errors.
ImageSharp	verified	BeatSaberPlaylistsLib	BeatMods 2.0.0, version id 1428, zipHash b642fec88b0f84a0643ebd401d08da35	IPA loaded ImageSharp 2.0.0.
Ini Parser	verified	BS Utils	BeatMods 2.5.9, version id 1352, zipHash 5df74ad1c6b120fecdc615dd55f15b88	IPA loaded INI Parser 2.5.9.
LookupID	todo	Chroma	TBD	Verify no missing assembly errors.
OpenVR API	todo	TBD	TBD	Include only if a 1.44.1 dependency needs it.
protobuf-net	todo	SongDetailsCache	TBD	Usually Libs/.
SongDetailsCache	todo	BetterSongList, SongRankedBadge	TBD	Verify cache startup.
System.IO.Compression	verified with warning	BeatSaberPlaylistsLib, System.IO.Compression.FileSystem	BeatMods 4.6.57, version id 1763, zipHash a4e9e26f61967e56168e08eecb01ab88	IPA loaded System.IO.Compression 4.6.57; logged a duplicate-library notice because the game also ships this assembly.
System.IO.Compression.FileSystem	verified	BeatSaverDownloader	BeatMods 4.7.3056, version id 1762, zipHash e19f6fd395d54de7bfcbbbe3084dea28	IPA loaded System.IO.Compression.FileSystem 4.7.3056.
Dynamic Bone	defer	TBD	TBD	Include only if a selected 1.44.1 mod requires it.
Final IK	defer	TBD	TBD	Include only if a selected 1.44.1 mod requires it.

Omitted Plugins

Record plugins skipped for this 1.44.1 pass. This is not a fix list for today.

Plugin	Reason omitted	Evidence/log note	Follow-up
Heck	No BeatMods verified 1.44.1 entry found on 2026-06-28.	Not installed.	Revisit only with a compatible source.
Chroma	No BeatMods verified 1.44.1 entry found on 2026-06-28.	Not installed.	Revisit after Heck is available.
NoodleExtensions	No BeatMods verified 1.44.1 entry found on 2026-06-28.	Not installed.	Revisit after Heck is available.
Vivify	No BeatMods verified 1.44.1 entry found on 2026-06-28.	Not installed.	Revisit after Heck is available.
PlaylistManager	No BeatMods verified 1.44.1 entry found on 2026-06-28.	Not installed.	Revisit only with a compatible source.
BeatSaverVoting	No BeatMods verified 1.44.1 entry found on 2026-06-28.	Not installed.	Revisit only with a compatible source.

Batch Results

Batch	Date	Result	IPA log notes	Action
0	2026-06-28	verified	BSIPA 4.3.7 installed and generated Logs/_latest.log.	Continue to dependency/plugin batches.
1	2026-06-28	verified	BSML, SiraUtil, and SongCore loaded; SongCore loaded 2 custom songs. Warnings: older target game-version metadata, missing Windows fonts, missing CustomWIPLevels/Cache/Info.dat, and one built-in Magic.wav duration approximation.	Treat as acceptable bootstrap baseline.
2	2026-06-28	verified	CustomJSONData loaded; startup reached main initialization; SongCore still loaded 2 custom songs. Warnings: older target game-version metadata, missing Windows fonts, and missing CustomWIPLevels/Cache/Info.dat.	Continue to downloader/playlist batch.
3	2026-06-28	verified with warning	BeatSaverDownloader, BeatSaverUpdater, BeatSaberPlaylistsLib, BeatSaverSharp, ScoreSaberSharp, BS Utils, Ini Parser, ImageSharp, and System.IO.Compression packages loaded; startup reached main initialization; SongCore still loaded 2 custom songs. Warning: BeatSaverDownloader probed for missing BetterSongList.dll with IPA library-loader CRITICAL lines, then continued and started its internal webserver.	Stop here per request; consider installing BetterSongList before deeper downloader UI testing.
4		todo
5		todo
6		todo
7		todo
8		todo