docs(deck): rewrite the Steam Deck page as a Deck install manual #2062
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!2062
Loading…
Reference in a new issue
No description provided.
Delete branch "omgitsgela/Longshot:docs/steam-deck-playbook-rewrite"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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 thegame has done by itself since the clock hold shipped, and led with
longshot_env.txtswitches a Deck player neverneeds to set. And it implied the copied
cachefolder 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 ona 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:
~/.local/share/longshot(not in the copy) and that shader caches don't travel between GPUs, so the first Deckstart 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=nativeinnx2/build.py, with the CPU stamped into the object keys), so a game built on anewer 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-v3line (already documented innx2/build.py:1178-1189as the portable level), with the plain launcher build offered as the usually-fine optionrather than a guaranteed one. The Deck's own Zen 2 satisfies v3, which the builder's own comments state.
put
--play "<the game folder>"in its Launch options, return to Game Mode and start it from the library. The menuwording was read off a live Steam client on a Deck; the
--playwording follows the launcher's own code (namedfolder, else its default build; build folders rename with updates).
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% onthe outdoor saves, from
device_policy.h).sudosysfs recipe: the game holds thepeak state itself and, at start, leaves a power level the player chose to the player. The
sudo teecommands aregone: root-only, reset on reboot, and already superseded.
HOS_SHORT_SLEEP_TIMER=1is dropped from the page. On Linux, with the variable unset, the game already putsits own sub-millisecond sleeps on the timer and keeps the host's yielding (
host/hos_thread.c); the old line askedfor the stronger all-sleeps-on-the-timer mode, which no longer belongs in a beginner page. The switch itself stays
in the switch reference.
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).
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 ongpu/vk/gpu_clock.hand
gpu/vk/device_policy.h(the two Deck defaults and their measured ranges),gpu/vk/spirv_pack.handgpu/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=windowsis the opposite direction), the launcher'sApp/Program.csand
App/LauncherService.cs(--play, its default build), anddocs/user/requirements.md.Testing
Tested: Docs-only change, exercised the way it is used. Every claim re-checked against
mainatb62932a9andthe launcher's
mainate222060(the branch is rebased onto9dd41326since; nothing between those twomaincommits 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=nativedefault,nx2/build.py:1178-1189), and a wizard step whose button order didn't match the mergedlauncher (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.--play "<folder>"path confirmed from launcher source atmain(folder check, default build, andthe folder-rename caveat the page now warns about); the merged launcher has no automatic tile feature, and the page
claims none.
Mode icon, and that non-Steam applications show in the Game Mode library.
tests/test_doc_anchors.py(20 anchors, all resolve; no codeanchor pointed at any removed heading),
tests/test_auto_handheld.py(Deck: tier 1, Minimum, the game's ownupscaler),
scripts/check_guide_screenshots.py(passes; its UI-source-drift item reports itself NOT CHECKED).red on
maintoo, identically:mainat9dd41326fails that job with the same 8 issues, allsettings-graphics.pngwhose recorded UI-source hashes predategpu/vkchanges that landed onmain. Runningthe job's own command in a clean
9dd41326checkout reproduces the same 8 issues, so it is inherited and adocs-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 teerecipe 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
main; the title is a Conventional Commit.the Deck-side menu wording was read from a running Steam client on a Deck LCD.)
mise run testpasses (any failure that also fails onmainis named). (Ranpython3 -I -B tests/run_all.py --strict, whatmise run testruns, with the pinned test deps installed, on this rebased head and on currentmainat9dd41326: 712 passed, 185 failed, 17 skipped on both, failure name lists identical. Every failurereproduces on untouched
main: this VM'sg++chokes on_Static_assertinrender/rx_nvn.hfor the menu-layoutcompiles, and the shader/GLSL-family checks' pinned-tool probe set is incomplete here. The full comparison is the
first PR comment.)
main, or Measurements says why there is nothing to measure.third_party/untouched; nothing GPL-incompatible.When it applies
Assisted-by:/Co-Authored-By:trailers.Ready to merge
left: no code path, nothing to run on any hardware.)
page the game never reads; its Deck-side steps were read from live software on a Deck LCD.)
main, measured again or a comment says why the numbers still hold. (Everyjob on this head passes except Guide screenshots / local UI source review, which fails identically on untouched
mainat9dd41326with the same 8 inheritedsettings-graphics.pngreview-hash issues: that image's recordedhashes predate
gpu/vkmenu changes that landed onmain. 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 testbox uses.)Possibly related, for context:
Strict suite comparison, as promised.
python3 -I -B tests/run_all.py --strict(whatmise run testruns), with the pinned test deps installed(
mise run setup's test-deps step:spirv-headers,vulkan-headers,glslang,spirv-tools; glslang 16.6.0 onPATH), on the rebased head and on current
main:bcfa15ea): 712 passed, 185 failed, 17 skipped in 747 smainat9dd41326: 712 passed, 185 failed, 17 skipped in 745 sThe 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: themenu-layout compiles (
test_settings_table.pyand the other C++ layout checks) fail under this VM'sg++on_Static_assertinrender/rx_nvn.h, and the rest are the shader/GLSL-family checks whose pinned-tool probe set isincomplete 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 atthis head is
tests/test_fpxkeep.py, which came in with9dd41326and 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(theRX_MARCHlevel rules the copy-route recipe relieson), 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 testbox stands: the failures it names are exactly the ones that also fail onmain.WIP: docs(deck): rewrite the Steam Deck page as a Deck install manualto docs(deck): rewrite the Steam Deck page as a Deck install manualThanks 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
--playshortcut 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.Description updated after the review of the remaining checklist boxes:
mise run teststays ticked: 712/185/17 on this head and onmainat9dd41326, failure name lists identical.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.
UI source review, which fails identically on untouched
mainat9dd41326with the same 8settings-graphics.pngreview-hash issues (that image's recorded hashes predategpu/vkmenu changes landed onmain). This branch adds no images and touches no UI source, so it cannot move that job. Treated the same way asthe
mise run testbox: a failure that also fails onmainis 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.
@review
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.
@fixwill do (2)docs/user/steam-deck-playbook.md:71: There is no Controls > Keyboard setting with an Auto value in this version. (more on the line)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:
26ae6dfc61against9dd41326e7: 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:
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.
@ -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 controlsneeds one setting first: Steam's Desktop layout sends the Deck's stick and buttons to the game as key presses (the leftstick as the arrow keys, B as Escape), so walking also moves the camera and one button fires two things at once. Openthe game's own menu with <kbd>F1</kbd> and set **Controls > Keyboard** to **Auto**, which ignores the keyboard while aL1: 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.
@fix
26ae6dfc6114d491374dRecommendation: 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
@fixchangedI changed this pull request: the new head is
14d491374d. I rebased it ontomain(783235a599).Changed
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:
14d491374dagainst783235a599: 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:
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.