docs(help): a page on reporting slow performance, with the switches that measure it #730

Merged
HumanBean merged 1 commit from HumanBean/Longshot:docs/performance-report into main 2026-11-15 07:21:22 +00:00
Owner

Type: docs · Risk: low · Tested on: none (docs only) · Needs: the site preview

Why

When a player says the game is slow or stutters, the team has to explain each time which switches to turn on and what to send back. This adds one page on the site to point them to: a few lines in longshot_env.txt that make the game measure itself, how to capture a run, and what to send.

What changed

A new player page, Help → Report slow performance (/help/performance/), made from docs/performance-report.md. It lists four switches the env file accepts (HOS_FPS_LOG, HOS_THREAD_TIMES, RX_VK_PASS_TIMING, RX_VK_SLOW_LOG), then gives the steps (stay in the slow spot for 60 to 90 s, then Gameplay → Bug report), what to send, and how to turn them off again.

  • docs: docs/performance-report.md (new); docs/reporting-and-contributing.md links to it.
  • website: src/content-pages.ts publishes it at help/performance; astro.config.ts adds it to the Help sidebar.

Switches that name a file (RX_VK_FRAME_LOG, HOS_SAMPLE_ALL) are left out on purpose: longshot_env.txt refuses them (env_line_allowed in host/hos_main.c). The log's own vi: lines already give the fps and the spread of frame times every 5 s.

Measurements

Nothing to measure: a docs page.

Flags and settings

None

Testing

Tested: checked against the source that each switch on the page is accepted from longshot_env.txt (env_line_allowed), and that the default vi: lines log the fps and frame-time spread every 5 s (host/nn_vi.c). No checks or site build were run locally: they are left to CI.

Not tested: the site build and how the page looks, until CI runs or a maintainer adds the preview label (this is from a fork).

Must be tested:

  • The site preview (a maintainer adds the preview label): open /help/performance/, expecting it in the Help sidebar under Report a problem, and its links to Discord, the report form and Common problems to open (by hand: open the preview).

Risks

What could break: the website build, if the page's links or the new sidebar entry are wrong.

Turning it off: revert the commit.

Compatibility: Nothing changes for players after updating.

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). Left to CI: not run locally.
  • 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:** none (docs only) · **Needs:** the site preview ## Why When a player says the game is slow or stutters, the team has to explain each time which switches to turn on and what to send back. This adds one page on the site to point them to: a few lines in `longshot_env.txt` that make the game measure itself, how to capture a run, and what to send. ## What changed A new player page, **Help → Report slow performance** (`/help/performance/`), made from `docs/performance-report.md`. It lists four switches the env file accepts (`HOS_FPS_LOG`, `HOS_THREAD_TIMES`, `RX_VK_PASS_TIMING`, `RX_VK_SLOW_LOG`), then gives the steps (stay in the slow spot for 60 to 90 s, then **Gameplay → Bug report**), what to send, and how to turn them off again. - docs: `docs/performance-report.md` (new); `docs/reporting-and-contributing.md` links to it. - website: `src/content-pages.ts` publishes it at `help/performance`; `astro.config.ts` adds it to the Help sidebar. Switches that name a file (`RX_VK_FRAME_LOG`, `HOS_SAMPLE_ALL`) are left out on purpose: `longshot_env.txt` refuses them (`env_line_allowed` in `host/hos_main.c`). The log's own `vi:` lines already give the fps and the spread of frame times every 5 s. ## Measurements Nothing to measure: a docs page. ### Flags and settings None ## Testing **Tested:** checked against the source that each switch on the page is accepted from `longshot_env.txt` (`env_line_allowed`), and that the default `vi:` lines log the fps and frame-time spread every 5 s (`host/nn_vi.c`). No checks or site build were run locally: they are left to CI. **Not tested:** the site build and how the page looks, until CI runs or a maintainer adds the `preview` label (this is from a fork). **Must be tested:** - The site preview (a maintainer adds the `preview` label): open `/help/performance/`, expecting it in the Help sidebar under Report a problem, and its links to Discord, the report form and Common problems to open (by hand: open the preview). ## Risks **What could break:** the website build, if the page's links or the new sidebar entry are wrong. **Turning it off:** revert the commit. **Compatibility:** Nothing changes for players after updating. ## 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). Left to CI: not run locally. - [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(help): a page on reporting slow performance, with the switches that measure it
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 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 23s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 21s
Third-party parts / As their notes say (pull_request) Successful in 34s
PR description / Description follows the template (pull_request_target) Failing after 17s
Website / Website on Cloudflare (pull_request_target) Failing after 3m3s
11ae8be84f
The game measures itself with a few lines in longshot_env.txt (fps log,
thread times, GPU pass timing, the slow-frame log); the page says which,
how to capture a run and what to send. Published at /help/performance/
and linked from the report page.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Owner

The Must-be-tested item now says what result to expect, and the status line names the preview.

The Must-be-tested item now says what result to expect, and the status line names the preview.
HumanBean changed title from WIP: docs(help): a page on reporting slow performance, with the switches that measure it to docs(help): a page on reporting slow performance, with the switches that measure it 2026-11-15 07:19:42 +00:00
HumanBean deleted branch docs/performance-report 2026-11-15 07:21:22 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
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!730
No description provided.