Add Naluluna mods and BSplus mods

2026-06-29 15:34:46 -07:00
parent 6117173507
commit 13d9481168
2 changed files with 234 additions and 26 deletions
@@ -0,0 +1,203 @@
+# NalulunaModAssistant Source and Install Notes
+
+This note records how NalulunaModAssistant behaves when used to install
+Patreon-only Naluluna mods. It is intended to guide future `plugin-helper`
+support for private/local payloads without checking private artifacts,
+session-specific URLs, or account data into the repo.
+
+Observed run:
+
+- Date: 2026-06-29
+- Assistant path: `C:\Users\pleb\Apps\Naluluna\NalulunaModAssistant.exe`
+- Assistant version: `1.5.1`
+- Runtime UI: WebView2 `149.0.4022.80`
+- Log path: `C:\Users\pleb\Apps\Naluluna\Logs\NalulunaModAssistant\_latest.log`
+
+## High-Level Flow
+
+NalulunaModAssistant is a WebView2 desktop app. It authenticates the user through
+an embedded browser, fetches a versioned mod catalog, then downloads selected
+plugin archives into a temporary working directory before extracting them into
+the configured Beat Saber directory.
+
+The observed Patreon flow was:
+
+1. Initialize WebView2 and a temporary working directory.
+2. Load the initial catalog JSON named `start`.
+3. Navigate to Patreon at `https://www.patreon.com/c/naluluna/posts`.
+4. Resolve the NalulunaModAssistant files post:
+   `https://www.patreon.com/naluluna/posts/nalulunamodassis-74489236`.
+5. Confirm the logged-in Patreon account has access.
+6. Detect Beat Saber version `1.44.1`.
+7. Select mod list version `1.42.0`.
+8. Fetch the catalog JSON named `1-42-0`.
+9. Download selected archives and extract their payloads into the configured
+   Beat Saber tree.
+
+The assistant binary also contains a `GetJsonFromGoogleSiteAsync` code path and
+Fanbox login/status paths. Those appear to be alternate or older source flows.
+The 2026-06-29 run used Patreon, not Google Sites, GitHub, BeatMods, or Fanbox.
+
+## Source Model
+
+Naluluna plugin artifacts are not normal public GitHub or BeatMods releases.
+For Patreon installs, the authoritative source is the private
+NalulunaModAssistant Patreon post and its attachment metadata.
+
+The assistant downloads files through two forms:
+
+- Relative catalog paths such as `nma/files/NalulunaUtils-5.7.0-bs1.44.0.zip`
+  and `nma/imgs/NalulunaCounters.jpg`.
+- Patreon file endpoints such as `https://www.patreon.com/file?...`, which
+  resolve to tokenized `patreonusercontent.com` CDN URLs after authentication.
+
+Do not record tokenized CDN URLs, cookies, WebView profile data, or private
+account identifiers in repo files. They are session-specific and may grant access
+to paid artifacts. For lockfile-style notes, record the Patreon post, the
+assistant-visible archive name, the mod version, the Beat Saber target string,
+the installed paths, and local file hashes when available.
+
+## Catalog Versioning
+
+In the observed run, the game was `1.44.1` but the assistant selected
+`modListVersion: 1.42.0` and fetched catalog node `1-42-0`.
+
+That means the assistant's catalog version should not be assumed to exactly
+match the game version. Treat it as an upstream compatibility bucket. For
+documentation and locks, record both values:
+
+- actual game version reported by the assistant
+- mod list version selected by the assistant
+
+## Install Target
+
+The assistant reads and writes a configured Beat Saber directory, not a
+BSManager instance root chosen by `plugin-helper`.
+
+Observed config:
+
+- Beat Saber directory:
+  `C:\Program Files (x86)\Steam\steamapps\common\Beat Saber`
+- Working directory:
+  `C:\Users\pleb\AppData\Local\Temp\tmp97E.tmp`
+
+This matters because the observed run installed into the Steam Beat Saber tree,
+not the BSManager `1.44.1` instance at
+`C:\Users\pleb\BSManager\BSInstances\1.44.1`.
+
+Before using NalulunaModAssistant as a source for a BSManager instance, either:
+
+- point the assistant at the intended BSManager instance root, if the UI allows
+  it, or
+- treat the Steam install as a staging source and copy exact installed files into
+  the target instance through a `plugin-helper` local/private payload workflow.
+
+Do not manually copy files into the live instance as a substitute for
+`plugin-helper` state tracking unless this is an explicit one-off recovery step.
+
+## Extraction Behavior
+
+Archives are extracted relative to the Beat Saber directory. The observed
+payloads wrote to these top-level areas:
+
+- `Plugins/`
+- `Libs/Native/`
+- `UserData/NalulunaUtils/`
+- `UserData/NalulunaSkybox/`
+- `NalulunaAvatars/`
+
+Examples from the observed run:
+
+- `Plugins/NalulunaUtils.dll`
+- `Plugins/NalulunaAvatars.dll`
+- `Plugins/NalulunaSkybox.dll`
+- `Plugins/NalulunaSkyboxSamples.manifest`
+- `Libs/Native/OVRLipSync.dll`
+- `UserData/NalulunaUtils/OpenVRHelper/OpenVRHelper.exe`
+- `UserData/NalulunaSkybox/*.jpgx`
+- `NalulunaAvatars/AliciaSolid.vrm`
+
+Some packages install manifests or data assets instead of a plugin DLL. A
+`plugin-helper` implementation should record every extracted file, not just the
+primary DLL.
+
+## Observed Install Batch
+
+The 2026-06-29 run installed the following selected packages:
+
+- `NalulunaShaders` `2.1.3`, archive
+  `NalulunaShaders-2.1.3-bs1.39.1.zip`
+- `NalulunaUtils` `5.7.0`, archive
+  `NalulunaUtils-5.7.0-bs1.44.0.zip`
+- `AliciaSolid` `1.10.0`, archive
+  `AliciaSolid-1.10.0-bs1.26.0.zip`
+- `NalulunaAvatars` `1.10.0`
+- `NalulunaSkybox` `2.0.0`
+- `OpenVRHelper` `0.2.3`
+- `NalulunaRewinder` `1.2.0`
+- `NalulunaCounters` `1.3.2`
+- `NalulunaEnergy` `1.1.0`
+- `NalulunaLevelDetail` `2.0.0`
+- `NalulunaSongPreview` `1.0.1`
+- `NalulunaSkyboxSamples` `1.1.0`
+
+The first `NalulunaUtils` attempt downloaded successfully but failed extraction
+with a Windows file-lock error:
+
+```text
+The process cannot access the file
+'C:\Users\pleb\AppData\Local\Temp\tmp97E.tmp\NalulunaUtils-5.7.0-bs1.44.0.zip'
+because it is being used by another process.
+```
+
+A later retry succeeded and extracted `Plugins/NalulunaUtils.dll`.
+
+Several downloads log `download interrupted: FileSecurityCheckFailed` after a
+successful install. In the observed run, those messages did not necessarily mean
+the mod failed; the assistant logged `Installed: ...` first. Treat this message
+as a warning to cross-check against extracted files and the assistant's final
+success/failure count.
+
+## Implications for plugin-helper
+
+Private Naluluna payloads should be modeled as local/private artifacts rather
+than first-class remote fetches until there is an explicit supported way to
+authenticate and download them safely.
+
+Recommended near-term workflow:
+
+1. Use NalulunaModAssistant to download/install into a staging Beat Saber tree.
+2. Inspect the assistant log for selected package names, versions, archive names,
+   and extracted paths.
+3. Hash the installed files or preserved archives.
+4. Add a `plugin-helper` local/private payload entry for each package.
+5. Apply that payload to the intended BSManager instance with normal install
+   state recording.
+6. Smoketest the BSManager instance and record results in
+   `docs/notes/install-and-verify-plugins-1.44.1.md`.
+
+Longer term, `plugin-helper` could add a "local archive import" command that
+accepts a zip from the assistant's working directory or a saved local cache,
+normalizes the extracted paths, computes hashes, and creates an auditable
+install plan without needing to understand Patreon authentication.
+
+## What Not To Commit
+
+Do not commit:
+
+- downloaded private plugin archives
+- tokenized `patreonusercontent.com` URLs
+- WebView2 profile data
+- Patreon or Fanbox cookies
+- full `_patreon.log` / `_fanbox.log` captures
+- account identifiers from logs
+
+Safe to commit:
+
+- assistant version
+- Patreon post URL
+- package names and versions
+- non-tokenized archive names shown by the assistant
+- extracted relative paths
+- hashes of local artifacts or installed files
+- compatibility and smoketest notes