# 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