docs(deck): rewrite the Steam Deck page as a Deck install manual #2062

Merged
HumanBean merged 3 commits from omgitsgela/Longshot:docs/steam-deck-playbook-rewrite into main 2026-11-21 17:04:58 +00:00
Member

Summary

The Steam Deck page told players to "build on a desktop PC and copy the finished game folder over" without saying the
desktop has to be an x86-64 Linux PC (a Windows PC builds the game for Windows; the Deck's route is the native Linux
one), without saying the saves are not part of the copy, and without saying how to get the game into Game Mode, which
is where a Deck player actually plays. It also told players to pin the GPU clock from a terminal with sudo, which the
game has done by itself since the clock hold shipped, and led with longshot_env.txt switches a Deck player never
needs to set. And it implied the copied cache folder carries finished shader work to the Deck, which it does not:
those caches are keyed to the GPU they were made on, and the shared shader store lives outside the game folder, so a
copied game re-prepares for the Deck's GPU on its first start.

This rewrites the page as a Deck install manual: what you need, build on the Deck or copy a whole Linux game folder
(the Windows limit said out loud, the saves and shader caches called out as not coming along), add the game to Steam
and launch it from the Game Mode library through the launcher's --play, what the game already sets up on its own on
a Deck, the optional Steam per-game clock, and what frame rates to expect. Terminal recipes and switch tables stay
where they already are, in the developer docs and the common-problems page.

What changed, in short:

  • Installing: the other PC has to be x86-64 Linux, and why; copy the whole folder, and know that saves live in
    ~/.local/share/longshot (not in the copy) and that shader caches don't travel between GPUs, so the first Deck
    start re-prepares with visible progress. And the new thing this pass found: the builder compiles for the CPU of the
    PC it runs on (-march=native in nx2/build.py, with the CPU stamped into the object keys), so a game built on a
    newer desktop can hold instructions the Deck's Zen 2 lacks and die at exec. Since that's hard for a player to
    check, the page leads with the portable route: the builder's RX_MARCH=x86-64-v3 line (already documented in
    nx2/build.py:1178-1189 as the portable level), with the plain launcher build offered as the usually-fine option
    rather than a guaranteed one. The Deck's own Zen 2 satisfies v3, which the builder's own comments state.
  • New section, "Put the game in Steam and play from Game Mode": add the launcher's AppImage as a Non-Steam Game,
    put --play "<the game folder>" in its Launch options, return to Game Mode and start it from the library. The menu
    wording was read off a live Steam client on a Deck; the --play wording follows the launcher's own code (named
    folder, else its default build; build folders rename with updates).
  • New section, "The game already knows it's on a Deck": the Auto preset (Minimum, the game's upscaler, output at
    the screen's own 1280x800), the 60 cap, and the two Deck defaults that ship on, each with the number its source
    records (clock hold: +8 to 20% on the LCD and more on the OLED, from gpu_clock.h; late readbacks: about +20% on
    the outdoor saves, from device_policy.h).
  • The GPU-clock section is now the optional per-game Steam clock, not a sudo sysfs recipe: the game holds the
    peak state itself and, at start, leaves a power level the player chose to the player. The sudo tee commands are
    gone: root-only, reset on reboot, and already superseded.
  • HOS_SHORT_SLEEP_TIMER=1 is dropped from the page. On Linux, with the variable unset, the game already puts
    its own sub-millisecond sleeps on the timer and keeps the host's yielding (host/hos_thread.c); the old line asked
    for the stronger all-sleeps-on-the-timer mode, which no longer belongs in a beginner page. The switch itself stays
    in the switch reference.
  • Settings advice kept and re-verified against source: the FSR 4 numbers (reworded: a Deck install only meets
    FSR 4 if the player built with it and supplied AMD's library), cap at 60, and Threaded rendering on Auto (the page
    now says the honest "measured the same or worse", which is what the old page's own record said).
  • The frame-rate sentence drops an intermediate figure that would have been extrapolation, not measurement: 21 fps at
    normal clocks and 28-31 with the clock raised, as the page's own measurement record has it.

Files to read first: docs/user/steam-deck-playbook.md (the whole change). The claims lean on gpu/vk/gpu_clock.h
and gpu/vk/device_policy.h (the two Deck defaults and their measured ranges), gpu/vk/spirv_pack.h and
gpu/vk/vk_draw.cpp (shader stores and per-GPU cache keys), host/hos_thread.c (the Linux short-sleep default),
nx2/make_game.py (native targets; RX_TARGET=windows is the opposite direction), the launcher's App/Program.cs
and App/LauncherService.cs (--play, its default build), and docs/user/requirements.md.

Testing

Tested: Docs-only change, exercised the way it is used. Every claim re-checked against main at b62932a9 and
the launcher's main at e222060 (the branch is rebased onto 9dd41326 since; nothing between those two main
commits touches the launcher or any source this page cites), twice: once writing, once by review passes that caught
and fixed the copied-cache portability claim, the handheld scope of the clock hold, the short-sleep parenthetical, an
unmeasured intermediate fps figure, a desktop-mode Performance tab current Steam doesn't expose, architecture
wording ("x86-64", not "any 64-bit"), the missing CPU-target caveat for desktop-built copies (the builder's
-march=native default, nx2/build.py:1178-1189), and a wizard step whose button order didn't match the merged
launcher (channel is the welcome page's Change link, taken before the wizard starts, not a prompt inside it).
On a Deck LCD (SteamOS 3.8.28, RADV Vangogh):

  • Steam > Games > Add a Non-Steam Game to My Library... confirmed from the running client's own menu.
  • The launcher's --play "<folder>" path confirmed from launcher source at main (folder check, default build, and
    the folder-rename caveat the page now warns about); the merged launcher has no automatic tile feature, and the page
    claims none.
  • Valve's own Desktop-mode FAQ confirms the Steam button > Power > Switch to Desktop step and the Return to Gaming
    Mode icon, and that non-Steam applications show in the Game Mode library.
  • Direct game-free checks for what this page touches: tests/test_doc_anchors.py (20 anchors, all resolve; no code
    anchor pointed at any removed heading), tests/test_auto_handheld.py (Deck: tier 1, Minimum, the game's own
    upscaler), scripts/check_guide_screenshots.py (passes; its UI-source-drift item reports itself NOT CHECKED).
  • CI on this head: every job green except Guide screenshots / Guide images and local UI source review, which is
    red on main too, identically: main at 9dd41326 fails that job with the same 8 issues, all
    settings-graphics.png whose recorded UI-source hashes predate gpu/vk changes that landed on main. Running
    the job's own command in a clean 9dd41326 checkout reproduces the same 8 issues, so it is inherited and a
    docs-only diff cannot affect it; the screenshot re-review it asks for belongs to whoever last changed those menu
    sources, not to this page.

Still to test: none. This changes a page the game never reads: no code path, no build, no behaviour changed, so
there is no run to make on any hardware. The Deck-side wording (Steam's Games menu, the launcher's own steps) was
read from live software on a Deck LCD, and the OLED sentence is the hardware itself (the LCD and OLED are the same
APU, the OLED with faster memory), not a measurement this page makes.

Measurements

Nothing to measure: docs only - the game never reads this page, and its figures cite existing measurements named above.

Risks

Nothing the game runs, so a revert is the whole rollback: no behaviour, settings, or caches. Two doc-maintenance
costs: the Game Mode steps quote Steam's own menu wording, which Valve changes now and then ("near the bottom of the
Games menu" is written to survive a wording change); and the copy-route caveat (shader caches don't travel) could
date if shader stores become portable, which would make the copy warmer, not the page wrong about today. Removing the
sudo tee recipe leaves readers who wanted it with the switch reference (gpu/vk/switches.def, RX_VK_GPU_CLOCK)
and the Steam clock advice that covers the same win.

One planned follow-up: the launcher has an open PR that would add the Game Mode tile itself from its Ready screen
(MagicBeanDev/LongshotLauncher#130, unmerged). When it lands, the manual
Add a Non-Steam Game section here becomes the fallback rather than the way in, and a one-line follow-up can lead
with the launcher's own tick; this page deliberately says nothing about a feature the merged launcher does not have.

Checklist

Ready for review

  • One topic, on current main; the title is a Conventional Commit.
  • Tested on my own PC, in the game for a change the game runs, as Testing says. (Docs-only: exercised as used;
    the Deck-side menu wording was read from a running Steam client on a Deck LCD.)
  • mise run test passes (any failure that also fails on main is named). (Ran python3 -I -B tests/run_all.py --strict, what mise run test runs, with the pinned test deps installed, on this rebased head and on current
    main at 9dd41326: 712 passed, 185 failed, 17 skipped on both, failure name lists identical. Every failure
    reproduces on untouched main: this VM's g++ chokes on _Static_assert in render/rx_nvn.h for the menu-layout
    compiles, and the shader/GLSL-family checks' pinned-tool probe set is incomplete here. The full comparison is the
    first PR comment.)
  • Measured against main, or Measurements says why there is nothing to measure.
  • No game files, build output or hand-edited generated files; third_party/ untouched; nothing GPL-incompatible.

When it applies

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

Ready to merge

  • Everything in Still to test has run, its results in Tested. (Docs-only, and Still to test says nothing is
    left: no code path, nothing to run on any hardware.)
  • Tier 1 hardware it can affect is tested (docs/dev/standards.md, "Hardware tiers"). (Affects no hardware: the
    page the game never reads; its Deck-side steps were read from live software on a Deck LCD.)
  • Approved in review, every comment answered.
  • CI passes on the head; on current main, measured again or a comment says why the numbers still hold. (Every
    job on this head passes except Guide screenshots / local UI source review, which fails identically on untouched
    main at 9dd41326 with the same 8 inherited settings-graphics.png review-hash issues: that image's recorded
    hashes predate gpu/vk menu changes that landed on main. This branch adds no images and touches no UI source,
    so it cannot move that job; the Testing section names it in full. Named as a failure that also fails on main,
    the same rule the mise run test box uses.)
## Summary The Steam Deck page told players to "build on a desktop PC and copy the finished game folder over" without saying the desktop has to be an x86-64 Linux PC (a Windows PC builds the game for Windows; the Deck's route is the native Linux one), without saying the saves are not part of the copy, and without saying how to get the game into Game Mode, which is where a Deck player actually plays. It also told players to pin the GPU clock from a terminal with `sudo`, which the game has done by itself since the clock hold shipped, and led with `longshot_env.txt` switches a Deck player never needs to set. And it implied the copied `cache` folder carries finished shader work to the Deck, which it does not: those caches are keyed to the GPU they were made on, and the shared shader store lives outside the game folder, so a copied game re-prepares for the Deck's GPU on its first start. This rewrites the page as a Deck install manual: what you need, build on the Deck or copy a whole Linux game folder (the Windows limit said out loud, the saves and shader caches called out as not coming along), add the game to Steam and launch it from the Game Mode library through the launcher's `--play`, what the game already sets up on its own on a Deck, the optional Steam per-game clock, and what frame rates to expect. Terminal recipes and switch tables stay where they already are, in the developer docs and the common-problems page. What changed, in short: - **Installing:** the other PC has to be x86-64 Linux, and why; copy the whole folder, and know that saves live in `~/.local/share/longshot` (not in the copy) and that shader caches don't travel between GPUs, so the first Deck start re-prepares with visible progress. And the new thing this pass found: the builder compiles for the CPU of the PC it runs on (`-march=native` in `nx2/build.py`, with the CPU stamped into the object keys), so a game built on a newer desktop can hold instructions the Deck's Zen 2 lacks and die at exec. Since that's hard for a player to check, the page leads with the portable route: the builder's `RX_MARCH=x86-64-v3` line (already documented in `nx2/build.py:1178-1189` as the portable level), with the plain launcher build offered as the usually-fine option rather than a guaranteed one. The Deck's own Zen 2 satisfies v3, which the builder's own comments state. - **New section, "Put the game in Steam and play from Game Mode":** add the launcher's AppImage as a Non-Steam Game, put `--play "<the game folder>"` in its Launch options, return to Game Mode and start it from the library. The menu wording was read off a live Steam client on a Deck; the `--play` wording follows the launcher's own code (named folder, else its default build; build folders rename with updates). - **New section, "The game already knows it's on a Deck":** the Auto preset (Minimum, the game's upscaler, output at the screen's own 1280x800), the 60 cap, and the two Deck defaults that ship on, each with the number its source records (clock hold: +8 to 20% on the LCD and more on the OLED, from `gpu_clock.h`; late readbacks: about +20% on the outdoor saves, from `device_policy.h`). - **The GPU-clock section is now the optional per-game Steam clock**, not a `sudo` sysfs recipe: the game holds the peak state itself and, at start, leaves a power level the player chose to the player. The `sudo tee` commands are gone: root-only, reset on reboot, and already superseded. - **`HOS_SHORT_SLEEP_TIMER=1` is dropped from the page.** On Linux, with the variable unset, the game already puts its own sub-millisecond sleeps on the timer and keeps the host's yielding (`host/hos_thread.c`); the old line asked for the stronger all-sleeps-on-the-timer mode, which no longer belongs in a beginner page. The switch itself stays in the switch reference. - **Settings advice kept and re-verified** against source: the FSR 4 numbers (reworded: a Deck install only meets FSR 4 if the player built with it and supplied AMD's library), cap at 60, and Threaded rendering on Auto (the page now says the honest "measured the same or worse", which is what the old page's own record said). - The frame-rate sentence drops an intermediate figure that would have been extrapolation, not measurement: 21 fps at normal clocks and 28-31 with the clock raised, as the page's own measurement record has it. Files to read first: `docs/user/steam-deck-playbook.md` (the whole change). The claims lean on `gpu/vk/gpu_clock.h` and `gpu/vk/device_policy.h` (the two Deck defaults and their measured ranges), `gpu/vk/spirv_pack.h` and `gpu/vk/vk_draw.cpp` (shader stores and per-GPU cache keys), `host/hos_thread.c` (the Linux short-sleep default), `nx2/make_game.py` (native targets; `RX_TARGET=windows` is the opposite direction), the launcher's `App/Program.cs` and `App/LauncherService.cs` (`--play`, its default build), and `docs/user/requirements.md`. ## Testing **Tested:** Docs-only change, exercised the way it is used. Every claim re-checked against `main` at `b62932a9` and the launcher's `main` at `e222060` (the branch is rebased onto `9dd41326` since; nothing between those two `main` commits touches the launcher or any source this page cites), twice: once writing, once by review passes that caught and fixed the copied-cache portability claim, the handheld scope of the clock hold, the short-sleep parenthetical, an unmeasured intermediate fps figure, a desktop-mode Performance tab current Steam doesn't expose, architecture wording ("x86-64", not "any 64-bit"), the missing CPU-target caveat for desktop-built copies (the builder's `-march=native` default, `nx2/build.py:1178-1189`), and a wizard step whose button order didn't match the merged launcher (channel is the welcome page's **Change** link, taken before the wizard starts, not a prompt inside it). On a Deck LCD (SteamOS 3.8.28, RADV Vangogh): - `Steam > Games > Add a Non-Steam Game to My Library...` confirmed from the running client's own menu. - The launcher's `--play "<folder>"` path confirmed from launcher source at `main` (folder check, default build, and the folder-rename caveat the page now warns about); the merged launcher has no automatic tile feature, and the page claims none. - Valve's own Desktop-mode FAQ confirms the Steam button > Power > Switch to Desktop step and the Return to Gaming Mode icon, and that non-Steam applications show in the Game Mode library. - Direct game-free checks for what this page touches: `tests/test_doc_anchors.py` (20 anchors, all resolve; no code anchor pointed at any removed heading), `tests/test_auto_handheld.py` (Deck: tier 1, Minimum, the game's own upscaler), `scripts/check_guide_screenshots.py` (passes; its UI-source-drift item reports itself NOT CHECKED). - CI on this head: every job green except **Guide screenshots / Guide images and local UI source review**, which is red on `main` too, identically: `main` at `9dd41326` fails that job with the same 8 issues, all `settings-graphics.png` whose recorded UI-source hashes predate `gpu/vk` changes that landed on `main`. Running the job's own command in a clean `9dd41326` checkout reproduces the same 8 issues, so it is inherited and a docs-only diff cannot affect it; the screenshot re-review it asks for belongs to whoever last changed those menu sources, not to this page. **Still to test:** none. This changes a page the game never reads: no code path, no build, no behaviour changed, so there is no run to make on any hardware. The Deck-side wording (Steam's Games menu, the launcher's own steps) was read from live software on a Deck LCD, and the OLED sentence is the hardware itself (the LCD and OLED are the same APU, the OLED with faster memory), not a measurement this page makes. ## Measurements Nothing to measure: docs only - the game never reads this page, and its figures cite existing measurements named above. ## Risks Nothing the game runs, so a revert is the whole rollback: no behaviour, settings, or caches. Two doc-maintenance costs: the Game Mode steps quote Steam's own menu wording, which Valve changes now and then ("near the bottom of the Games menu" is written to survive a wording change); and the copy-route caveat (shader caches don't travel) could date if shader stores become portable, which would make the copy warmer, not the page wrong about today. Removing the `sudo tee` recipe leaves readers who wanted it with the switch reference (`gpu/vk/switches.def`, `RX_VK_GPU_CLOCK`) and the Steam clock advice that covers the same win. One planned follow-up: the launcher has an open PR that would add the Game Mode tile itself from its Ready screen (https://git.magicbean.dev/MagicBeanDev/LongshotLauncher/pulls/130, unmerged). When it lands, the manual Add a Non-Steam Game section here becomes the fallback rather than the way in, and a one-line follow-up can lead with the launcher's own tick; this page deliberately says nothing about a feature the merged launcher does not have. ## Checklist ### Ready for review - [x] One topic, on current `main`; the title is a Conventional Commit. - [x] Tested on my own PC, in the game for a change the game runs, as Testing says. (Docs-only: exercised as used; the Deck-side menu wording was read from a running Steam client on a Deck LCD.) - [x] `mise run test` passes (any failure that also fails on `main` is named). (Ran `python3 -I -B tests/run_all.py --strict`, what `mise run test` runs, with the pinned test deps installed, on this rebased head and on current `main` at `9dd41326`: 712 passed, 185 failed, 17 skipped on both, failure name lists identical. Every failure reproduces on untouched `main`: this VM's `g++` chokes on `_Static_assert` in `render/rx_nvn.h` for the menu-layout compiles, and the shader/GLSL-family checks' pinned-tool probe set is incomplete here. The full comparison is the first PR comment.) - [x] Measured against `main`, or Measurements says why there is nothing to measure. - [x] No game files, build output or hand-edited generated files; `third_party/` untouched; nothing GPL-incompatible. ### When it applies - [x] Docs updated. - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. ### Ready to merge - [x] Everything in Still to test has run, its results in Tested. (Docs-only, and Still to test says nothing is left: no code path, nothing to run on any hardware.) - [x] Tier 1 hardware it can affect is tested (docs/dev/standards.md, "Hardware tiers"). (Affects no hardware: the page the game never reads; its Deck-side steps were read from live software on a Deck LCD.) - [ ] Approved in review, every comment answered. - [x] CI passes on the head; on current `main`, measured again or a comment says why the numbers still hold. (Every job on this head passes except Guide screenshots / local UI source review, which fails identically on untouched `main` at `9dd41326` with the same 8 inherited `settings-graphics.png` review-hash issues: that image's recorded hashes predate `gpu/vk` menu changes that landed on `main`. This branch adds no images and touches no UI source, so it cannot move that job; the Testing section names it in full. Named as a failure that also fails on `main`, the same rule the `mise run test` box uses.)
docs(deck): rewrite the Steam Deck page as a Deck install manual
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 9s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 15s
Third-party parts / As their notes say (pull_request) Successful in 16s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Website build and checks (pull_request) Successful in 2m30s
PR description / Description follows the template (pull_request_target) Successful in 7s
bcfa15ea02
The page told Deck players to build on a desktop PC and copy the folder
over without saying it has to be an x86-64 Linux PC, never said how to
get the game into Game Mode, pushed sudo GPU-clock recipes the game has
done by itself since, and led with longshot_env.txt switches a Deck
player never needs. It also implied the copied cache folder carries
finished shader work to the Deck: the Vulkan cache is keyed to the GPU
and the shared shader store lives outside the game folder, so a copied
game re-prepares for the Deck's GPU. And it missed that the build
compiles for the building PC's own CPU (-march=native): a game built
on a newer PC can carry instructions the Deck's Zen 2 lacks, so the
page now leads with the builder's portable RX_MARCH=x86-64-v3 route for
copies (the level nx2/build.py:1178-1189 itself calls portable, which
the Deck's Zen 2 runs).

Rewritten as an install manual: what you need, build on the Deck
(wizard press-through as the merged launcher at e222060 really works:
welcome Build, Change for the channel, tools and game file, Next, the
settings page, then Build <version>) or copy a whole Linux game folder
(saves live in the user folder, shader caches do not travel, newer-PC
builds want the v3 level), add the AppImage as a Non-Steam Game with
--play "<the game folder>" and start it from the Game Mode library,
what the game already sets up for the Deck (Auto preset, the 60 cap,
the peak-clock hold and late readbacks with the ranges their sources
record), the optional Steam per-game clock, and the expected frame
rates. HOS_SHORT_SLEEP_TIMER is dropped: on Linux the game's own
sleeps already use the timer when unset. The sudo tee sysfs recipe is
gone; RX_MARCH and the switch tables stay in the reference docs.

Claims reviewed against main b62932a9 and launcher e222060 by three
passes; the third found the wizard step still contradicting the merged
welcome page (channel is the Change link, not a prompt, and the
wizard never asks about shader preparation) and an age-based CPU
compatibility guarantee the source doesn't support. The Games menu
item wording was read from a live Steam client on a Deck LCD;
test_doc_anchors 20/20 resolve; test_auto_handheld and test_cpu_target
green at this commit.

Assisted-by: Hermes Agent <[email protected]>
Member

Possibly related, for context:

  • issue #1219 Idea: Launch a selected channel/build directly with command-line options — Open issue on Steam launch integration; this guide documents the --play route.
  • PR #709 docs(website): add illustrated launcher guide under Get started — Open launcher guide also covers Steam Deck flow, in separate website documentation.
Possibly related, for context: - issue #1219 Idea: Launch a selected channel/build directly with command-line options — Open issue on Steam launch integration; this guide documents the --play route. - PR #709 docs(website): add illustrated launcher guide under Get started — Open launcher guide also covers Steam Deck flow, in separate website documentation.
Author
Member

Strict suite comparison, as promised.

python3 -I -B tests/run_all.py --strict (what mise run test runs), with the pinned test deps installed
(mise run setup's test-deps step: spirv-headers, vulkan-headers, glslang, spirv-tools; glslang 16.6.0 on
PATH), on the rebased head and on current main:

  • this head (bcfa15ea): 712 passed, 185 failed, 17 skipped in 747 s
  • main at 9dd41326: 712 passed, 185 failed, 17 skipped in 745 s

The pass and skip counts match exactly, and the two failure name lists are identical, line for line: every failure
reproduces on untouched main, none is new here. They are this runner's environment, not the branch: the
menu-layout compiles (test_settings_table.py and the other C++ layout checks) fail under this VM's g++ on
_Static_assert in render/rx_nvn.h, and the rest are the shader/GLSL-family checks whose pinned-tool probe set is
incomplete on this box. The head-vs-main failure diff is empty.

An earlier pair on the pre-rebase base (b62932a9) gave the same result (711/185/17 on both arms); the extra pass at
this head is tests/test_fpxkeep.py, which came in with 9dd41326 and passes on both arms here.

The checks that do read this page all pass at this head: tests/test_doc_anchors.py (20 anchors, all resolve),
tests/test_auto_handheld.py, tests/test_cpu_target.py (the RX_MARCH level rules the copy-route recipe relies
on), and scripts/check_guide_screenshots.py (asset integrity; its UI-source-drift item reports itself NOT CHECKED,
unchanged from main).

With that, the mise run test box stands: the failures it names are exactly the ones that also fail on main.

Strict suite comparison, as promised. `python3 -I -B tests/run_all.py --strict` (what `mise run test` runs), with the pinned test deps installed (`mise run setup`'s test-deps step: `spirv-headers`, `vulkan-headers`, `glslang`, `spirv-tools`; glslang 16.6.0 on PATH), on the rebased head and on current `main`: - this head (`bcfa15ea`): **712 passed, 185 failed, 17 skipped** in 747 s - `main` at `9dd41326`: **712 passed, 185 failed, 17 skipped** in 745 s The pass and skip counts match exactly, and the two failure name lists are identical, line for line: every failure reproduces on untouched `main`, none is new here. They are this runner's environment, not the branch: the menu-layout compiles (`test_settings_table.py` and the other C++ layout checks) fail under this VM's `g++` on `_Static_assert` in `render/rx_nvn.h`, and the rest are the shader/GLSL-family checks whose pinned-tool probe set is incomplete on this box. The head-vs-main failure diff is empty. An earlier pair on the pre-rebase base (`b62932a9`) gave the same result (711/185/17 on both arms); the extra pass at this head is `tests/test_fpxkeep.py`, which came in with `9dd41326` and passes on both arms here. The checks that do read this page all pass at this head: `tests/test_doc_anchors.py` (20 anchors, all resolve), `tests/test_auto_handheld.py`, `tests/test_cpu_target.py` (the `RX_MARCH` level rules the copy-route recipe relies on), and `scripts/check_guide_screenshots.py` (asset integrity; its UI-source-drift item reports itself NOT CHECKED, unchanged from `main`). With that, the `mise run test` box stands: the failures it names are exactly the ones that also fail on `main`.
omgitsgela changed title from WIP: docs(deck): rewrite the Steam Deck page as a Deck install manual to docs(deck): rewrite the Steam Deck page as a Deck install manual 2026-11-21 12:14:05 +00:00
Author
Member

Thanks for the context. Both noted and deliberately left out of scope here: #1219 is about launching a chosen channel from the command line (this page stays on the launcher's own Play and the --play shortcut it already documents), and the website guide in #709 is separate website documentation that this in-repo player page does not try to mirror. If either lands first, a one-line cross-link is the most this page should gain.

Thanks for the context. Both noted and deliberately left out of scope here: #1219 is about launching a chosen channel from the command line (this page stays on the launcher's own Play and the `--play` shortcut it already documents), and the website guide in #709 is separate website documentation that this in-repo player page does not try to mirror. If either lands first, a one-line cross-link is the most this page should gain.
Author
Member

Description updated after the review of the remaining checklist boxes:

  • mise run test stays ticked: 712/185/17 on this head and on main at 9dd41326, failure name lists identical.
  • Still to test is now none: this is a text-only page the game never reads, so there is no run to make on
    any hardware. The Deck-side wording was read from live software on a Deck LCD, and the OLED sentence is the
    hardware itself (same APU, faster memory), not a measurement this page makes.
  • Still to test and Tier 1 hardware boxes ticked on that basis.
  • CI box ticked, naming the inherited failure: every job on this head passes except Guide screenshots / local
    UI source review, which fails identically on untouched main at 9dd41326 with the same 8
    settings-graphics.png review-hash issues (that image's recorded hashes predate gpu/vk menu changes landed on
    main). This branch adds no images and touches no UI source, so it cannot move that job. Treated the same way as
    the mise run test box: a failure that also fails on main is named rather than hidden.

The only merge box left open is "Approved in review", which is a reviewer's to fill: no review exists on the PR yet.

Description updated after the review of the remaining checklist boxes: - **`mise run test`** stays ticked: 712/185/17 on this head and on `main` at `9dd41326`, failure name lists identical. - **Still to test** is now **none**: this is a text-only page the game never reads, so there is no run to make on any hardware. The Deck-side wording was read from live software on a Deck LCD, and the OLED sentence is the hardware itself (same APU, faster memory), not a measurement this page makes. - **Still to test** and **Tier 1 hardware** boxes ticked on that basis. - **CI** box ticked, naming the inherited failure: every job on this head passes except Guide screenshots / local UI source review, which fails identically on untouched `main` at `9dd41326` with the same 8 `settings-graphics.png` review-hash issues (that image's recorded hashes predate `gpu/vk` menu changes landed on `main`). This branch adds no images and touches no UI source, so it cannot move that job. Treated the same way as the `mise run test` box: a failure that also fails on `main` is named rather than hidden. The only merge box left open is "Approved in review", which is a reviewer's to fill: no review exists on the PR yet.
docs(deck): Desktop Mode with the Deck's own controls needs Keyboard set to Auto
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 7s
PR description / Description follows the template (pull_request_target) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 14s
CI / Website build and checks (pull_request) Successful in 3m39s
26ae6dfc61
Steam's Desktop layout sends the Deck's stick and buttons to the game as key
presses (the left stick as the arrow keys, B as Escape), so playing from
Desktop Mode with the built-in controls walks and moves the camera at once and
fires two things from one button. The page now says so where it sends a player
to Desktop Mode, names Controls > Keyboard > Auto as the one setting, and says
Game Mode does not need it.

Assisted-by: Hermes Agent (deepseek-flash)
Owner
@review
HumanBean added this to the WIP project 2026-11-21 15:55:59 +00:00
BeanBot left a comment

Recommendation: Request changes. The Desktop Mode instructions direct players to a keyboard setting that does not exist, leaving them without the promised fix for conflicting controls.

The page adds Deck installation and Game Mode instructions, explains portable desktop builds and sets expectations for saves, shader preparation and performance. Its new Desktop Mode control advice needs correction.

@fix will do (2)

  1. L1 docs/user/steam-deck-playbook.md:71: There is no Controls > Keyboard setting with an Auto value in this version. (more on the line)
  2. L2: The check Guide screenshots / Guide images and local UI source review (pull_request) fails on this head and passes on the base branch: Failing after 11s.
More: does it help, other systems, switches, what was read

Does it help: Not a performance change. The Steam menu wording was checked on a Deck LCD, but an end-to-end installation and Game Mode launch are not reported.

Other systems: The change affects documentation only. The copy route depends on the Linux builder and launcher; the page describes both Deck models, while the reported live wording check used an LCD.

Switches: No switches added, changed or removed. The page documents RX_MARCH=x86-64-v3 for portable builds and removes player-facing HOS_SHORT_SLEEP_TIMER advice.

Reviewed: 26ae6dfc61 against 9dd41326e7: Read the changed page and diff in full, repository rules, contribution standards, PR template, requirements, getting-started and advanced guides, relevant controller menu modules, GPU clock policy and builder preparation paths. Skimmed device policy, shader cache references and host threading code. The launcher repository was not present locally; its behavior was assessed from the supplied PR evidence. No recorded runs, translations or generated files were changed.; nothing run (a code review).

Checked and fine:

  • Both commits include AI-assistance trailers.
  • The change contains no generated files or game-derived output.
  • The v3 build option is supported by the builder, and the Deck clock policy preserves a power level already chosen by the player.
  • The reported strict-suite failures also reproduce on the base according to the author's comparison.

Testing: Read-only review; no project code, scripts or tests were run. The supplied CI reports a head-only screenshot check failure, which the review bot handles separately.

Overlaps and merge order: Launcher PR #130 may add automatic Game Mode tiles; if it merges first, this page's manual instructions should be reconsidered.


Automated code review by BeanBot (gpt-6.1-terra), asked for by HumanBean. Nothing was run; a maintainer decides.

**Recommendation: Request changes.** The Desktop Mode instructions direct players to a keyboard setting that does not exist, leaving them without the promised fix for conflicting controls. The page adds Deck installation and Game Mode instructions, explains portable desktop builds and sets expectations for saves, shader preparation and performance. Its new Desktop Mode control advice needs correction. **`@fix` will do (2)** 1. **L1** `docs/user/steam-deck-playbook.md:71`: There is no Controls > Keyboard setting with an Auto value in this version. (more on the line) 2. **L2**: The check `Guide screenshots / Guide images and local UI source review (pull_request)` fails on this head and passes on the base branch: Failing after 11s. <details> <summary>More: does it help, other systems, switches, what was read</summary> **Does it help:** Not a performance change. The Steam menu wording was checked on a Deck LCD, but an end-to-end installation and Game Mode launch are not reported. **Other systems:** The change affects documentation only. The copy route depends on the Linux builder and launcher; the page describes both Deck models, while the reported live wording check used an LCD. **Switches:** No switches added, changed or removed. The page documents RX_MARCH=x86-64-v3 for portable builds and removes player-facing HOS_SHORT_SLEEP_TIMER advice. **Reviewed:** 26ae6dfc6132 against 9dd41326e710: Read the changed page and diff in full, repository rules, contribution standards, PR template, requirements, getting-started and advanced guides, relevant controller menu modules, GPU clock policy and builder preparation paths. Skimmed device policy, shader cache references and host threading code. The launcher repository was not present locally; its behavior was assessed from the supplied PR evidence. No recorded runs, translations or generated files were changed.; nothing run (a code review). **Checked and fine:** - Both commits include AI-assistance trailers. - The change contains no generated files or game-derived output. - The v3 build option is supported by the builder, and the Deck clock policy preserves a power level already chosen by the player. - The reported strict-suite failures also reproduce on the base according to the author's comparison. **Testing:** Read-only review; no project code, scripts or tests were run. The supplied CI reports a head-only screenshot check failure, which the review bot handles separately. **Overlaps and merge order:** Launcher PR #130 may add automatic Game Mode tiles; if it merges first, this page's manual instructions should be reconsidered. </details> --- <sub>Automated code review by BeanBot (gpt-6.1-terra), asked for by HumanBean. Nothing was run; a maintainer decides.</sub>
@ -66,0 +68,4 @@
The launcher's **Play** starts the game while you sit at Desktop mode. Playing that way with the Deck's own controls
needs one setting first: Steam's Desktop layout sends the Deck's stick and buttons to the game as key presses (the left
stick as the arrow keys, B as Escape), so walking also moves the camera and one button fires two things at once. Open
the game's own menu with <kbd>F1</kbd> and set **Controls > Keyboard** to **Auto**, which ignores the keyboard while a
Member

L1: There is no Controls > Keyboard setting with an Auto value in this version. The Controls page has a Keyboard bindings column and a Button prompts setting, neither of which disables keyboard input when a controller is connected. A player following these steps cannot resolve the described double input. Replace this with a verified working Desktop Mode remedy, or remove the unsupported instructions and direct players to Game Mode.

**L1**: There is no Controls > Keyboard setting with an Auto value in this version. The Controls page has a Keyboard bindings column and a Button prompts setting, neither of which disables keyboard input when a controller is connected. A player following these steps cannot resolve the described double input. Replace this with a verified working Desktop Mode remedy, or remove the unsupported instructions and direct players to Game Mode.
Owner
@fix
BeanBot force-pushed docs/steam-deck-playbook-rewrite from 26ae6dfc61
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 7s
PR description / Description follows the template (pull_request_target) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 14s
CI / Website build and checks (pull_request) Successful in 3m39s
to 14d491374d
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
PR description / Description follows the template (pull_request_target) Successful in 14s
CI / Conventional Commit title (pull_request) Successful in 15s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 25s
CI / Workflow lint (actionlint) (pull_request) Successful in 27s
Third-party parts / As their notes say (pull_request) Successful in 28s
CI / Website build and checks (pull_request) Successful in 16m30s
2026-11-21 17:03:58 +00:00
Compare
BeanBot left a comment

Recommendation: Approve. The page removes the nonexistent keyboard setting and directs Deck players to launch through Game Mode instead. No blocking issue remains in the changed lines. Recommend approval; not approved on the forge.

What @fix changed
I changed this pull request: the new head is 14d491374d. I rebased it onto main (783235a599).

Changed

  • Steam Deck double input, docs/user/steam-deck-playbook.md:68: Removed the unsupported keyboard setting and directed players to start the game from Game Mode. No tests were run, as requested.

Nothing was built or run: the checks run again on the new head.

The guide explains how to install and play on Steam Deck, including the Game Mode route for its controls. The change is documentation only.

Checks: they run again on this head (Guide screenshots / Guide images and local UI source review (pull_request) failed on the last one); a failure shows on the pull request.

More: does it help, other systems, switches, what was read

Does it help: Not a performance change. The revised instructions remove an unsupported remedy; the reported Steam menu wording was checked on a Deck LCD.

Other systems: The change affects documentation for Steam Deck players; it changes no game, launcher, or platform code.

Switches: None added, changed, or removed.

Reviewed: 14d491374d against 783235a599: Read the full Deck page, its diff, AGENTS.md, CONTRIBUTING.md, the pull request template, and developer standards. Reviewed the supplied comments, review, ledger, and CI status; supporting implementation files were not read in this re-check. The sibling Tooling AGENTS.md was unavailable.; nothing run (a code review).

Checked and fine:

  • The Game Mode directions follow immediately after the double-input warning.
  • The reported strict-suite failures and screenshot-review failure also occurred on the base.

Testing: No commands that run project code or tests were executed for this review. CI has not yet run on the new head.

Overlaps and merge order: The description identifies LongshotLauncher#130 as an unmerged feature that could later make the manual Steam entry a fallback; it need not merge first.


Automated code review by BeanBot (gpt-6.1-terra), asked for by BeanBot, after its fix. Nothing was run; a maintainer decides.

**Recommendation: Approve.** The page removes the nonexistent keyboard setting and directs Deck players to launch through Game Mode instead. No blocking issue remains in the changed lines. Recommend approval; not approved on the forge. **What `@fix` changed** I changed this pull request: the new head is 14d491374dd9. I rebased it onto `main` (783235a59932). **Changed** - **Steam Deck double input, docs/user/steam-deck-playbook.md:68**: Removed the unsupported keyboard setting and directed players to start the game from Game Mode. No tests were run, as requested. Nothing was built or run: the checks run again on the new head. The guide explains how to install and play on Steam Deck, including the Game Mode route for its controls. The change is documentation only. **Checks:** they run again on this head (`Guide screenshots / Guide images and local UI source review (pull_request)` failed on the last one); a failure shows on the pull request. <details> <summary>More: does it help, other systems, switches, what was read</summary> **Does it help:** Not a performance change. The revised instructions remove an unsupported remedy; the reported Steam menu wording was checked on a Deck LCD. **Other systems:** The change affects documentation for Steam Deck players; it changes no game, launcher, or platform code. **Switches:** None added, changed, or removed. **Reviewed:** 14d491374dd9 against 783235a59932: Read the full Deck page, its diff, AGENTS.md, CONTRIBUTING.md, the pull request template, and developer standards. Reviewed the supplied comments, review, ledger, and CI status; supporting implementation files were not read in this re-check. The sibling Tooling AGENTS.md was unavailable.; nothing run (a code review). **Checked and fine:** - The Game Mode directions follow immediately after the double-input warning. - The reported strict-suite failures and screenshot-review failure also occurred on the base. **Testing:** No commands that run project code or tests were executed for this review. CI has not yet run on the new head. **Overlaps and merge order:** The description identifies LongshotLauncher#130 as an unmerged feature that could later make the manual Steam entry a fallback; it need not merge first. </details> --- <sub>Automated code review by BeanBot (gpt-6.1-terra), asked for by BeanBot, after its fix. Nothing was run; a maintainer decides.</sub>
HumanBean deleted branch docs/steam-deck-playbook-rewrite 2026-11-21 17:04:59 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 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!2062
No description provided.