Merge org main 5aa245cf into the non-Adreno test branch

Conflicts resolved keeping both sides: main's comment cleanup (#764) taken
where only comments differed; the test branch's code kept everywhere else.
ensureAuto runs main's Quest auto drivers before the Mali paths;
vkp_update_map keeps the Quest layer path and the completion-unknown check
(pass_begin goes through it); gamescope backend selection plus main's
steam-mode cursor composite; droiddeck-session's watcher is main's shared
loop with the Venus GL probe after it; SessionFiles/runtime_inputs/build.yml
carry both the Xclipse layer and main's VR assets. Main's GPU detection
test follows the non-Adreno support text; the Steam presentation test
finds its block by code, not by a removed comment.
This commit is contained in:
The412Banner committed 2026-10-15 18:40:47 -04:00
commit 75612da44b
1016 files changed
+95104 -48259

No files matched your search

+35 -26
View File
@@ -12,6 +12,8 @@ and reports every run.
answers each command with JSON. It and the session-start Activity (`AgentStartActivity`) are in
every build and require `android.permission.DUMP`, held by the ADB shell and privileged or
explicitly granted callers. The provider checks the calling permission before decoding requests.
A build shipped under another package (`tools/release/variants.txt`) answers at
`content://<package>.agent`: set `DROIDDECK_PACKAGE` to that package for `droiddeckctl`.
- **The guest agent** `droiddeck-agent` runs inside every session (started by
`droiddeck-session`). It runs commands with the session's own environment, publishes gamescope's
focus, and talks to the Steam client's DevTools, which only accepts guest processes. The app and
@@ -23,10 +25,10 @@ and reports every run.
## Access
Player controls and observations work over authorized ADB on any build: `state`, `start`, `stop`,
`resume`, `wait`, `launch`, `quit`, `focus`, `input`, `ui`, `logs`, `screenshot`, `record`, `displays`,
`wake`, and `access`.
`resume`, `wait`, `launch`, `quit`, `focus`, `input`, `ui`, `logs`, `screenshot`, `record`, `pacing`,
`displays`, `wake`, and `access`.
**Setup > Session > Debugging tools** is off by default in every build, including debug builds.
**Setup > Diagnostics > Debugging tools** is off by default in every build, including debug builds.
It enables `run`, `guest`, `cdp`, all `env` operations, `override`, and `prefs`. The toggle switches
directly without a confirmation dialog. The bridge refuses to change it through `ui` or preference
writes. The existing preference key, `setting-agent-commands` test tag, JSON command names, and
@@ -75,53 +77,60 @@ artifact or file error, 7 debugging tools disabled.
## Commands
```sh
tools/droiddeckctl state # schema 2, below
tools/droiddeckctl start steam --wait # --ui desktop, --url steam://..., --timeout
tools/droiddeckctl start steam --wait --reuse # keep a Steam session that is already up
tools/droiddeckctl state
tools/droiddeckctl start steam --wait
tools/droiddeckctl start steam --wait --reuse
tools/droiddeckctl start desktop
tools/droiddeckctl run /usr/bin/foo -- arg1 arg2
tools/droiddeckctl wait ready|idle|failed # --timeout (default 90 s)
tools/droiddeckctl wait ready|idle|failed
tools/droiddeckctl stop
tools/droiddeckctl resume
tools/droiddeckctl launch 489830 --wait # Steam game by app id; --wait = until it has focus
tools/droiddeckctl wait focused 489830 # gamescope focuses it AND Steam lists it focusable
tools/droiddeckctl wait game # any app but the Steam client (769) has focus
tools/droiddeckctl quit 489830 # Steam's TerminateApp, then SIGTERM/SIGKILL
tools/droiddeckctl focus # focus properties and every Xwayland server's windows
tools/droiddeckctl launch 489830 --wait
tools/droiddeckctl wait focused 489830
tools/droiddeckctl wait game
tools/droiddeckctl quit 489830
tools/droiddeckctl focus
tools/droiddeckctl input key ENTER # names (ESC, F1, UP, A...) or evdev codes; --mod CTRL
tools/droiddeckctl input text 'hello world' # as US-layout keys; --commit for text-input
tools/droiddeckctl input tap 640 360 # session output pixels; --space fraction for 0..1
tools/droiddeckctl input key ENTER
tools/droiddeckctl input text 'hello world'
tools/droiddeckctl input tap 640 360
tools/droiddeckctl input swipe 100 600 100 100 --duration 400
tools/droiddeckctl input pad a # a b x y lb rb start select guide qam up down left right
tools/droiddeckctl input pad a
tools/droiddeckctl input stick left 0 -1 --hold 500
tools/droiddeckctl input trigger right 1.0
tools/droiddeckctl ui dump # tagged, labelled and clickable nodes; --all for every node
tools/droiddeckctl ui click rail-steam # by test tag
tools/droiddeckctl ui click --match "Play" # by text or description; --index for the nth match
tools/droiddeckctl ui dump
tools/droiddeckctl ui click rail-steam
tools/droiddeckctl ui click --match "Play"
tools/droiddeckctl ui set-text some-field --text abc
tools/droiddeckctl guest -- xprop -root GAMESCOPE_FOCUSED_APP # --timeout --env K=V --cwd --stdin --check
tools/droiddeckctl guest -- xprop -root GAMESCOPE_FOCUSED_APP
tools/droiddeckctl cdp targets
tools/droiddeckctl cdp eval 'SteamClient.Apps.GetMyRunningApps?.()' # --target, --no-await
tools/droiddeckctl env set DXVK_HUD=fps # next session only; --persistent until cleared
tools/droiddeckctl cdp eval 'SteamClient.Apps.GetMyRunningApps?.()'
tools/droiddeckctl env set DXVK_HUD=fps
tools/droiddeckctl env list
tools/droiddeckctl env clear [next|persistent|all]
tools/droiddeckctl override gamescope ./gamescope # first on the next session's PATH, removed after it
tools/droiddeckctl override gamescope ./gamescope
tools/droiddeckctl prefs get session
tools/droiddeckctl prefs set session some_key true --type bool # returns the previous value
tools/droiddeckctl prefs set session some_key true --type bool
tools/droiddeckctl logs latest ./session-artifacts
tools/droiddeckctl screenshot ./screen.png --display 4
tools/droiddeckctl record ./clip.mp4 --seconds 8 --display 0
tools/droiddeckctl displays # logical ids, names, sizes, capture ids
tools/droiddeckctl wake # wake the screen, dismiss the keyguard
tools/droiddeckctl pacing --seconds 30
tools/droiddeckctl displays
tools/droiddeckctl wake
```
A sleeping device suspends the session and hides the app's windows from `ui dump`; `wake` first.
`pacing` reads SurfaceFlinger's timestats for the game's layer (the session's SurfaceView when the
compositor has no layer of its own) and reports the frames that reached the panel, `fpsOnScreen`,
the present-to-present histogram and the share of intervals off the usual cadence. A game's own fps
counter counts frames handed over, not frames shown, so it can read 60 while one frame in four
stays on screen for two refreshes.
`input` needs a session that has drawn its first frame. Pad input goes through the session screen's
virtual pad, the same one the on-screen controls drive, so games that ignore touch still respond.
`launch`, `quit` and `cdp` need a Steam session; `focus` and `wait focused` need gamescope (every
+194
View File
@@ -0,0 +1,194 @@
# Cardboard VR (experimental)
Cardboard mode turns the session screen into a phone VR viewer (Google Cardboard and similar): the
panel is split into a left and a right eye, each drawn through a barrel distortion that the viewer's
lenses undo. Two sources can feed it:
- **Virtual screen** (any game, Steam, the desktop): the session hangs as a flat screen in front of
you, with real stereo depth from the eye distance. With head tracking on, the phone's rotation
sensor keeps the screen fixed in the room while your head turns (3DoF).
- **Side-by-side 3D**: the frame already holds a left and a right image. This is what SteamVR draws
here (below), and what SBS 3D video or a stereo shader like SuperDepth3D produces. Only the lens is
added.
The settings live in the session drawer, **Display > Cardboard VR**: mode, picture, viewer (lens
profile), eye distance, screen size and distance, head tracking and recenter, and SteamVR. Everything
applies live. `tools/droiddeckctl prefs set session cardboard '{"enabled":true,...}'` drives the same
settings (`gpu/Cardboard.kt` has the keys).
## How the picture is made
```
game / Steam -> gamescope -> DroidDeck compositor -> effects -> frame generation
-> Cardboard pass (cardboard.frag) -> 1:1 blit -> panel
```
`app/src/main/cpp/waylandcomp/src/cardboard.c` is the last stage of the compositor pass. It forces the
copy path (no zero-copy layer: the pass draws the whole panel) and renders `cardboard.frag` into a
panel-sized target:
- each output pixel picks its eye, finds its offset from that eye's lens centre in tangent space, and
applies the viewer's distortion polynomial `r(1 + k1 r² + k2 r⁴)` (sampling outwards draws the image
barrel-shaped; the lens pincushions it back), optionally per colour channel for chromatic
aberration;
- **virtual screen**: the ray from the eye (offset by half the IPD), rotated by the head pose,
meets a plane `screenDistance` away; outside it is a dark backdrop;
- **side-by-side**: the eye samples its own half of the frame over the same field of view.
The lens centres sit inset towards the nose so they line up with the viewer's lenses on the panel
actually used (the panel's physical size from DisplayMetrics). The field of view is the panel's height
seen from the lens's focal distance (`Cardboard.fovDeg`). Viewer profiles are in `Cardboard.Viewer`.
Head tracking (`gpu/HeadTracker.kt`) reads the game rotation vector (gyro and accelerometer, no compass)
on a thread of its own and hands a row-major head-to-world matrix straight to native code. Recenter
resets the heading only, so the horizon stays level. When the view is more than 60° from level (lying
back, or the device flat on a table) it takes the whole orientation as straight ahead. A new pose
redraws even a static scene (`vkp_cardboard_pose_changed` on the vsync tick).
The pose is also published to the guest: a 128-byte seqlocked file, `headpose_shm.h`, at
`/run/droiddeck/droiddeck-headpose`. It carries the rotation, the IPD, and the frustum the side-by-side
pass expects of a source (`tan_half_fov`, `eye_aspect`, eye size), so a renderer in the guest can match
the lens exactly.
## SteamVR
Valve's ARM64 SteamVR, the build the Steam Frame runs, comes from Valve's public SteamOS package
server (`deckard-steamvr`, pinned by version and SHA-256 in `droiddeck-steamvr`; the same hash
[steam-frame-nixos](https://github.com/y0usaf/steam-frame-nixos) pins). `droiddeck-steamvr install`
unpacks it to `/opt/steamvr`. The drawer's **Install** button runs that (571 MB). **Start** then
switches the picture to side-by-side and runs SteamVR with three DroidDeck pieces (`tools/vr`):
1. **`driver_droiddeck.so`**, an OpenVR driver with one HMD:
- pose: the shared head pose file (3DoF, standing height);
- projection: exactly the frustum the Cardboard pass samples, with identity distortion (the app does
the lens);
- a proximity sensor that reads "worn" while Cardboard mode is on. Without it SteamVR takes a still
headset (a phone on a table) for an unused one, enters standby after a few seconds, and the
compositor stops submitting frames;
- frames: `IVRDriverDirectModeComponent` with a free-running 60 Hz vsync announcer, as ALVR does on
Linux. SteamVR renders each eye into textures the driver allocates through its IPC resource
manager (dmabufs);
- `presenter.cpp` imports those eye textures into a Vulkan device of its own and blits them side
by side into a fullscreen window on DroidDeck's own compositor (`wayland-0`, the app_id
`droiddeck-cardboard-vr` keeps it above gamescope's window), sized to the Cardboard panel so
nothing scales it down. SteamVR hands the textures over with no fence the driver can wait on, so
the presenter gives the compositor's GPU work a few milliseconds first, as ALVR does.
`DROIDDECK_VR_PRESENT=x11` uses the older path instead: an X11 window on gamescope's Xwayland marked
`STEAM_OVERLAY` (the external overlay slot is mangoapp's), at the session's resolution;
2. **`VK_LAYER_DROIDDECK_vr`**, a Vulkan layer, enabled explicitly in SteamVR's processes and implicit
for the rest of the session (Steam's own web helper shares its in-VR overlay with SteamVR too, and
crashes without it until Steam quits). Implicitly it does nothing in an ordinary session:
- the display stand-in below happens only while SteamVR runs (`droiddeck-steamvr`'s `active`
marker, which a new session clears) or where the layer is enabled by name. Gamescope and games
asking for display extensions outside SteamVR get them untouched;
- the semaphore bridge runs in those same processes, and in Steam's web helper once SteamVR is
installed;
- with SteamVR not installed, every process gets the driver's functions unchanged.
What it does in SteamVR's processes:
- `vrcompositor` always asks for `VK_KHR_display` and keeps a direct-mode window even with a
driver-direct HMD. Turnip on KGSL refuses to enumerate any GPU when `VK_KHR_display` is enabled
("I can't KHR_display"). The layer takes the display extensions off the instance and stands in
for one display with one mode and one plane, whose surface is a headless one
(`VK_EXT_headless_surface`, sized from the mode because headless reports none). The vblank side
of `VK_EXT_display_control` is a 60 Hz clock;
- SteamVR shares a timeline semaphore with every shared image, exported as an opaque fd, which
Turnip/KGSL cannot export. The layer creates it unshared and hands out a memfd holding a 64-bit
counter instead. Every process with the semaphore keeps a real local one, and a poller thread
carries values both ways (reached locally: up into the counter; seen in the counter: signalled
locally from the host), so GPU waits work as written, a poll period late. Waits on an imported
binary semaphore, which cannot be bridged that way, are dropped. With the semaphores dropped
outright (the first version) the dashboard showed torn, half-drawn tiles;
- Turnip on KGSL does not defer a submit that waits on a timeline value nobody has signalled yet:
`vkQueueSubmit` blocks until it is. SteamVR's client waits on a compositor value that the
compositor signals only after the client has submitted and said so, which deadlocked every app
before its first frame (`helloxr`'s swapchain acquire, DXVK's submit thread in a Proton game).
A submit's wait on an imported shared value that is neither reached nor queued in that process
gets 3 ms for the other process to reach it, then is dropped;
- Steam's web helper has the semaphore bridge whenever SteamVR is installed: its GPU process
outlives SteamVR runs, and one started without the layer crashed when SteamVR showed Steam's
overlays, until Steam quit;
- `DROIDDECK_VR_CRASHTRACE=1` (or a `crashtrace` file beside the `active` marker, for processes like
Steam whose environment is not ours) prints a backtrace on a fatal signal. `vrcompositor`'s
launcher drops `LD_PRELOAD`, but the layer is loaded there. It only takes signals nobody handles
yet: Wine and FEX handle `SIGSEGV` as part of running a Proton game, and a replaced handler
crashed The Lab;
- a `semtrace` file beside the marker logs, every 2 s, each bridged semaphore's local and shared
value and the memfd inode that names it in every process, plus the first waits and signals
(values up to 3) submitted on them.
3. **`droiddeck-steamvr`**, the guest helper (`status | install | start | stop`), which the app drives
through the guest agent's fixed `vr` request (no agent commands needed). It also supplies an `xset`
stand-in, because the dashboard's web helper checks the X server with it.
Imported eye textures carry the same format list SteamVR's mutable sRGB images do. With it Turnip keeps
UBWC compression on, and an import that disagreed read compressed data as garbage.
Two more fixes outside `tools/vr` were needed for the dashboard (Steam's library, in VR):
- **SysV semaphores** (`tools/linuxfs/preload/sysv.c`): the session emulates them, and `IPC_STAT`
reported `sem_otime` 0 forever. SteamVR's web helper does the usual race-free init (wait until
`sem_otime` is non-zero), so its zygotes slept in a `semctl`/`usleep` loop and the dashboard never
appeared. `semop` now stamps `sem_otime`, `SETVAL`/`SETALL`/`IPC_SET` stamp `sem_ctime`;
`test_sysv_preload.py` covers it.
- `vrwebhelper` gets the same tracer treatment as Steam's `steamwebhelper` (`tracer.c`).
Verified on the AYN Thor (SD 8 Gen 2, Turnip): SteamVR 2.17.10 starts with the DroidDeck HMD active,
the compositor runs driver-direct at about 60 fps, the dashboard (Steam's library in VR, with the
controller's laser) shows cleanly in both eyes at the panel's resolution while Steam keeps running, and
a pose written to the shared file turns SteamVR's view. Started from the drawer button through the agent.
### Not done yet
- **Controllers**: the driver adds two Vive-profile hands driven by the session's game pad. It reads
the absolute-state snapshot the app already publishes in fake input ring 0
(`FAKE_EVDEV_MEMFD_PATHS`), so the app needs no new plumbing. They are a gaze pointer: low in front
of each hand, pointing where the head looks. Mapping, right hand: right stick = trackpad, A/R3 =
trackpad click, RT = trigger, RB = grip, Start = menu, guide = system. Left hand: left stick, X/L3,
LT, LB, Select. Both hands activate in SteamVR and their laser shows on the dashboard; guide, Start and
A presses show up in the ring the driver reads.
- **Layers**: only the first layer of each frame is drawn. SteamVR's compositor composites the
dashboard into it, so this has not mattered yet.
- **Timing**: no reprojection, and the presenter blits whatever was submitted last, a guard delay
after it arrived. The chain is SteamVR → presenter → DroidDeck compositor → lens pass.
- **Cross-process GPU sync** is a poll away from exact (see the semaphore note above); binary
semaphores are not bridged.
- **Apps and games**: Windows VR games run through Proton ARM64 (FEX for the x86-64 game, DXVK, and
Proton's `vrclient_x64` bridging to SteamVR's ARM64 `vrclient.so`). Tested on the Thor:
- **Thumper** (356400, its own D3D11 engine), started with its VR launch option: menus and levels
at 60 Hz, about 7 ms CPU and 13 ms GPU a frame, 23 dropped frames in 6485;
- **The Thrill of the Fight** (494150, Unity): loads into its gym, 60 Hz with 6.5 ms CPU and 8.5 ms
GPU a frame;
- **The Lab** (6.6 GB) loads, but Android's low-memory killer took the whole app while it did, next
to Steam and SteamVR. Two VR games at once do the same, so quit one (`droiddeckctl quit <appid>`)
before starting the next;
- **SUPERHOT VR** stops at its EULA, which SteamVR's dashboard shows in VR;
- **SteamVR Home** is not in the ARM64 package. Steam's own Windows SteamVR (250820) has it
(`tools/steamvr_environments`, `steamtours.exe`), and it starts under Proton, but Proton's
`vrclient_x64` implements only `IVROverlayView_003` and Home asks for `_002`, so it stops at
"SteamVR initialization failed!";
- SteamVR's ARM64 OpenXR sample, `helloxr -g Vulkan2`, reaches a focused session and submits frames
(it was stuck before the first one until the wait fix above), but its picture shows up as torn
tiles: next to chase. `hellovr_sdl` (OpenGL) needs GLEW, which the runtime lacks.
SteamVR opens its game menu over a newly started game; `vrcmd --hidedashboard` (in
`/opt/steamvr/bin/linuxarm64`) closes it.
- **Quest 3**: unrelated to this; on the Quest DroidDeck stays a 2D panel (`docs/quest.md`).
## Building and testing
- `tools/vr/build.sh [OUT]` builds the driver and the layer in the local cross image, or
`--native OUT` with aarch64 compilers on PATH (CI). `tools/build_local.sh` and CI put them in the
APK under `assets/linuxfs/usr/local/lib/droiddeck-vr`; `SessionFiles` stages them, and
`droiddeck-steamvr`, into the rootfs.
- Shader: `cardboard_frag.h` is generated from `cardboard.frag`
(`glslangValidator -V --vn cardboard_frag_code -o cardboard_frag.h cardboard.frag`).
`tools/tests/test_cardboard.py` checks it is current, and checks the push-constant packing on the
host.
- `CardboardTest` covers the settings, lens inset and field of view, the head-pose maths (quaternions,
display-rotation remaps, recentring) and the SteamVR status. `test_droiddeck_agent.py` covers the
`vr` request.
- Logs: the compositor's `[cardboard]` lines; SteamVR's in `~/.local/share/Steam/logs`
(`vrserver.txt`, `vrcompositor.txt`) and `/run/droiddeck/droiddeck-steamvr/vrstartup.log`. The
driver's lines start with `droiddeck:`.
Lessons from bringing this up on the Thor, and how to debug a live session: `docs/development/cardboard-vr-learnings.md`.
+13 -4
View File
@@ -66,10 +66,19 @@ value holds on both sides.
Automatic: the game folder's own images, then Steam (the appid the files name, else a
store search whose result has the same name), then SteamGridDB, then the exe's icon. The
art chooser (an Artwork row) shows the game folder's images, Steam's official piece and
SteamGridDB's best few (fetched when it opens); a tap applies one, "Pick image…" takes a
file through the same picker (png, jpg, jpeg, webp, ico), "Reset to automatic" drops the
choice. A choice is a copy in `files/added-art/<appid>/chosen-<slot>.<ext>`, its source in
the preferences.
SteamGridDB's best few (fetched when it opens); a tap applies one, "Search SteamGridDB…"
opens a search (it starts with the game's name and opens the match at once when one is
exact; "Show more" pages through the images), "Pick image…" takes a file through the same
picker (png, jpg, jpeg, webp, ico), "Reset to automatic" drops the choice. A choice is a
copy in `files/added-art/<appid>/chosen-<slot>.<ext>`, its source in the preferences.
SteamGridDB failures are told apart (`SteamGridDb.Status`: no key, key refused, rate limit,
offline, server, no match for the game) and shown under the SteamGridDB images instead of
leaving the row out. The SteamGridDB game id is remembered per game in
`added-art/<appid>/sgdb-id`; "none" (SteamGridDB has no such game) is kept for a week, but
a failed request is never written as "none", a "none" older than the saved key is asked
again, and the chooser always asks again when the user opens it. A background pass stops
asking SteamGridDB after its first failure.
Setup › Launcher › Games holds the Artwork switch (automatic fetching) and the
SteamGridDB API key: the user's own, sealed with `CredentialCipher`, wins over the build's
+175
View File
@@ -0,0 +1,175 @@
# Amazon Games module: clean-room rewrite
The Amazon Games integration (the Rust `amazon` module in `libdroiddeckstores.so` and the Kotlin
package `com.droiddeck.launcher.stores.amazon`) was rewritten so that it carries no code from the
earlier implementation. This page records how that was done and every judgement call the new code
makes.
## Process
1. **Spec, written separately.** A functional specification (six documents: summary and unknowns,
service protocol, manifest format, install behaviour, on-disk compatibility, and the app-facing
interface) was written from the old code by a separate pass. It describes behaviour and data
formats only, not code structure.
2. **Implementation from the spec only.** The implementer worked from those documents and from
code that is not Amazon-specific:
- read: the spec; the crate's `Cargo.toml`, `Cargo.lock`, `lib.rs`, `stores_jni.rs`,
`priority.rs`, `fetch_tuning.rs` and the shared `fetch_core.rs`; the clean-room Epic module
(Rust and Kotlin) as the structural template; `JNI.md`; the shared Kotlin store code (account
store, install records, download queue, login activity, catalog and state); the signatures and
call sites of `StoreSizes`' Amazon branch (to keep them compiling); build files and CI;
- not read: anything under `stores/amazon/` (Kotlin, Java, tests) or `src/amazon*` (Rust) of the
old tree, other branches or checkouts, or any Amazon client source. The old files were deleted
with `git rm` without being opened.
3. **Fresh code.** Every file has its own structure, names and comments, with a plain description
and `SPDX-License-Identifier: GPL-3.0-or-later` (the crate's licence). Where the spec left a fact
open, the choice was made from general knowledge of Amazon's public services or from
unauthenticated probes of the live endpoints (below), and is listed here.
## Layout
Rust, `app/src/main/rust/stores/src/amazon/`:
| File | Role |
|---|---|
| `net.rs` | blocking HTTP (reqwest + rustls), the three User-Agent identities, hex / percent / base64url helpers, URL scrubbing for logs |
| `auth.rs` | per-attempt device serial, client id, PKCE verifier and challenge; sign-in URL; code from the return URL; registration, refresh, deregistration |
| `distribution.rs` | the distribution service call shape (`X-Amz-Target`, `x-amzn-token`, `Content-Encoding: amz-1.0`), refusal detection, the download lookup |
| `library.rs` | entitlement pages, field fallbacks, de-duplication, add-on filter, sort |
| `cdn.rs` | path insertion before the signed query, file URLs, the manifest GET |
| `codec.rs` | manifest framing (big-endian header length) and xz / LZMA-alone decompression (`lzma-rs`) |
| `proto.rs` | a strict protobuf wire reader (and test writers) |
| `manifest.rs` | packages → files, path normalisation and safety, duplicate handling |
| `install/` | `mod.rs` (the run), `check.rs` (completeness, stray `.tmp`, free space), `writer.rs` (streamed download, SHA-256, atomic placement), `tests.rs` (loopback end-to-end) |
| `launch.rs` | `fuel.json`, exe scoring, the FuelPump environment |
| `service.rs`, `ffi.rs` | named operations and the JNI boundary |
Kotlin, `app/src/main/java/com/droiddeck/launcher/stores/amazon/`: `AmazonBackend` (the
`StoreBackend`, installs the login flow), `AmazonLogin` (the WebView flow), `AmazonCredentialStore`
(the account through `StoreAccounts`, single-flight refresh), `AmazonPrefs`, `AmazonLibrary` (sync,
cache, posters, publishing), `AmazonInstaller` (the queue job), `AmazonNative` (JNI), and two thin
wrappers kept for `StoreSizes`: `AmazonApiClient` (`getGameDownload`, `getBytes`, `appendPath`) and
`AmazonManifest` (`parse(bytes).totalInstallSize`).
The JNI surface (`nativeConfigure`, `nativeCall`, `nativeFetch`, `nativeInspect`, `nativeInstall`,
`nativeCancel`, `nativeRelease`) is documented in `app/src/main/rust/stores/JNI.md`. The old
`nativeStart` symbol is gone. The Java xz library stays in `app/build.gradle`: commons-compress
needs it for the `.tar.xz` Windows components, so only Amazon stopped using it.
## Compatibility kept exactly
- Credentials (`stores/amazon/credentials.json` through `StoreAccounts`): the same keys
(`access_token`, `refresh_token`, `device_serial`, `client_id`, `expires_at`, `display_name`). A
refresh merges `access_token`, `device_serial`, `client_id`, `expires_at` into the stored record
and keeps every other key; a new sign-in writes the whole record. Registration and refresh keep
the launcher's device constants, so existing refresh tokens keep working.
- Preferences `stores.amazon`: `library_cache` (same element keys), `library_synced_at`,
`vcover_<id>`, `size_<id>`, `version_<id>`; sign-out removes only the first two.
- Install folders, the sidecar keys (`extra.entitlementId`, `extra.sku`, no `cloud` key), the
launcher name `.droiddeck-launch.bat`, the `.tmp` naming and the two marker files.
- The catalog item's `extra` (`entitlementId`, `sku`, `version` = `""`) so the shared size cache and
the saved queue keep working.
## User-Agents and what the probes showed
Unauthenticated probes of the live services (2026-10-14):
- **Distribution service** (`gaming.amazon.com`): `GetEntitlements`, `GetGameDownload` and
`GetLiveVersionIds` answered identically for `AGSLauncher/1.0.0`, `DroidDeck/…`, a curl UA, with
and without the `UserAgent` header. A bad token gives HTTP 401 `<NotAuthorizedException/>`; no
token gives HTTP 400 with `com.amazon.coral.service#NotAuthorizedException`. The probes cannot
show whether the UA matters for an authorised call, so the launcher's `User-Agent` and
`UserAgent` values are kept (Amazon's own client identifiers, one constant each in `net.rs`).
- **Identity API** (`api.amazon.com`): register, token and deregister gave the same validation
errors whatever the UA (Firefox, `DroidDeck/…`, none). The desktop Firefox string is kept for
these calls, the same as the WebView: it is a generic browser label, not a client name, and
existing refresh tokens are known to work with it.
- **Sign-in page** (`www.amazon.com/ap/signin`): every UA got Amazon's bot check from the probe
host, so nothing could be learned; the WebView keeps the desktop Firefox string (a sign-in page
that misbehaves would lock every user out).
- **CDN**: no URL is reachable without a token. Manifest and file requests now send
`DroidDeck/<versionName>`, the only third-party label the old integration sent; this needs the
device test below.
Refusal detection follows the probes: 401, 403, and 400 whose body names `NotAuthorizedException`
mean "sign in again".
## Judgement calls
Recommended fixes from the spec, adopted:
1. **Complete = size and SHA-256.** One test for the space check and the download plan; a
same-size corrupt file is repaired. Files without a SHA-256 (another algorithm) are judged by
size. No cross-run "verified" cache: every present file is hashed on each run.
2. **A failed library page fails the sync** and keeps the old cache; a refused token is reported
with the shared "session expired: sign in again" line, also when a cache is shown.
3. **Single-flight refresh** (`AmazonCredentialStore`); a forced refresh after a failed library call
skips the refresh when another caller already replaced the token.
4. **Mark updating** (`beforeReplace` → `StoreInstalls.markUpdating`) once, before the first file
is put in place (new or replacing; the shared step only acts on an installed record).
5. **Manifest path safety**: absolute paths, any `:` (drive letters and stream names; Windows file
names cannot contain it), NUL, `.` / `..` and empty segments, and DroidDeck's own root files
(`.droiddeck-store.json` and its `.tmp`, `.droiddeck-launch.bat`, the two markers, compared
ignoring case) fail the install naming the path. A manifest that lists both `X` and `X.tmp` is
refused (the second would collide with the first's temporary file). The protobuf reader rejects
truncation, over-long varints, groups and unknown wire types, field number 0, wrong wire types
on the fields used, and a non-empty file without a hash or a SHA-256 that is not 32 bytes.
6. **Exe scoring on relative paths.** The Unreal-folder rule is tested against `"/" + relative
path` so a top-level `Binaries/Win64/…` still matches. The "first five letters" rule compares the
title with the file name **without** `.exe` (the extension's letters would otherwise count). An
empty title never matches the "path contains the title" rule. Ties: larger file, then the earlier
path. Only regular files are candidates; symlinks are not followed; depth is capped at 16.
7. **CDN User-Agent** is `DroidDeck/<versionName>` (see above).
8. **Empty files** whose hash is absent or the SHA-256 of empty input are created locally; stray
`.tmp` siblings of manifest files are removed at run start (other `.tmp` files are untouched).
9. **Markers** `.amazon_download_in_progress` / `.amazon_download_complete` are still written.
10. **Duplicate paths**: the later entry wins with a log warning; files sharing one hash are fetched
once per path (no copy optimisation).
Other choices:
- **Install size** is the sum over distinct paths (equal to the spec's "duplicates included" sum
for every manifest without duplicate paths, which none have been seen to have); it is the
progress total, the disk size and `size_<id>`.
- **Free space** is measured in Rust (`statvfs` on the folder or its nearest existing parent),
which is what the shared probe measures; unknown never blocks, a measured zero does.
- **Pre-download check** is reported in the queue's Manifest stage ("Checking files…" with byte
progress), like GOG and Epic: the Downloads UI orders stages Manifest → Download → Verify →
Install, so a Verify stage before Download would read backwards.
- **Concurrency**: one streamed GET per file through the shared fetch core in stream mode (the
speed tier's window clamped to 1–128, per-host cap `max(6, ceil(window / hosts))`, 120 s to the
response headers, the core's 30 s idle cap on the body, its five attempts with back-off and its
stall and 429 handling). A piece at offset 0 restarts the file (a retry); an out-of-order piece,
a body longer than the manifest size, a short body or a hash mismatch deletes the `.tmp` and is
retried; a write error, a refused `beforeReplace` or a failed rename fails the run.
- **Decompression** uses the `lzma-rs` crate (pure Rust; xz with any check type and LZMA-alone),
with a 256 MiB cap on the decompressed manifest.
- **Live version lookup** (`GetLiveVersionIds`) is not implemented; nothing used it.
- **DLC filter**: add-ons are hidden only when they also name a parent product (as the spec's sync
contract says), unless that would hide everything; the Rust call returns the filtered, sorted list
plus the unfiltered count.
- **Sign-in code**: the authorization code is read from the return URL's query (`%XX` decoded, `+`
kept literally; codes are URL-safe). The WebView flow passes the URL to Rust and never logs it.
- **Randomness** for the serial and verifier comes from `/dev/urandom`.
- **`fuel.json`** is found by exact name, else a case-insensitive match at the folder root; a UTF-8
BOM is accepted. `Main.Command` is accepted after stripping leading `/` and `./`, and must be a
safe relative path naming a regular file.
- **Logs**: the Rust side strips the query string and fragment of every URL in a line before it
reaches `onLog`; the shared redaction runs after that as before.
- **No engine, no store**: without the native library, sign-in, sync and install report
"Amazon Games: the store engine is not available"; there is no Java fallback.
## What needs device testing
- An existing signed-in user stays signed in after the update: the library shows from cache at once,
and a forced sync refreshes the token with the stored refresh token and lists the games.
- A fresh sign-in through the WebView (registration, display name), and sign-out (deregistration
fired, library cache cleared).
- A library with many pages; add-ons hidden; posters.
- Install, pause, resume, cancel (folder removed); repair of an installed game (nothing downloaded
when intact; a corrupted file fetched again; "Resume install" offered when a repair is
interrupted); an SD-card install; out-of-space refusal.
- Every endpoint with the chosen User-Agents, the CDN with `DroidDeck/…` in particular.
- Launch of an existing install through its existing Steam shortcut (same shortcut, same prefix)
and of a fresh install (exe choice, `fuel.json` arguments, the five FuelPump variables in
`.droiddeck-launch.bat`); uninstall.
+131
View File
@@ -0,0 +1,131 @@
# Cardboard VR and SteamVR on Turnip: what we learned
Written 2026-10-13, after the first stretch of Cardboard mode work on the AYN Thor (Snapdragon 8 Gen 2,
Adreno 740, Turnip on KGSL). `docs/cardboard-vr.md` describes how the feature works. This page records
what it took to get there: the traps, why each fix looks the way it does, how to debug a live session,
and what is still open. Read it before the next round of VR work.
## Where it stands
| What | Result |
| --- | --- |
| Cardboard mode (lens pass, 3DoF head tracking, recentre) | Works on any picture; picture follows SteamVR on and off |
| SteamVR 2.17.10 ARM64 (the Steam Frame's `deckard-steamvr`) | Starts from the drawer; driver-direct at 60 Hz, dashboard and Steam library in VR |
| Thumper (356400, D3D11, VR launch option) | Menus and levels at 60 Hz, 7 ms CPU / 13 ms GPU, 23 of 6485 frames dropped |
| The Thrill of the Fight (494150, Unity) | Gym loads, 60 Hz, 6.5 ms CPU / 8.5 ms GPU |
| The Lab (450390) | Loads, then Android's low-memory killer takes the whole app |
| SUPERHOT VR (617830) | Reaches its EULA in the dashboard (not accepted in testing) |
| SteamVR Home | Blocked: Proton's `vrclient_x64` lacks `IVROverlayView_002` |
| `helloxr -g Vulkan2` (OpenXR) | Session focused and submitting, picture shows as torn tiles |
Screenshots from the Thor: [Thumper gameplay](evidence/cardboard-thumper-vr-gameplay-2026-10-13.png),
[Thumper title](evidence/cardboard-thumper-vr-cardboard-2026-10-13.png),
[The Thrill of the Fight](evidence/cardboard-thrill-of-the-fight-cardboard-2026-10-13.png),
[the SteamVR dashboard with a game's EULA](evidence/cardboard-steamvr-dashboard-2026-10-13.png).
Games run as x86-64 Windows builds through Proton ARM64 (FEX, DXVK). Proton's `vrclient_x64` forwards
OpenVR to SteamVR's ARM64 `vrclient.so`, so no x86 SteamVR is involved.
## Turnip on KGSL: the four things SteamVR trips over
1. **`VK_KHR_display` makes the GPU disappear.** Turnip on KGSL enumerates no physical device when an
instance enables it ("I can't KHR_display"). `vrcompositor` always asks for it. The layer takes the
display extensions off the instance and fakes one display, mode and plane backed by a headless
surface. Headless surfaces report a `UINT32_MAX` extent, so the swapchain is sized from the mode.
2. **No exportable semaphores.** SteamVR shares a timeline semaphore with every shared image as an
opaque fd, and Turnip/KGSL cannot export one. The layer creates the semaphore unshared and hands out
a memfd (`droiddeck-shared-sem`) holding a 64-bit counter. A poller thread in each process carries
values both ways every 300 µs. Dropping the semaphores outright, the first attempt, gave torn
dashboard tiles.
3. **Wait-before-signal blocks the submitting thread.** Turnip does not defer a submit that waits on
a timeline value nobody has signalled yet; `vkQueueSubmit` sleeps until it is. SteamVR's client
waits on a compositor value that the compositor signals only after the client has submitted and
said so, so every client deadlocked before its first frame:
- `helloxr` blocked in a wait-idle in `vrclient.so`;
- DXVK's `dxvk-queue` thread blocked in Proton games.
The layer now gives a submit's wait on an imported shared value 3 ms, then drops it. It is kept
when the value is already reached, or when this process has queued the signal itself. Two details
mattered:
- the waits are judged before the submit's own signals count, because an acquire waits on one
value and signals the next on the same semaphore;
- SteamVR's client interop device is Vulkan 1.0, so only the `KHR` entry points resolve there.
4. **UBWC layouts must agree.** An imported image has to be created with the same
`VkImageFormatListCreateInfo` (sRGB + UNORM) as its creator, or Turnip lays out the compression
differently and the reader sees garbage. The presenter's eye-texture import does this.
## Other traps, in the order they cost time
- **A still headset goes to standby.** A phone on a table looks unworn, SteamVR enters standby after
about 15 s, and the compositor stops submitting. The driver's proximity sensor reads "worn" while
Cardboard is on.
- **Emulated SysV semaphores never set `sem_otime`.** SteamVR's web helper waits for it to become
non-zero before using a semaphore set, so the dashboard never appeared. `sysv.c` now stamps
`sem_otime` and `sem_ctime`.
- **Steam's web helper needs the layer too.** It shares Steam's in-VR overlays with SteamVR and crashed
without the layer; after a few crashes Steam quits. Its GPU process outlives SteamVR runs, so
`steamwebhelper` gets the semaphore bridge whenever SteamVR is installed, not only while SteamVR's
`active` marker exists. It never gets the display stand-in.
- **Keep the layer out of ordinary sessions.** As an implicit layer it loads everywhere. Display
extensions are only taken off while SteamVR runs, a new session clears a leftover `active` marker,
and without SteamVR installed every process gets the driver's functions unchanged. Review feedback
on the first version pointed out that gamescope asking for a display extension would have been
rewritten in an ordinary session.
- **The `active` marker race.** Clearing a stale marker whenever `vrserver` is not running also
cleared it during startup, before `vrserver` appeared, because the app polls status every 3 s. Steam
quit as a result. Only a marker older than 2 minutes is cleared now.
- **Signal handlers in Proton games.** The layer's crash tracer replaced the `SIGSEGV` handler that FEX
and Wine rely on, and The Lab crashed in FEX's JIT. It now installs only where nothing handles the
signal.
- **mangoapp owns gamescope's single external overlay slot**, so an X11 presenter has to use
`STEAM_OVERLAY`. The default presenter is now a Wayland window on DroidDeck's own compositor, kept
on top by app id.
- **Memory.** Steam, SteamVR and one VR game fit in the Thor's 12 GB. A large game such as The Lab, or
two games at once, push the device into critical pressure, and the low-memory killer takes
DroidDeck itself (`ended-without-teardown.txt` in the session logs, `lowmemorykiller` in logcat).
- **Head-tracking axes.** With the display at `ROTATION_90`, screen x is minus device y and screen y is
device x. Getting this wrong made a turn at the hips tilt the view. Recentring now keeps the world
vertical and resets the heading only.
## Debugging a live session
- **Logs:** `~/.local/share/Steam/logs/{vrserver,vrcompositor,xrclient_*}.txt` and
`/run/droiddeck/droiddeck-steamvr/vrstartup.log`. Lines from the driver start with `droiddeck:`,
lines from the layer with `[droiddeck-vr-layer]`. A game's layer messages land in the session log.
- **Markers beside `active`** in `/run/droiddeck/droiddeck-steamvr/`:
- `crashtrace` prints backtraces on fatal signals;
- `semtrace` logs each bridged semaphore's local and shared value every 2 s, named by the memfd
inode so the same semaphore can be matched across processes, plus the first waits, signals and
shared image create infos.
Both are read when a process starts.
- **Frame stats:** in `/opt/steamvr/bin/linuxarm64`, `LD_LIBRARY_PATH=. ./vrcmd --stats` reports
submits, drops and app CPU/GPU times. `./vrcmd --hidedashboard` closes the menu SteamVR opens over a
new game.
- **Where a process is stuck:** a stack scan of `/proc/<tid>/mem` from the saved stack pointer (a small
Python helper) gives module+offset frames. That is how the wait-idle in `vrclient.so` and the
blocked `dxvk-queue` thread were found.
- **VR launch options:** `SteamClient.Apps.GetLaunchOptionsForApp(id)` lists them, and
`SteamClient.Apps.RunGame("<id>", "", <index>, 100)` starts one, through `droiddeckctl cdp eval`.
- **Quitting:** `droiddeckctl quit <appid>`. Without the id the game keeps running.
- **Pitfalls when testing:**
- never `pkill -f` or `pgrep -f` a pattern inside a guest command, because it matches the
command's own shell; use `pgrep -x`;
- replace a loaded `.so` by copying to a temporary name and `mv`, never `cp` over it;
- a session start restages the driver and layer from the APK assets, so a hand-copied build is
lost on the next start.
## Open items
- **`helloxr` picture.** Both sides create the swapchain images with identical parameters, so this is
not the UBWC import issue. Reading an image mid-render (the dropped wait) or binning tiles is the
next suspicion.
- **SteamVR Home** needs `IVROverlayView_002` in Proton's `vrclient`, or an ARM64 build of Home.
- **The Lab and other large games** need memory headroom. Candidates: stop Steam's own web helpers
while a VR game runs, or lower SteamVR's footprint.
- **Wait drops are a heuristic.** A 3 ms grace keeps the common case in sync. A submit thread in the
layer, deferring submits until their waits are reachable, would be exact.
- **Layers:** only the first layer of each frame is presented. No reprojection.
- **Controllers** are a gaze pointer driven by the pad. Pad presses did not close the SteamVR menu in
testing. Untested: whether that came from gamescope focus being on Steam, or from the system button
mapping.
@@ -0,0 +1,29 @@
# Discord build channels
Use the same names as the app's Updates page:
| App | Discord | Builds | Existing webhook secret |
| --- | --- | --- | --- |
| Preview | [#preview-builds](https://discord.com/channels/1552707793247539220/1554202932965015583) | Signed builds of `main`, including merged fixes | `DISCORD_BUILDS_WEBHOOK` |
| Test builds | [#test-builds](https://discord.com/channels/1552707793247539220/1557605185365217340) | Signed builds of individual open pull requests | `DISCORD_PR_BUILDS_WEBHOOK` |
Stable contains tested releases published from version tags. Preview contains the newest
merged fixes before Stable; Test builds let users try an unmerged fix by its PR number.
## Renaming safely
Rename the existing Discord channels in place. Keep their IDs, permissions, and webhooks.
The webhook URLs used by `build.yml`, `pr-release-publish.yml`, and `pr-release-cleanup.yml`
route by ID, so changing a channel's name or topic needs no secret rotation or routing change.
Keep the existing GitHub secret names even though they use the old channel terminology.
PR publication saves `webhook_id` and `message_id` in the signed build report comment.
Republishing edits that message; closing or merging the PR retires it. Neither operation
looks up a Discord channel by name. Keep the existing webhook so those saved references
continue to work. Recreating a channel or webhook is a different operation and needs a
separate migration.
For future renames, check the channel and webhook IDs before and after, verify that the
existing webhook token can still read an earlier build message, and inspect the next
publish/update/retirement runs. Separately hosted bots may have their own configuration;
this repository only controls the GitHub Actions build announcements.
+144
View File
@@ -0,0 +1,144 @@
# Epic Games Store module: clean-room rewrite
The Epic integration (the Rust `epic` module in `libdroiddeckstores.so` and the Kotlin package
`com.droiddeck.launcher.stores.epic`) was rewritten so that it carries no code from the earlier
implementation, whose Rust module stated derivation from third-party Epic clients. This page
records how that was done and every judgement call the new code makes.
## Process
1. **Spec, written separately.** A functional specification (six documents: summary and unknowns,
service protocol, manifest and chunk formats, install behaviour, on-disk compatibility, and the
app-facing interface) was written from the old code by a separate pass. It describes behaviour
and data formats only, not code structure.
2. **Implementation from the spec only.** The implementer worked from those documents and from
code that is not Epic-specific:
- read: the spec; the crate's `Cargo.toml`, `lib.rs`, `stores_jni.rs`, `priority.rs`,
`fetch_tuning.rs`, the shared `fetch_core.rs` and the GOG module (for crate, threading and JNI
conventions); `JNI.md`; the Kotlin code outside `stores/epic/` that calls Epic (to keep its API);
build files and CI;
- not read: anything under `stores/epic/` (Kotlin, Java, tests) or `src/epic*` (Rust) of the old
tree, the body of the old `EpicCloud` class and of `CloudSavePaths.epic`, other branches or
checkouts, or any Epic client source. The old files were deleted with `git rm` without being
opened. (A search over shared files incidentally printed two lines of the old `EpicCloud`, its
base URL and User-Agent constant; both values are in the spec and only the URL is used.)
3. **Fresh code.** Every file of the new module has its own structure, names and comments, with a
plain description and `SPDX-License-Identifier: GPL-3.0-or-later` (the crate's licence). Where
the spec left a fact open, the choice was made from general knowledge of Epic's public services
and is listed below.
## Layout
| Rust (`app/src/main/rust/stores/src/epic/`) | |
|---|---|
| `net.rs` | blocking HTTP helper, the one User-Agent, percent/base64 encoders |
| `account.rs` | sign-in with an authorization code, refresh, exchange codes, redirect-page parsing |
| `library.rs`, `catalog.rs` | owned items (all pages), catalog details and attributes |
| `build_info.rs` | live build lookup, CDN list, manifest download |
| `manifest.rs`, `chunk.rs` | binary and JSON manifests, chunk files |
| `locale.rs` | device language → install tags, tag selection |
| `install/` | the install engine: `staging`, `delta`, `space`, `cache`, `schedule`, `writer`, `mod` (orchestration), end-to-end `tests` against a loopback server |
| `shop.rs`, `achievements.rs`, `savesync.rs`, `launch.rs`, `timefmt.rs` | shelves, achievements, cloud saves, launch arguments, ISO dates |
| `service.rs`, `ffi.rs` | the JSON operations and the JNI entry points |
| Kotlin (`stores/epic/`) | |
|---|---|
| `EpicBackend` | `StoreBackend` + `EpicLaunchSupport`; installs the login flow |
| `EpicLogin` | the `StoreLoginActivity.Flow` |
| `EpicCredentialStore`, `EpicPrefs` | account (shared Keystore store), `stores.epic` prefs |
| `EpicLibrary`, `EpicShelves` | library sync and cache, shop shelves |
| `EpicInstaller` | the download-queue job |
| `EpicApiClient`, `EpicDownloadManager`, `EpicInstallTags`, `EpicAchievements` | API kept for callers outside the package |
| `EpicSaveSync`, `EpicSaveTemplate` | cloud-save transfers for `EpicCloud`, template parsing for `CloudSavePaths.epic` |
| `EpicNative` | JNI wrapper (see `rust/stores/JNI.md`) |
## Judgement calls
Numbers in brackets refer to the spec's list of unknowns.
**Fixed where clearly correct**
1. OAuth form values (authorization code, refresh token) are percent-encoded [9].
2. A library page that fails ends the sync with an error and keeps the cached library instead of
caching a partial one; an HTTP 401 is reported as "session expired: sign in again" rather than
an empty library [7].
**Chosen where the spec left it open**
3. **User-Agent** [1]: every HTTP request (account, library, catalog, build info, CDNs, store
GraphQL, promotions, cloud saves) sends `DroidDeck/<versionName>`, defined once in
`epic/net.rs` (`USER_AGENT_PRODUCT`); changing that constant is the one place to adjust.
Achievements are the exception: Epic's achievements service rejects other agents, so
`epic/achievements.rs` sends Epic's launcher agent (`net.rs::EPIC_LAUNCHER_USER_AGENT`). The sign-in **WebView** keeps the launcher-style UA it used
before, because a sign-in page that rejects the UA would lock every user out; that string lives
in `epic/account.rs` (`WEBVIEW_USER_AGENT`).
4. **Shared fetch core** [14]: chunk downloads reuse the crate's store-agnostic `fetch_core` (also
used by GOG and Amazon; it came from Bannerlator's own crate and, unlike the old Epic module,
states no derivation from an Epic client). It already provides the adaptive window, CDN
rotation, retries with back-off, 429 and stall cooldowns the spec asks for. If its lineage is
ever in doubt, it is the one shared dependency to replace.
5. **Out-of-package Epic code** [14]: `EpicCloud` and `CloudSavePaths.epic` were rewritten to call
the new module. `StoreLaunch`'s exchange-code handling, `EpicOptions`, `WinCompSources.epic` and
`SessionPrefs.storesEpicMode` are shared code and were left as they are.
6. **Save-path template** parsing is Kotlin (`EpicSaveTemplate`), not Rust: the prefix walk it feeds
is shared Kotlin code and its existing unit test runs on the JVM without the native library. The
Epic walk matches folder names case- and punctuation-insensitively (`MyGame` finds `My-Game`), as
that test expects.
7. **One engine** [12, 13]: the hidden `storesEpicMode` switch is not read and there is no Java
fallback; without the native library the Epic store reports itself unavailable. When the full
space plan does not fit, the engine runs in a narrow mode (one file staged at a time, no chunk
cache), which needs only the net peak of the pending files.
8. **Schedule and cache**: the cache budget is enforced by the plan (eviction of the chunk needed
furthest in the future). At run time files are admitted up to 48 downloads ahead of the
furthest dispatched one, so the cache can briefly hold a few entries more than the plan's peak.
A chunk is first written into every admitted file that uses it; it touches the cache only when a
not-yet-admitted file still needs it.
9. **Space probing** uses `statvfs` (available blocks × fragment size, the same figure as Android's
`StatFs.getAvailableBytes`) from Rust; a failed probe is "unknown". A scratch directory on the same
filesystem as the game is treated as "beside the game".
10. **File hashing** is done in file order while parts land; parts that arrive early are read back
from the stage file. Files without a manifest hash are not hashed.
11. **Staging folder recovery**: an *empty* staging folder without its marker (a run stopped between
creating the folder and writing the marker) is adopted and the marker written; any other missing
or foreign marker fails the run without deleting.
12. **Unsafe manifest paths** (absolute, `..`, empty segments) fail the install.
13. **Encrypted manifests** (stored-as bit 1) are refused with an explicit message.
14. **Meta section prerequisite ids** are all read (no cap at 64), so the following fields stay aligned.
15. **Store GraphQL shelves** are requested with their arguments written into the query text
(country reduced to two letters first) instead of typed GraphQL variables, so the query does not
depend on the server's variable type names.
16. **Achievements**: when an account id is stored and the player-progress query gets no answer, the
result is "unreachable" rather than a list with everything locked.
17. **Token refresh** is single-flight (one refresh at a time; a waiting caller re-reads the stored
account first), so a rotated refresh token is never spent twice. A fresh sign-in replaces the
stored account instead of merging with it.
18. **Download progress** reported to the queue never moves backwards, although samples come from
several native threads.
19. **Network window** is the speed tier's value clamped to 1–128; the per-host cap is
`max(6, ceil(window / hosts))`.
**Kept at parity (known weak spots)**
- Chunk requests do not carry the CDN's signing query; only the manifest request does; the
`cloudflare.epicgamescdn.com` CDN stays excluded [2].
- The manifest file name comes from the first manifest location and is requested from every CDN [3].
- The manifest header SHA-1 and the chunk header GUID/hash are not checked (chunk size and chunk
SHA-1 are) [4].
- Per-file flags, symlink targets and custom fields are ignored [5]; JSON manifests carry no hashes
as read, so their files are rewritten on every run [6].
- The refresh token's own expiry is not tracked; a failed refresh still returns the stored token [8].
- The cloud `hash` is compared as if it were an MD5 [10].
- `AdditionalCommandLine` is one argument, frozen at install [11].
- Shop search, an unused "wants an exchange code" helper and per-game uninstall work are not
ported; DLC stay hidden and are never installed separately; optional (non-language) install tags
are never selected; resume restarts a partially written file from zero [15–18].
- Library details are fetched one game at a time, as before.
## What needs device testing
- Sign-in through the WebView, and that an **existing** saved account (sealed `credentials.json`)
stays signed in after the update.
- Every endpoint with the DroidDeck User-Agent: library, catalog, build info, CDN downloads, store
GraphQL and promotions, cloud saves (achievements use the launcher agent, see above).
- Library sync and shelves; install, pause/resume, cancel, update and repair; a card install with
the internal scratch cache; launch with an exchange code; cloud-save up/down.
Binary file not shown.

After

Width:  |  Height:  |  Size: 251 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 256 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 644 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 614 KiB

@@ -228,3 +228,11 @@ flag for an experiment.
Device check (Thor): Alan Wake's American Nightmare with its 1280x720 Game Resolution runs on `:1`
at 1280x720 with no `--force-windows-fullscreen` in the session, 2 frame-size changes, no crash
in logcat. The Games tab and the drawer render without the switch.
## Steam picture position
The launcher's Execute Steam settings, under Display, offer Picture position: Top, Bottom, Center (default). The selection applies to the entire Steam session, including menus and games, and is loaded again on resume. No focus-based switching or in-game toggle is used. PiP and VR retain their own presentation.
Positioning keeps the selected resolution, fit scale, aspect ratio and full surface intact. It distributes outer letterboxing above or below the picture; it does not crop game-authored black bars inside the surface. A surface that already fills the panel has no vertical space to move. Use a 16:9 resolution for fixed-16:9 games when a separate controls area is desired.
The compositor publishes actual bounds for touch mapping and ignores touches starting outside the picture. The mapping harness covers top, bottom and center across tall, 16:9 and wide surfaces, including inverse input mapping and legacy half-screen mode compatibility.
+126 -16
View File
@@ -24,26 +24,112 @@ scanned (`StoreInstallRoot.roots`): internal, every card, and the Steam library'
installs an earlier build put there. `<Store>` is `GOG`, `Epic` or `Amazon`; `<title>` is the title
with unsafe characters dropped, at most 60 characters (`StoreInstallRoot.folderName`), chosen once;
a rerun (repair, update) lands on the folder whose sidecar carries the game's id, wherever it is.
An Epic install on a card keeps its in-flight chunks in `cacheDir/stores/epic/<id>/`: the
`chunkCacheDir` of both native calls (`EpicNative.run` fetches into it, `EpicNative.assemble`
writes the files from it and drops each chunk after its last use, then the folder), and of the
manager's own loops when the engine is not there; `""` keeps the cache beside the game, as an
internal install has it. The scratch folder is removed on cancel-with-delete and on uninstall.
The cache holds whole ~1 MiB chunk windows, shared with files this device does not install, so it
is often larger than the game (Metalstorm: 9.1 GB of chunks for 4.4 GB of files); the free-space
check, made after the delta pass, counts the missing chunks and the missing files on their own
volumes. A successful run removes the cache.
An Epic install on a card keeps its in-flight chunks in `cacheDir/stores/epic/<id>/`;
`""` keeps the cache beside the game, as an internal install has it. The scratch folder is
removed on cancel-with-delete and on uninstall.
Preflight resolves an existing game's folder before selecting its target root, so a resume or
repair on a card checks and remembers that volume rather than internal storage. Fresh GOG and
Amazon installs can reject insufficient catalog-size space immediately; existing installs defer
to manifest checks of the files still needing work (GOG MD5, Amazon SHA-256 where supplied).
Free-space display probes the nearest existing ancestor without creating the target folder; if
the probe cannot determine space, it reports **Free space unknown** rather than blocking an install.
`StoreInstallRoot` uses `-1` for unknown and preserves a measured `StatFs` zero as **0 B free**.
Fresh GOG/Amazon preflight and the backends' own space checks (GOG in Kotlin, Epic and Amazon in
the Rust engine) reject known zero when bytes remain. The read-only probe walks existing ancestors without creating directories; a failed
`StatFs` probe can use a positive `File.usableSpace` fallback, but that API's ambiguous zero is
unknown, not a measurement of a full disk.
Preflight failures remain failed Downloads rows with Clear and Retry. Retry reruns preflight
outside the worker lifecycle and then enqueues the real backend; it never occupies a queue slot
with a placeholder job. Failures are kept in the Downloads UI, notification and logs rather than
duplicated as transient failure toasts. Active queue persistence and ordinary backend pause/retry
are unchanged.
Epic installs run in the Rust `epic` module of `libdroiddeckstores.so` (`epic/install/`), driven by
`EpicInstaller` through `EpicNative.install`. There is one engine; the old hidden `storesEpicMode`
switch is no longer read. Without the native library the Epic store cannot install (the facade
reports "the store engine is not available"). The design, and how it was written from a
functional spec only, is in [epic-cleanroom.md](epic-cleanroom.md).
A run, in order: CDN list from the build information (`EpicApiClient.getManifestApiJson`) →
manifest from the first CDN that serves it → parse (binary or JSON) → files selected by the device
language's install tags (`EpicInstallTags`) → staging recovery → the delta pass (a selected file is
up to date when it has the manifest size and SHA-1; a file without a manifest hash is always
rewritten) → space plan → chunk cache preparation → fetch schedule → download and write → the
installed record (`StoreInstalls.complete`). Resume, update and repair are the same rerun.
- **Schedule** (`epic/install/schedule.rs`). The pending files' parts form one timeline. A chunk is
downloaded at its first use and feeds every later use in the same file directly. If it is used
again in a later file it is kept, decompressed and verified, in the chunk cache, which has a byte
budget; when keeping a chunk would exceed it, the cached chunk needed furthest in the future is
dropped and downloaded again when needed. Chunks a previous run left in the cache are reused,
soonest-needed first, as far as the budget allows.
- **Writing** (`epic/install/writer.rs`). Files are admitted strictly in order, a little ahead of
the download, and a download is dispatched only once the file of its first use is admitted, so
the number of half-written files stays small. Each admitted file is written into a unique
`epic-<pid>-<seq>-<nanos>.stage` file in `<game>/.droiddeck-epic-staging/`; the file SHA-1 is
computed in file order as parts land. A complete file is synced, size- and hash-checked, and
renamed over its destination. Right before the first rename of the run `StoreInstalls.markUpdating`
switches an installed record to `updating`; a refusal fails the run with nothing replaced.
- **Fetching** uses the shared `fetch_core` (adaptive window, CDN rotation, retries with back-off,
stall and 429 cooldowns) with the speed tier's window and decode workers. Every chunk is checked
(header, zlib stream end, exact size, SHA-1) before any byte reaches a file or the cache.
- **Space** (`epic/install/space.rs`). Free space is probed per volume (`statvfs`; unknown is never
"no space"). The plan: net peak of the pending files in order (each old copy credited at its own
swap), a cache budget of half the remaining space (at most 1 GiB, 256 MiB when unknown, 0 is
allowed), an overlap budget that limits how many bytes of files replacing existing data are
staged at once on an update (at least the largest replaced file), and a 64 MiB transient
allowance. A card install keeps its cache in `cacheDir/stores/epic/<id>/` when internal storage
can hold a useful cache and the game has no non-empty `.chunks` yet; otherwise the cache is
`<game>/.chunks`. When the full plan does not fit, the run falls back to one file at a time with
no cache (needs only the net peak); when even that does not fit the install is refused before any
chunk request, naming the storage, the need, the free space and the shortfall.
- **Progress**: the bar counts pending-file bytes written (not compressed chunk bytes), at most every
50 ms plus once per finished file. The run logs `epic: plan …` and `epic: summary mode=adaptive|narrow
files=… bytes_written=… avg_mbps=… fetches=… refetches=… peak_cache_mib=… hosts=…`.
- **Cancel / pause / failure**: the cancel flag is forwarded within 250 ms; the run stops its
requests, joins its threads, removes every unfinished stage file and `.part` cache entry, and only
then returns. Swapped files stay; unswapped destinations keep their old content; the chunk cache
stays for the next run. Success removes the cache and the staging folder (when only its marker is
left).
The staging folder is recognised by its `owner` marker (`DroidDeck Epic staging v1` + LF). Before
the delta pass the run checks that the folder is a real directory at the expected canonical path,
that the marker matches and that every other entry is a plain `.stage` file directly inside it; only
then are those orphans deleted. Anything unexpected fails the run without deleting. A manifest path
naming the staging folder, an absolute path or a `..` segment is refused. `.stage` / `.part` files
elsewhere in the game folder are never touched.
Amazon installs run in the Rust `amazon` module (`amazon/install/`), driven by `AmazonInstaller`
through `AmazonNative.install`; sign-in, the library sync and the size lookup call the same module
through `AmazonNative.call`. The design, and how it was written from a functional spec only, is in
[amazon-cleanroom.md](amazon-cleanroom.md).
An Amazon run, in order: download lookup for the entitlement (`GetGameDownload`: a CDN base URL with
a signed query, and the version id) → `manifest.proto` from that base (a 4-byte big-endian header
length, an opaque header, then an xz or LZMA-alone compressed protobuf) → parse (every file of every
package; paths refused when absolute, with a drive letter, `..`, empty segments, or naming
DroidDeck's own root files) → leftover `<file>.tmp` siblings removed → the check of files on disk (a
file is complete when it has the manifest size and SHA-256; the same test drives the space check and
the download plan) → space check (`Not enough free space: need …, only … free`; unknown free space
never blocks) → empty files created locally → every other pending file fetched from
`files/<sha256 hex>` under the base, one streamed GET each through the shared fetch core (the speed
tier's window; at least half the CPU cores verifying and writing), hashed as it arrives, written to
`<file>.tmp` and renamed over the destination after the size and hash checks → the installed record.
Before the first file is put in place the record is switched to `updating`, so an interrupted repair
is offered as "Resume install". There is no partial-file resume: a file is complete or fetched again
from its first byte. Files the manifest does not list are left alone.
## The sidecar
```json
{
"version": 1,
"store": "epic", // gog | epic | amazon
"id": "Samorost3", // the store's own id: GOG product id, Epic app name, Amazon product id
"store": "epic",
"id": "Samorost3",
"title": "Samorost 3",
"exe": "Samorost3.exe", // relative to the folder, forward slashes; what the icon is read from
"launcher": ".droiddeck-launch.bat",// optional; what the shortcut runs instead of exe
"exe": "Samorost3.exe",
"launcher": ".droiddeck-launch.bat",
"args": ["-EpicPortal", "-epicusername=\"Name\"", "..."],
"env": {"FUEL_DIR": "C:\\ProgramData\\Amazon Games Services\\Legacy"},
"installVersion": "1.4.0",
@@ -59,7 +145,18 @@ store root whose sidecar says `installing`, or that has no sidecar at all, is an
install: `AddedGames.scan` leaves it out (it is neither a game nor a Custom folder), and the Stores
card and page offer **Resume install**, which reuses that folder - and an Epic `.chunks` beside it -
instead of starting a fresh one (`StoreInstallRoot.existingFolder`). A finished install being
repaired keeps its finished sidecar. The launcher and the finished sidecar are written before the
repaired keeps its finished sidecar until Epic reaches the first verified file swap. Immediately
before that swap Epic atomically changes the record to `"state": "updating"`, preserves launch
choices and identifiers, and clears `installVersion`. Network/hash failures or cancellation before
that point leave the old installed record and files intact. A later failure can leave a mixture of
verified new files and untouched old files: replacement is atomic **per file**, not a transactional
whole-game update or rollback. The updating folder is excluded from installed scans and offered
for resume. Cancellation with deletion clears caches but retains that folder and its verified
swaps; retry preserves the updating record's metadata. If marking or swapping fails, no destructive
fallback is attempted (the conservative updating state can remain even when a swap fails).
Completion writes the installed record with the new version only after all selected files succeed.
An already registered live Steam shortcut is not revoked at each file swap; do not launch an
in-progress update. The launcher and the finished sidecar are written before the
art and the Steam registration; a failure writing them fails the download with its message.
`StoreGameSidecar.parse` refuses anything whose `exe` or `launcher` would point outside the folder.
@@ -106,6 +203,15 @@ An Epic game's launch choices are the Epic card in the Games tab's launch settin
read the same thing - and "Resolve Epic sign-in", which opens Epic's account page behind its
sign-in in Android's browser.
An Amazon game's exe and arguments come from its `fuel.json` (`Main.Command`, used when it names
an existing file; `Main.Args`, used even when it does not), else from a score over every `.exe`
below the folder (Unreal shipping binaries and `Binaries/Win64` first, crash handlers, setups,
launchers and tiny stubs last; the rules see paths relative to the install folder), else the shared
picker. Its launcher sets five FuelPump variables frozen at install time: `FUEL_DIR`,
`AMAZON_GAMES_SDK_PATH`, `AMAZON_GAMES_FUEL_ENTITLEMENT_ID`, `AMAZON_GAMES_FUEL_PRODUCT_SKU` and
`AMAZON_GAMES_FUEL_DISPLAY_NAME` (the account name, `Player` without one). No Amazon Games SDK files
are deployed into the prefix and `fuel.json` `PostInstall` steps are not run.
A game's web links reach Android: `droiddeck-store-launch` sets the prefix's
`HKCU\Software\Wine\WineBrowser` `Browsers` to `/usr/local/bin/droiddeck-open-url`, which is also
`xdg-open` first on the game's PATH, and hands http(s) addresses to the app, which opens them in
@@ -146,7 +252,9 @@ the prefix's user folder appears, within a minute. Every path logs
has no cloud saves.
- **The services:** GOG `cloudstorage.gog.com/v1/<user>/<client>` with a token issued to the game's
own client (the client secret is kept at install; the Galaxy token is the fallback); Epic's
savesync data storage with signed read and write links.
savesync data storage with signed read and write links (`EpicCloud` → `EpicSaveSync` → the Rust
`epic/savesync.rs`; the template's root token and `{EpicId}` / `{AppName}` are read by
`EpicSaveTemplate`).
- **Which launches:** `droiddeck-store-launch` recognises a store game by the launcher .bat Steam runs
or, for a game without one (most GOG games), by its exe - the folders above it are searched for
the sidecar.
@@ -172,7 +280,9 @@ keeps the files; every store's install skips complete, verified files on the rer
rerun. Cancel deletes the folder. `StoreDownloadService` holds a foreground notification while
anything runs. The native engine (`libdroiddeckstores.so`, `StoresNative`, `GogNative`, `EpicNative`,
`AmazonNative`; contract in `app/src/main/rust/stores/JNI.md`) is loaded on first use; without it
each manager runs its Java fetch loop.
the GOG manager runs its Java fetch loop, and the Epic and Amazon stores (all of whose service calls
and installs run in the Rust `epic` and `amazon` modules) are unavailable: sign-in, sync and install
report "the store engine is not available".
## Settings
+126
View File
@@ -0,0 +1,126 @@
# Quest presentation candidate Test 2 — 2026-10-13
Base: `main` at `a394dfd31b2102e20dd99c6f51b4873bbdedab05`.
Reference APK: `DroidDeck-PR669-A6xx-Test2(1).apk`, SHA-256
`95ffb5ea6ae61d6a92c4ce9ad46f329d77a0f113ebbaabc6da30d6c8bd951154`.
Its embedded source revision is `d3f3439bbc45ca67de86d0093356a449c2c74600`.
## Evidence and scope
Reported symptoms: Desktop shows vertical corruption; Steam has green marks in
its black borders; starting Desktop first also corrupts subsequent Steam, and
closing Steam can expose corruption when returning to the menu. The supplied
modified PR669 APK reportedly avoids the transition problem.
Source inspection confirms that the compositor outlives sessions. The old
Quest workaround enables only `hdr.steam`, and the initial HDR-gated layer
selection happens only at compositor startup. Whole desktops and black borders
can still use the Android Vulkan swapchain even when a fullscreen game uses a
SurfaceControl layer. This is consistent with the reported symptoms, but is not
an on-device reproduction or proof of the exact driver defect.
The supplied APK has the same Steam-only preference initialization and the
same bundled Quest 3 Turnip binary as main (SHA-256
`af0d6bb38756eace17b43311c5c61a7ef3dc6e83d5cb8a63577d6a1d10c0aed0`).
It additionally supports a Quest 2 driver. Therefore the APK comparison does
not establish a new Quest 3 driver regression. Device, installed driver,
persistent preferences and session logs still matter.
## Test 1 startup regression and Test 2 correction
The Test 1 user confirmed a Quest 3 and a black window after runtime setup.
The supplied state report identifies `0.4.0-questdisplay-test1`, runtime `r9`
installed, an active guest, `installing=null`, no recorded failure, and saved
session artifacts. The session was suspended at capture. Suspension alone does
not establish the cause of the original black window. The retained main log
starts after the test window was closed, so the startup diagnostics are absent.
Source review found a Test 1 bug: `vkp_render` unconditionally signaled the first
frame after successfully showing the black backdrop, even with no client draws.
The Android listener then hid the loading UI and marked Steam's window as shown.
This also happened when the content-layer operation returned a successful no-op
(no visible geometry or no available pool slot). Consequently `firstFrame=true`
in Test 1 is not reliable evidence that Steam had displayed a frame.
Test 2 removes the backdrop notification. The existing content-layer presenter
owns the notification after submitting client content. A host regression test
compiles the production `vkp_render` entrypoint with controlled layer outcomes;
it failed on Test 1's empty scene and passes with this change. It also covers
successful no-ops, content presentation, errors and the existing non-Quest,
frame-generation and Cardboard routes. All seven focused host tests pass.
On 2026-10-13, the user tested Test 2 on Quest 3 and confirmed that it was
functioning as intended. This is a user-reported hardware result; a separate
pass/fail record for each checklist item below was not supplied. Broader headset,
game, colour and performance coverage remains outstanding. The user's separate
Quest 2 success report concerns the Adreno 6xx compatibility PR, not this build.
## Candidate change
- Recognize Quest 2/3/3S for presentation independently of HDR and session order.
This does not install an A6xx driver or expand main's Quest 2 driver support.
- Enable the layer protocol before the first client connects.
- Compose complete SDR scenes into the existing GPU-rendered gralloc layer,
including Desktop's multiple windows. Keep the existing path for a fullscreen
AHB that cannot be imported into the compositor.
- Present the black backdrop as an opaque SurfaceControl layer, initialized
once through a CPU-mapped 16-by-16 buffer. Game/desktop rendering stays on
the GPU. The backdrop does not use a Turnip Android swapchain.
- Use actual native-window dimensions for layer geometry without creating a
Vulkan swapchain solely for sizing.
- Retire the backdrop on detach/rebind and hide it before a real swapchain
frame. Reject a black buffer whose CPU lock/unlock failed.
Other devices retain their normal presentation paths. Frame generation and
Cardboard still use the original swapchain path and are outside this test's
coverage; leave them off for the first test. HDR negotiation itself is unchanged.
## Validation
The full ARM64 native compositor, including the existing frame-generation
engines, is compiled from this checkout with Android NDK r27d, API 26 and 16 KB
ELF alignment. Host tests exercise the actual backdrop implementation with
mock Android APIs: initialized pixels and padded rows, immutable reuse,
resize, hide/show, retirement/recreation, absent windows, allocation/lock/
unlock/transaction failure recovery, and the Quest device gate. These checks
cannot validate Horizon's compositor, colours, latency or graphics output.
Run the focused host tests (LeakSanitizer may need `ASAN_OPTIONS=detect_leaks=0`
when the test runner itself operates under ptrace):
```sh
python3 -m unittest tools.tests.test_quest_presentation tools.tests.test_quest_kgsl -v
```
The test APK uses the verified official CI APK for this exact base commit,
with only `lib/arm64-v8a/libdroiddeckwayland.so` rebuilt and replaced, an added
`assets/quest-presentation-test.json` provenance record, and a new APK signature.
DEX, other native libraries and runtime assets stay unchanged. The manifest is
repackaged with the repository's variant helper as `com.droiddeck.questdisplaytest`
so it can install beside the normal app and the supplied APK, whose signing key
is different. Provider authorities and the signature permission are renamed too.
It uses separate app data and needs its own initial setup. It is not a complete
Gradle rebuild. The displayed version is `0.4.0-questdisplay-test2`. It is signed
using the repository's public AOSP test key. The launcher label remains DroidDeck;
check the version in app info to distinguish the test installation.
Test 2 retains Test 1's package, version code and signing certificate. Install it
over Test 1 without uninstalling or clearing data; its installed runtime and
session logs are retained. The original main application remains separate.
## Headset test
Fully close DroidDeck before starting. Keep the same driver and resolution
settings that produced the problem; turn off frame generation and Cardboard.
1. Cold launch Desktop. Check the desktop, windows and black borders.
2. Switch Desktop to Steam without restarting the app.
3. Close Steam and return to the DroidDeck menu.
4. Fully close the app, then launch Steam first; inspect the top/bottom borders.
5. Switch to Desktop and repeat both transitions several times.
6. Resize the Quest panel and suspend/resume the app once.
Record the headset model and whether each step is fixed. If it fails, export
that session's logs, including `wayland.log` and device information. Look for
`Quest presentation: display layers for Steam and desktop` to confirm this
renderer was loaded. Test 2's reported Quest 3 result is recorded above.
+28 -2
View File
@@ -1,16 +1,42 @@
# Experimental Quest 3/3S support
# Experimental Quest 2/3/3S support
Quest 3/3S runs DroidDeck as a 2D panel. This does not add immersive VR or
OpenXR support. Quest 2 is outside the bundled Adreno 7xx driver path.
OpenXR support. Quest 2 has a separate experimental Adreno 6xx driver path.
Quest 2 selects `turnip26.3.0-quest2`, a pinned Banners-Turnip A6xx/A7xx build
with the same GPUOBJ adapter. It does not select the Quest 3 A7xx binary.
The first Quest 2 launch applies manual driver selection and the SurfaceControl
workaround, even if `questDefaultsV1` exists from an earlier install. Later user
choices are retained. The separate `turnip26.3.0-a6xx` bundle provides a plain
Adreno 6xx offline fallback for other devices; their driver Auto behavior remains.
Neither family-wide hardware coverage nor Quest 2 operation has been verified.
The A6xx input URL and SHA-256 are pinned in `tools/quest/build-driver.py`.
Both A6xx bundles are prepared by the existing local/CI wrapper build step and
covered by runtime-input attestation. Quest 3/3S retains its original driver.
Early installation and compositor breadcrumbs are written to `driver-setup.txt`
in private files and, when available, the app's external files directory. They
do not require a Steam session. The existing Quest Java crash file now also
applies to Quest 2; native crashes still require Android logcat.
Install the standard DroidDeck APK on Quest 3/3S. Device detection on the
first launch selects manual drivers, the bundled
`turnip25.1.0-quest1` Android driver and the default Linux driver. It enables
`hdr.steam` to use the existing SurfaceControl presentation workaround from
[the Quest report](https://github.com/Droid-Deck/DroidDeck/issues/245).
Presentation also has a Quest-specific layer path for complete SDR scenes and
the black backdrop, independent of this HDR preference; see
[the presentation candidate and headset test](quest-presentation-test.md).
These defaults apply once; subsequent user changes are retained. Colour
accuracy and headset performance still need testing.
Selecting driver Auto also uses the bundled Quest display driver and runtime
default, without downloading a generic Adreno driver pair. Manual selections
remain available and are not replaced on startup. Android's Auto-by-GPU fallback
uses the Quest bundle too; the external `Download/droiddeck-driver` override
still takes precedence. Fully close and restart DroidDeck after changing the
display driver, since the compositor loads it once per app process.
Both the Android driver wrapper and the Linux session preload use
`tools/quest/kgsl_compat.c`. Successful legacy allocation/free calls are
unchanged. Only `EACCES`/`EPERM` failures retry through `GPUOBJ_ALLOC`,