docs(website): a Mods page: installing mods, turning them off, the load order and checking the log #1210

Merged
HumanBean merged 1 commit from HumanBean/Longshot:docs/website-mods-page into main 2026-11-16 19:15:48 +00:00
Owner

Type: docs · Risk: low · Tested on: not built here (docs only) · Needs: CI's website build and check

Why

The website has no page about mods. A player who wants to install one has to find the README's Mods section on
Forgejo, which is written as a reference, or docs/mods.md, which is the loader's contract for authors. Neither says
where the launcher keeps the game folder, how to turn a mod off, or how to tell from the log whether a mod loaded.

What changed

A new player guide, docs/using-mods.md, published at /mods/ and listed under Get started after Transfer a save.
It covers what works on main today (RomFS file mods) and nothing that is still in a pull request.

  • docs: docs/using-mods.md: before you start (back up saves, stop the game), installing (the launcher's Open
    folder
    , one mods folder per version, the <name>/romfs layout, emulator layouts), turning a mod off (_ or
    -), which mod wins a shared file, resource size tables for mods that make files bigger, the mods: log lines from
    host/mods.c and what each means, and what doesn't work (exefs patches, no mod manager). It ends with links to
    the README's Mods section and docs/mods.md for authors, and HOS_MODS.
  • website: website/src/content-pages.ts adds mods; website/astro.config.ts adds it to the sidebar.
  • docs: docs/updates-and-saves.md's Mods section and the README's Mods section link to the new guide.

Measurements

Nothing to measure: documentation only.

Flags and settings

None.

Testing

Tested: the log lines and the folder rules read against host/mods.c (hos_mods_init, find_mods,
hos_mods_romfs) and the README's Mods section; the links' targets (saves.md#where-longshot-keeps-them,
README.md#mods, mods.md) exist. No game-branding terms from GAME_BRANDING in the new page.

Not tested: no tests or website build were run on this PC; CI runs tests/run_all.py and the website's build and
npm run check.

Must be tested:

  • CI: the website build and npm run check pass with the new page, expecting /mods/ in the sidebar and its links
    resolving (CI's website workflow).

Risks

What could break: the website build, if the new page trips a check.

Turning it off: revert the commit.

Compatibility: Nothing changes.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** docs · **Risk:** low · **Tested on:** not built here (docs only) · **Needs:** CI's website build and check ## Why The website has no page about mods. A player who wants to install one has to find the README's Mods section on Forgejo, which is written as a reference, or `docs/mods.md`, which is the loader's contract for authors. Neither says where the launcher keeps the game folder, how to turn a mod off, or how to tell from the log whether a mod loaded. ## What changed A new player guide, `docs/using-mods.md`, published at `/mods/` and listed under **Get started** after Transfer a save. It covers what works on `main` today (RomFS file mods) and nothing that is still in a pull request. - docs: `docs/using-mods.md`: before you start (back up saves, stop the game), installing (the launcher's **Open folder**, one `mods` folder per version, the `<name>/romfs` layout, emulator layouts), turning a mod off (`_` or `-`), which mod wins a shared file, resource size tables for mods that make files bigger, the `mods:` log lines from `host/mods.c` and what each means, and what doesn't work (`exefs` patches, no mod manager). It ends with links to the README's Mods section and `docs/mods.md` for authors, and `HOS_MODS`. - website: `website/src/content-pages.ts` adds `mods`; `website/astro.config.ts` adds it to the sidebar. - docs: `docs/updates-and-saves.md`'s Mods section and the README's Mods section link to the new guide. ## Measurements Nothing to measure: documentation only. ### Flags and settings None. ## Testing **Tested:** the log lines and the folder rules read against `host/mods.c` (`hos_mods_init`, `find_mods`, `hos_mods_romfs`) and the README's Mods section; the links' targets (`saves.md#where-longshot-keeps-them`, `README.md#mods`, `mods.md`) exist. No game-branding terms from `GAME_BRANDING` in the new page. **Not tested:** no tests or website build were run on this PC; CI runs `tests/run_all.py` and the website's build and `npm run check`. **Must be tested:** - CI: the website build and `npm run check` pass with the new page, expecting `/mods/` in the sidebar and its links resolving (CI's website workflow). ## Risks **What could break:** the website build, if the new page trips a check. **Turning it off:** revert the commit. **Compatibility:** Nothing changes. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
docs(website): a Mods page: installing mods, turning them off, the load order and checking the log
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 6s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 17s
PR description / Description follows the template (pull_request_target) Failing after 5s
5923a776cc
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Collaborator

Possibly related, for context:

  • PR #984 WIP: feat(mods): a mod's code module (exefs/subsdk*) is built in with the game — Open code-mod work affects whether ExeFS support claims remain accurate
  • PR #1089 WIP: feat(mods): an archive several mods have is served as one, each file inside it from the mod that changed it — Open archive-merging work may change mod ordering guidance
  • PR #962 WIP: docs(website): add an experimental multiplayer guide — Overlapping website-guide/navigation work, though on multiplayer
Possibly related, for context: - PR #984 WIP: feat(mods): a mod's code module (exefs/subsdk*) is built in with the game — Open code-mod work affects whether ExeFS support claims remain accurate - PR #1089 WIP: feat(mods): an archive several mods have is served as one, each file inside it from the mod that changed it — Open archive-merging work may change mod ordering guidance - PR #962 WIP: docs(website): add an experimental multiplayer guide — Overlapping website-guide/navigation work, though on multiplayer
HumanBean changed title from WIP: docs(website): a Mods page: installing mods, turning them off, the load order and checking the log to docs(website): a Mods page: installing mods, turning them off, the load order and checking the log 2026-11-16 19:13:04 +00:00
HumanBean deleted branch docs/website-mods-page 2026-11-16 19:15:49 +00:00
Author
Owner

Website preview: https://pr-1210-longshot-website.hckr-5e0.workers.dev/mods/

Uploaded by hand from a PC (wrangler versions upload --preview-alias pr-1210, after npm run build with Node 24.14) at 5923a776cc; production is unchanged. npm run check was not run here: CI's website job runs it.

<!-- website-preview --> **Website preview:** https://pr-1210-longshot-website.hckr-5e0.workers.dev/mods/ Uploaded by hand from a PC (`wrangler versions upload --preview-alias pr-1210`, after `npm run build` with Node 24.14) at 5923a776cc92; production is unchanged. `npm run check` was not run here: CI's website job runs it.
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1210
No description provided.