feat(builder): prepare Steam Deck shaders on a Linux PC #2800

Open

github-sync wants to merge 7 commits from github/pr/2800 into main

github-sync commented

2026-11-12 14:41:11 +00:00

Owner

@polaco1782 opened this pull request on GitHub · 2026-11-12 13:55 UTC · original

Steam Deck shader preparation can take a long time, and caches compiled for a desktop GPU cannot be copied over as-is. This adds an option to prepare them on a Linux PC with the Deck's own driver, while bounding compiler memory use after an unbounded attempt exhausted the PC's RAM.

Changes

Add Prepare for Steam Deck on this PC and an SSH address to the Linux AppImage builder, plus nx2/make_game.py --steamdeck deck@steamdeck and a helper for existing game folders.
Read and verify the Deck's RADV driver and DRM shim over existing SSH key access. Check the offline GPU identity, driver and pipeline-cache UUID against the real Deck; keep the driver bundle in the builder cache.
Prepare in a disposable snapshot with four compiler workers, eight fresh process batches, a systemd memory limit of at most 8 GiB, and no worker swap. Release Vulkan objects after use; publish caches only after every batch succeeds and validates. Failed preparation preserves the installed caches.
Copy the private Mesa disk cache with the game. A matching prepared record makes the Deck load programs and pipelines when drawn, avoiding the memory cost of retaining the entire shader bank at startup. Explicit precompile choices remain available; stale records restore normal preparation.
Add game-free regression checks for argument validation, isolation, failure handling, batch coverage, object release, UTF-8 paths and startup readiness. Document usage and measured runs.

Validation

Hardware runs used 55b976c0 plus this feature, before rebasing onto 51da0464; the full game-free suite was rerun after the rebase.

Check	Observed result
PC preparation: Fedora 44, Ryzen 7 5700X, 32 GiB; exact LCD Deck Mesa 26.2.0-devel (`62436c0070`)	38,809 seed programs visited; 55,302 predicted pipelines (54,881 built, 421 duplicates), then 17,949 graphics and 9,691 compute pipelines. About 29 minutes; peak process RSS 7.37 GiB, no OOM kills or driver faults. Eight-batch cache reuse reproduced the counts without faults.
Native cache acceptance: LCD Deck, SteamOS 3.8.25, RADV VANGOGH	Full PC-generated cache accepted in 6.1 s, exit 0. Native preparation handled 17,949 graphics and 50 used compute pipelines in 991 ms.
Deck runtime memory regression	Resident precompile exceeded an 8 GiB test cgroup; a 10 GiB run hit the free-RAM guard during save load. With automatic loading when drawn, the same copied save rendered in Kakariko Village and exited normally after 55.55 s, without OOM or driver faults; minimum system RAM available was 1.37 GiB.
Rendered scene	Adult Kakariko potion shop, over 120 gameplay frames. Final five-second log window: 18.1 fps; earlier load-inclusive window: 9.4 fps. No FPS improvement claim. Original 14 save files and settings verified unchanged.

CCACHE_DIR=build-linux/ccache python -I -B tests/run_all.py --jobs 2: 466 passed, 0 failed, 33 skipped in 300 s on the rebased head. git diff --check passed.

Hardware results are recorded in docs/tested-configurations.md. Steam Gaming Mode window presentation, physical controls, audio, extended play, OLED Decks, Windows and other GPU vendors were not exercised by these runs. The rebased head has not been rerun in the game. This PR contains source, tests and documentation; game files, saves, driver libraries and generated caches stay local.

See #1000.

> [@polaco1782](https://github.com/polaco1782) opened this pull request on GitHub · 2026-11-12 13:55 UTC · [original](https://github.com/NotRexed/Hookshot/pull/2800) Steam Deck shader preparation can take a long time, and caches compiled for a desktop GPU cannot be copied over as-is. This adds an option to prepare them on a Linux PC with the Deck's own driver, while bounding compiler memory use after an unbounded attempt exhausted the PC's RAM. ## Changes - Add **Prepare for Steam Deck on this PC** and an SSH address to the Linux AppImage builder, plus `nx2/make_game.py --steamdeck deck@steamdeck` and a helper for existing game folders. - Read and verify the Deck's RADV driver and DRM shim over existing SSH key access. Check the offline GPU identity, driver and pipeline-cache UUID against the real Deck; keep the driver bundle in the builder cache. - Prepare in a disposable snapshot with four compiler workers, eight fresh process batches, a systemd memory limit of at most 8 GiB, and no worker swap. Release Vulkan objects after use; publish caches only after every batch succeeds and validates. Failed preparation preserves the installed caches. - Copy the private Mesa disk cache with the game. A matching prepared record makes the Deck load programs and pipelines when drawn, avoiding the memory cost of retaining the entire shader bank at startup. Explicit precompile choices remain available; stale records restore normal preparation. - Add game-free regression checks for argument validation, isolation, failure handling, batch coverage, object release, UTF-8 paths and startup readiness. Document usage and measured runs. ## Validation Hardware runs used `55b976c0` plus this feature, before rebasing onto `51da0464`; the full game-free suite was rerun after the rebase. | Check | Observed result | |---|---| | PC preparation: Fedora 44, Ryzen 7 5700X, 32 GiB; exact LCD Deck Mesa 26.2.0-devel (`62436c0070`) | 38,809 seed programs visited; 55,302 predicted pipelines (54,881 built, 421 duplicates), then 17,949 graphics and 9,691 compute pipelines. About 29 minutes; peak process RSS 7.37 GiB, no OOM kills or driver faults. Eight-batch cache reuse reproduced the counts without faults. | | Native cache acceptance: LCD Deck, SteamOS 3.8.25, RADV VANGOGH | Full PC-generated cache accepted in 6.1 s, exit 0. Native preparation handled 17,949 graphics and 50 used compute pipelines in 991 ms. | | Deck runtime memory regression | Resident precompile exceeded an 8 GiB test cgroup; a 10 GiB run hit the free-RAM guard during save load. With automatic loading when drawn, the same copied save rendered in Kakariko Village and exited normally after 55.55 s, without OOM or driver faults; minimum system RAM available was 1.37 GiB. | | Rendered scene | Adult Kakariko potion shop, over 120 gameplay frames. Final five-second log window: 18.1 fps; earlier load-inclusive window: 9.4 fps. No FPS improvement claim. Original 14 save files and settings verified unchanged. | `CCACHE_DIR=build-linux/ccache python -I -B tests/run_all.py --jobs 2`: **466 passed, 0 failed, 33 skipped** in 300 s on the rebased head. `git diff --check` passed. Hardware results are recorded in `docs/tested-configurations.md`. Steam Gaming Mode window presentation, physical controls, audio, extended play, OLED Decks, Windows and other GPU vendors were not exercised by these runs. The rebased head has not been rerun in the game. This PR contains source, tests and documentation; game files, saves, driver libraries and generated caches stay local. See #1000.

github-sync added 3 commits

2026-11-12 14:41:11 +00:00

feat(builder): prepare Steam Deck shaders on a Linux PC 42f6beab15

docs: omit screenshots from Steam Deck contribution 062a220672

test: resolve Steam Deck driver paths on Windows 7579f45ae5

Match the canonical bundle path produced by driver_environment when Windows temporary directories use 8.3 aliases. Cover normalized paths with parent segments, spaces, and UTF-8 without skipping Windows checks.

github-sync referenced this pull request

2026-11-12 14:42:20 +00:00

perf(vk): keep program stages' SPIR-V packed, make shader modules only per pipeline (~1.5 GB less RAM on NVIDIA) #2309

github-sync referenced this pull request

2026-11-12 15:49:07 +00:00

docs(steamdeck): record geometry and GPU clock measurements #2818

github-sync added 4 commits

2026-11-12 19:00:59 +00:00

Merge main into Steam Deck shader preparation 409273abc1

Preserve streamed offline preparation with load-at-create defaults and use current compute selection plan. Validate bounded preparation regression and retain both configuration report sets.

Merge main into Steam Deck shader preparation 6624b6fc7e

Merge current main cache fixes into Deck preparation ae78c24bbf

Merge main mesh launch switch and preserve Deck docs 5e55cda2f1

Commenting is not possible because the repository is archived.

No reviewers