mirror of
https://github.com/Droid-Deck/DroidDeck.git
synced 2026-11-22 06:15:58 +00:00
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:
commit
75612da44b
1016 files changed
+95104
-48259
No files matched your search
+35
-26
@@ -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
|
||||
|
||||
@@ -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`.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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`,
|
||||
|
||||
Reference in new issue
Block a user