docs: play on the Steam Deck: what to expect, which switches help, and the clock setting (#716) #968

Merged
HumanBean merged 2 commits from omgitsgela/Longshot:docs/steam-deck-playbook into main 2026-11-15 23:40:36 +00:00
Contributor

Type: docs · Risk: low · Tested on: Steam Deck LCD (Jupiter, Vangogh), SteamOS holo · Needs: the site preview

Why

Deck players install like it's a desktop PC and then judge the game by their first
minute: auto GPU clocks, an SD-card install, FSR 4 because it is newest, Threaded
rendering because the menu offers it. Most of those choices measure worse on this
hardware, and the two that measure better are two switches nobody tells them about.
This is what we learned running Longshot on a Deck LCD for a week — one page, from
install to the two switches and the one clock line, so a Deck player starts where we
ended.

See #716 (this page is the player-facing half of it; the automation ask stands).
See #386 (SD vs internal drive), #73 (intro movies), #750 (Hyrule Town spin).

What changed

  • New player page docs/steam-deck-playbook.md, published at install/steam-deck
    (website/src/content-pages.ts, sidebar in website/astro.config.ts), linked from
    Getting started under the SteamOS paragraph.
  • Two measured-run files under docs/tested/ (2026-11-15-steam-deck-lcd-omgitsgela-run03..04):
    today's main at the worst save (the page's headline expectation) and the intro-movie skip
    counts on merged main at stock clocks. scripts/tested_configurations.py validates both.
    The launch-state clock arms the page's clock section leans on live on #716 itself, where
    the claim lives, not here.
  • What the page claims, and what it deliberately does not: it gives the two switches with
    #238's own numbers, the clock line with our paired arms, and the fps a player should
    expect per area kind. It tells players to keep FSR 4 off on RDNA2 (measured 15.7 vs
    FSR 3.1's 20.6 on Deck) and Threaded off (parity-to-worse on Deck). It states the intro
    movie improvement as direction, not a clean single-change number, because the settings
    differed between eras — the row says exactly that.

Measurements

Docs only, nothing to measure in code. The two docs/tested/ rows carry the Deck
measurements themselves, including the honest caveat where a comparison is era-crossing
rather than interleaved (run04's intro line: the pacing engage line did not fire in
those two arms, recorded rather than explained away).

Flags and settings

None added or changed. The page documents two existing switches (RX_VK_READBACK_LATE,
HOS_SHORT_SLEEP_TIMER) at their shipped defaults.

Testing

Tested: on the Deck itself — every number on the page comes from scripted arms on
real Deck LCD hardware (rows in docs/tested/); the fragment validator passes
(scripts/tested_configurations.py, rc 0); tests/run_all.py gives the same result
on this branch and on the rebased base (533 passed, 20 failed, 90 skipped on both).
The 20 are the same host-environment tests that fail on main here, named:
test_linux_update, test_lift_cleanup_error, test_make_game_cache,
test_bake_portability, test_bug_report, test_crt_options,
test_appimage_player_build, test_env_on, test_crash_dialog,
test_hardware_report, test_missing_nup, test_link_skip,
test_options_budget_once, test_mods_size_table, test_pipeline_tour,
test_readback_late, test_run_all_changed, test_vk_pgo, test_walk_key,
test_vk_occlusion_queries — none touches this change (docs and website wiring only).

Not tested: the website render of the new sidebar entry and page.

Must be tested:

  • any desktop, docs preview: install/steam-deck renders in the Get started sidebar and
    the page's links to common-issues and performance-report resolve as site links
    (Test Farm: @Beanstalk docs, the site preview).
  • Steam Deck LCD, anyone's: follow the clock-line section as written, expecting
    power_dpm_force_performance_level to read high afterwards (by hand; we measured
    this exact line on our Deck).

Risks

What could break: only the site nav; a wrong slug would 404 the new page.
Turning it off: revert the commit.
Compatibility: Nothing changes for the game.

Issues

See #716
See #386
See #73
See #750

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.
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • Docs updated.

WIP until the site preview passes; keeping it WIP is per the template's Needs line.

**Type:** docs · **Risk:** low · **Tested on:** Steam Deck LCD (Jupiter, Vangogh), SteamOS holo · **Needs:** the site preview ## Why Deck players install like it's a desktop PC and then judge the game by their first minute: auto GPU clocks, an SD-card install, FSR 4 because it is newest, Threaded rendering because the menu offers it. Most of those choices measure *worse* on this hardware, and the two that measure *better* are two switches nobody tells them about. This is what we learned running Longshot on a Deck LCD for a week — one page, from install to the two switches and the one clock line, so a Deck player starts where we ended. See #716 (this page is the player-facing half of it; the automation ask stands). See #386 (SD vs internal drive), #73 (intro movies), #750 (Hyrule Town spin). ## What changed - New player page **docs/steam-deck-playbook.md**, published at `install/steam-deck` (`website/src/content-pages.ts`, sidebar in `website/astro.config.ts`), linked from Getting started under the SteamOS paragraph. - Two measured-run files under `docs/tested/` (`2026-11-15-steam-deck-lcd-omgitsgela-run03..04`): today's main at the worst save (the page's headline expectation) and the intro-movie skip counts on merged main at stock clocks. `scripts/tested_configurations.py` validates both. The launch-state clock arms the page's clock section leans on live on #716 itself, where the claim lives, not here. - What the page claims, and what it deliberately does not: it gives the two switches with #238's own numbers, the clock line with our paired arms, and the fps a player should expect per area kind. It tells players to keep FSR 4 off on RDNA2 (measured 15.7 vs FSR 3.1's 20.6 on Deck) and Threaded off (parity-to-worse on Deck). It states the intro movie improvement as direction, not a clean single-change number, because the settings differed between eras — the row says exactly that. ## Measurements Docs only, nothing to measure in code. The two `docs/tested/` rows carry the Deck measurements themselves, including the honest caveat where a comparison is era-crossing rather than interleaved (run04's intro line: the pacing engage line did not fire in those two arms, recorded rather than explained away). ## Flags and settings None added or changed. The page documents two existing switches (`RX_VK_READBACK_LATE`, `HOS_SHORT_SLEEP_TIMER`) at their shipped defaults. ## Testing **Tested:** on the Deck itself — every number on the page comes from scripted arms on real Deck LCD hardware (rows in `docs/tested/`); the fragment validator passes (`scripts/tested_configurations.py`, rc 0); `tests/run_all.py` gives the *same* result on this branch and on the rebased base (`533 passed, 20 failed, 90 skipped` on both). The 20 are the same host-environment tests that fail on `main` here, named: `test_linux_update`, `test_lift_cleanup_error`, `test_make_game_cache`, `test_bake_portability`, `test_bug_report`, `test_crt_options`, `test_appimage_player_build`, `test_env_on`, `test_crash_dialog`, `test_hardware_report`, `test_missing_nup`, `test_link_skip`, `test_options_budget_once`, `test_mods_size_table`, `test_pipeline_tour`, `test_readback_late`, `test_run_all_changed`, `test_vk_pgo`, `test_walk_key`, `test_vk_occlusion_queries` — none touches this change (docs and website wiring only). **Not tested:** the website render of the new sidebar entry and page. **Must be tested:** - any desktop, docs preview: `install/steam-deck` renders in the Get started sidebar and the page's links to `common-issues` and `performance-report` resolve as site links (Test Farm: @Beanstalk docs, the site preview). - Steam Deck LCD, anyone's: follow the clock-line section as written, expecting `power_dpm_force_performance_level` to read `high` afterwards (by hand; we measured this exact line on our Deck). ## Risks **What could break:** only the site nav; a wrong slug would 404 the new page. **Turning it off:** revert the commit. **Compatibility:** Nothing changes for the game. ## Issues See #716 See #386 See #73 See #750 ## 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`. - [x] `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] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [x] Docs updated. WIP until the site preview passes; keeping it WIP is per the template's Needs line.
docs: play on the Steam Deck: what to expect, which switches help, and the clock setting (#716)
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 3s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
1e06d8c6c1
Assisted-by: GPT-6 Astra
Collaborator

Possibly related, for context:

  • issue #947 Game: Crashes every time when loading saves on Steam Deck LCD — Steam Deck LCD crash; relevant player context but not addressed by this docs change
Possibly related, for context: - issue #947 Game: Crashes every time when loading saves on Steam Deck LCD — Steam Deck LCD crash; relevant player context but not addressed by this docs change
docs(deck): keep the two rows the page quotes; the launch-state arms belong on #716
Some checks failed
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Failing after 3s
7f62f9d9af
Assisted-by: GPT-6 Astra
HumanBean changed title from WIP: docs: play on the Steam Deck: what to expect, which switches help, and the clock setting (#716) to docs: play on the Steam Deck: what to expect, which switches help, and the clock setting (#716) 2026-11-15 23:40:29 +00:00
HumanBean deleted branch docs/steam-deck-playbook 2026-11-15 23:40:37 +00:00
Some checks failed
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Failing after 3s
Some workflows are waiting to be reviewed.
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!968
No description provided.