Beat Saber Artifact Policy

Use this policy for plugin install/update/bootstrap tasks and for audit reports that discuss candidate artifacts.

Source Priority

Prefer upstream GitHub release artifacts for ordinary repository-backed plugins.
Use BeatMods primarily as compatibility, dependency, and verification metadata.
Use BeatMods CDN artifacts only for inaccessible upstream assets, BeatMods-only packages, framework/library dependencies, or cases where no matching upstream release asset exists.
Skip paid/private Patreon, Discord, and closed-source sources during automated public update checks. Report them as manual follow-up unless the user provides the artifact and asks to manage it.

Repository Guardrail

For ordinary GitHub-hosted plugins, require an explicit GitHub repository, release URL, or user-provided local planning note before selecting a release.
If the user provided a repo URL but no release URL, query that exact repo's releases and choose the most appropriate non-draft, non-prerelease release for the target instance.
If the user provided no repo or release URL for a plugin install/update, stop and ask for one.
Do not discover a different repository from web search, substitute a fork, or infer the "correct" project from a similar package name.
If the URL is a releases page, use that repo's release API and choose the latest non-draft, non-prerelease release unless the user asks for a tag.
If the URL is a tag URL, use that exact tag.

BeatMods Exceptions

When the user explicitly asks to bootstrap a Beat Saber instance or install verified mods without GitHub URLs, use BeatMods verified metadata to identify compatible versions and dependency closure. Still prefer upstream GitHub assets when BeatMods exposes a gitUrl and a matching release asset can be found.

Record the artifact source plus BeatMods modVersion, version id, zipHash, dependencies, and supported game version in repo notes or lock data when BeatMods metadata drives the selection.

BeatMods dependency entries are mod-version ids. Resolve the selected mod's dependency closure before downloading.

Checksums And Inspection

Download artifacts into the selected helper state directory, normally:
```
<state_dir>/instances/<instance>/downloads/<plugin-id>/
```
Record SHA-256 checksums for downloaded or built artifacts.
Match the checksum against GitHub's digest when available.
For BeatMods CDN artifacts, preserve BeatMods zipHash metadata and verify the downloaded archive against the expected hash when the helper supports it.
Inspect archive contents before selecting install strategy:
```
unzip -l <artifact>
```

Install Strategy Guide

dll-to-plugins: asset is a single .dll that belongs in Plugins/.
bsipa-zip: zip top-level paths are only IPA/, Libs/, or Plugins/.
root-zip: zip contains valid game-root paths outside the BSIPA top-level set. Use this for BSIPA/bootstrap archives because IPA.exe, IPA.runtimeconfig*.json, and root winhttp.dll are game-root files.
zip-to-pending: only when the release is intended for IPA/Pending/.
manual: do not use for installable releases.

BSIPA Bootstrap

Treat BSIPA as a bootstrap phase. bootstrap installs the locked BSIPA archive and records generated files. Ordinary plugin plans should depend on healthy bootstrap state.

For BSIPA bootstrap archives, expect root-relative IPA/ and IPA.exe files whether sourced from GitHub or BeatMods. Extract into the instance root and run IPA.exe -n under the same Proton environment used by the smoke test. This creates or copies root winhttp.dll and root Libs/ substrate files.

3.7 KiB Raw Blame History