pleb
86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
<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:
|
|
|
|
```bash
|
|
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.
|