plugin-helper/docs/notes/naluluna-mod-assistant.md

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:

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