chore: merge main into feat/lse-emu

This commit is contained in:
Kurt Himebauch committed 2026-11-15 13:30:28 -05:00
commit 73104aff03
667 files changed
+75245 -4143

No files matched your search

+19 -1
View File
@@ -28,7 +28,7 @@ Player controls and observations work over authorized ADB on any build: `state`,
`resume`, `wait`, `launch`, `quit`, `focus`, `input`, `ui`, `logs`, `screenshot`, `record`, `pacing`,
`thermal`, `displays`, `wake`, `glasses` (except `glasses raw`), and `access`.
**Setup > Diagnostics > Debugging tools** is off by default in every build, including debug builds.
**Setup > Developer > Debugging tools** is off by default in every build, including debug builds.
It enables `run`, `guest`, `cdp`, all `env` operations, `override`, `prefs`, and `glasses raw`. 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
@@ -122,6 +122,10 @@ tools/droiddeckctl input swipe 100 600 100 100 --duration 400
tools/droiddeckctl input pad a
tools/droiddeckctl input stick left 0 -1 --hold 500
tools/droiddeckctl input trigger right 1.0
tools/droiddeckctl input pen tap 0.5 0.5 --pressure 0.7
tools/droiddeckctl input pen stroke 0.2 0.5 0.8 0.5 --pressure 0.1:0.9 --tilt-x=-30:30
tools/droiddeckctl input pen hover 0.3 0.5 --to 0.7 0.5 --duration 600
tools/droiddeckctl input pen button primary 0.5 0.5
tools/droiddeckctl ui dump
tools/droiddeckctl ui click rail-steam
@@ -196,6 +200,20 @@ virtual pad, the same one the on-screen controls drive, so games that ignore tou
`launch`, `quit` and `cdp` need a Steam session; `focus` and `wait focused` need gamescope (every
mode except the desktop).
`input pen` does not go through the app. It registers a virtual pen with `adb shell uinput -`, so
Android's own input reader makes the stylus events, as for a built-in pen, and it works on whatever
is on screen, without a session or Setup > Developer > Debugging tools. Positions are fractions of
the screen as shown; `dumpsys input` gives the frame, rotation and size of the display Android maps
internal touchscreens to. `hover` comes near and glides to `--to`; `tap`, `stroke` and `button`
hover for `--hover-ms` (80) before and after the touch or the button press. Each takes
`--tool pen|eraser`, `--tilt-x` and `--tilt-y` in degrees, `--distance` in device units (0 to 255)
and `--rate` (120 samples a second); `--pressure` and tilt take `FROM:TO` ranges, written
`--tilt-x=-30:30` when they start negative. A gesture lasts at most 30 s. `UINPUT_UNAVAILABLE`
means the shell has no `uinput` or cannot write `/dev/uinput`, `NO_VIEWPORT` that there is no
internal display or it is off, and `UINPUT_FAILED` that `uinput` stopped early; all three exit 3.
It needs Android 14 QPR2 or later: the `uinput` of Android 12 to 14 QPR1 takes only numeric codes
and the USB or Bluetooth bus, so there the pen ends with `UINPUT_FAILED`.
## State (schema 2)
`state` returns `schema`, `build`, `appVersion`, `runtime {installed, version}`,
+3 -1
View File
@@ -4,7 +4,9 @@ Settings → Boot movie has four tabs.
- **Installed**: "Browse" lists every movie Steam can play: DroidDeck's two, plus every `.webm` in Steam's
`config/uioverrides/movies` folder (imported, installed from SteamDeckRepo, or put there by Steam). The list is re-read
every two seconds, so a movie picked or removed inside Steam shows up, and a movie picked inside Steam becomes the choice.
every two seconds, so a movie picked or removed inside Steam shows up, and a movie picked inside Steam becomes the choice. The Shuffle switch is Steam's own `Shuffle` setting (`startup_movie_shuffle` in
Steam's client settings, `Shuffle` next to `MovieID` and `LocalPath`): it is written at the next session start, a change made in Steam is
taken over, and with it off the selected movie plays as before.
- **Import**: the same importer as before (copy, remux or on-device transcode to VP8/Opus). The result is written into
Steam's movies folder, so Steam lists it as well.
- **SteamDeckRepo**: browses `https://steamdeckrepo.com/api/posts` (`sort`, `device`, `search`, `page`; 12 posts a page).
+16 -3
View File
@@ -104,7 +104,7 @@ Run the batch/reference and work-budget regressions with
## Game debug logs
Under **Setup > Diagnostics**, enable **Session logs** and **Game debug logs**
Under **Setup > Developer**, enable **Session logs** and **Game debug logs**
before reproducing a Windows game problem. Game debug logs is off by default and
is available when Session logs is enabled. It applies to the next game launch through DroidDeck's
Valve or third-party Proton wrapper, including added games and store shortcuts.
@@ -142,7 +142,7 @@ that diagnostics were skipped instead of writing uncollected files elsewhere.
## Enhanced diagnostics
Use **Setup > Diagnostics > Enhanced diagnostics for next session** when normal
Use **Setup > Developer > Enhanced diagnostics for next session** when normal
session logs are not enough. The setting is one-shot: DroidDeck creates and
retains the next session's log directory, records the diagnostic profile, then
turns the setting off. It also enables the existing game diagnostic environment
@@ -254,6 +254,14 @@ The former feature-level rules for Caravan SandWitch, RoboCop: Rogue City,
ReSkate and Cyberpunk 2077 compensated for the global `12_2` override and are
removed. Stellar Blade also uses automatic detection. The separate Deep Rock
Galactic GDK ray-tracing opt-out and Mali bridge capability cap remain.
"Skip GL error checks" (under "Client interface") sets `MESA_NO_ERROR=1` for the client
interface and Chromium apps only. Games keep Mesa's GL error checks: with
`MESA_NO_ERROR`, an invalid call such as `glBufferData` with no buffer bound reads
a NULL buffer object instead of returning `GL_INVALID_OPERATION`, and the game's
render thread stops. A game profile entry, or `MESA_NO_ERROR` in the session's own
environment, still applies to games.
Other picker suggestions are editable starting values and are enabled only when
added and saved. Older or
custom components can support a different set of options. Android Wine wrapper,
@@ -275,7 +283,12 @@ DroidDeck instead publishes an atomic JSON snapshot at
`/root/.config/droiddeck/game-environment.json`. Both its Valve ARM64 Proton
wrapper and adopted third-party Proton wrappers execute `droiddeck-game-env`,
which reads that snapshot for each real game launch and uses `execvpe` to start
Proton. Probe prefix `compatdata/0` and non-launch verbs are unchanged. Malformed
Proton. Probe prefix `compatdata/0` and non-launch verbs are unchanged. A game launch
adds `tabtip.exe=d` to `WINEDLLOVERRIDES` unless the launch has `SteamDeck=1`
or the overrides already set `tabtip.exe` (also as `*tabtip.exe` or
`tabtip.exe.dll`): Proton's tabtip only opens Steam's
keyboard with `SteamDeck=1`, but it always runs UI Automation queries inside the
focused game, which crash games that answer them (Godot 4.5 AccessKit). Malformed
configuration falls back to the inherited environment without evaluating its
contents. Both component and environment selection normalize signed non-Steam
prefix IDs to unsigned IDs.
+30 -19
View File
@@ -9,8 +9,10 @@ Every five seconds the monitor reads `MemAvailable`, swap headroom and memory PS
headroom means less than one fifth of total RAM (bounded to 512–1536 MiB), or at least 1%
`some avg10` memory stall with less than one third of RAM available. Pressure requests target
only the launcher processes already recognized by the monitor, never the game. They require
at least 128 MiB launcher RSS and enough free swap to cover its entire RSS while leaving
one fifth of swap (at least 256 MiB) free. The regular automatic client request uses the
at least 128 MiB launcher RSS and enough free swap to cover its anonymous RSS while leaving
one fifth of swap (at least 256 MiB) free. File-backed resident pages do not consume this
budget: the page-out helper targets private anonymous mappings. If `RssAnon` is absent from a
process's status, its full RSS is used instead. The regular automatic client request uses the
same swap guard. An explicit session RAM cap retains its existing behavior.
Pressure requests are at least 30 seconds apart. Reclaiming less than 16 MiB doubles the
@@ -41,27 +43,35 @@ reduced aggregate launcher RSS only from 263 to 255 MiB and backed off. Thus lau
does not resolve this load failure, and this run did not exhaust swap. The unevictable/shmem
growth needs allocation attribution before treating it as a driver or GPU-memory diagnosis.
## Low-RAM devices: compressing idle game memory
## Pressure reclaim: compressing idle game memory
On devices with at most 13 GiB `MemTotal` (every 12 GB phone and handheld and below), the
monitor also compresses the game session itself when memory runs out. The trigger is absolute
headroom, not a percentage: Android's `lmkd` killed a session on a 7.5 GiB device with
The monitor also compresses the game session itself when observed pressure approaches the
system kill boundary. There is no RAM-size gate. The trigger is absolute real headroom, not a
percentage: Android's `lmkd` killed a session on a 7.5 GiB device with
490 MiB still available, so a 95% used threshold (about 400 MiB left on 8 GB) is already past the
kill. A world load added 1 GiB of GPU memory in about ten seconds, and compressing 1.4 GiB took
2.6 seconds, so the request has to leave room for both.
The session request runs when available memory falls below a quarter of RAM (bounded to
768–2560 MiB, 1.85 GiB on an 8 GB device), or below one and a half times that with at least 1%
`some avg10` memory stall. One request pages out every session process that loaded
`libblsession.so`: the game, Wine and its services, plus the launcher processes unless their
compression is turned off, under a single wait. It runs before the launcher-only check, which
can wait up to 12 seconds for acknowledgements. While a game runs and available memory is under
twice that level, memory is read every second instead of every five. Requests are at least 30 seconds apart and need the same swap reserve as launcher
requests. When the session has read back more than half of what the previous request compressed,
that memory is in use: the request is skipped and the wait doubles, up to five minutes. A
request whose memory stayed compressed resets it to 30 seconds. Below half the headroom the
wait is ignored and only the 30-second spacing applies. The state resets when the game exits. Devices above 13 GiB keep the
launcher-only behaviour.
Performance > Compress idle game memory turns this off (`BL_ZRAM_IDLE=0`); launcher compression
and the RAM cap are unaffected.
The session request runs when real headroom falls below a quarter of RAM (bounded to
768–2560 MiB), or below one and a half times that with at least 1% `some` or `full avg10`
memory stall. Real headroom subtracts positive growth in KGSL allocation, `Unevictable`, and
`Shmem` from `MemAvailable`; a rapid fall also qualifies near twice the headroom. The monitor
may first request page-out of idle Steam and hidden launchers, subject to the Performance
setting and client reclaim limits. When both qualify, both requests are sent before waiting
for either to complete, so a slow launcher acknowledgement does not delay the game request. Until the client
request finishes, its anonymous RSS remains reserved from the session's swap budget. Completion
and backoff are measured against the processes that received each request, even if a later scan
finds different processes. The session request targets processes that loaded
`libblsession.so`: the game, Wine and its services, and excludes Steam and hidden launchers.
Requests are at least 30 seconds apart and need the same
swap reserve as launcher requests. When the session has read back more than half of what the
previous request compressed, that memory is in use: the request is skipped and the wait doubles,
up to five minutes. A request whose memory stayed compressed resets it to 30 seconds. Below half
the headroom the wait is ignored and only the 30-second spacing applies. The state resets when
the game exits.
Measured on a Retroid Pocket Duo (7.5 GiB, kernel 6.6, 6 GiB lzo-rle zram plus a 4 GiB swap file)
entering the world in World of Warcraft: Forever, one run each:
@@ -91,7 +101,8 @@ A second run on that build showed the trigger arriving too late: character selec
there. During the load, available memory crossed the headroom 9 seconds after Enter World, but the
launcher check ran first and waited 12 seconds for acknowledgements; the game request started at
21 seconds, moved about 200 MiB, and `lmkd` ended the session at 30 seconds. The quarter-of-RAM
level and the game-first single request address both.
level starts reclaim earlier. Sending both requests before waiting removes the launcher
acknowledgement delay; it does not guarantee that reclaim can keep up with every loading peak.
Without root an app cannot write its memory cgroup's `memory.reclaim` (owned by `system`),
`process_madvise` on another process returns `EPERM`, `PAGEMAP_SCAN` is absent before Linux 6.7,
+8 -2
View File
@@ -122,11 +122,16 @@ What it does, per feature:
- The source must be memory the application has mapped; DXVK's staging memory is.
- Decoded texels go through the layer's own staging buffers, recycled when the command buffer is reset.
- Copies from a BC image into a buffer, and between BC and uncompressed images, are skipped with a warning.
- `dualSrcBlend`: reports maxFragmentDualSrcAttachments 1. DXVK 2.x and 3.x require it for D3D11.
- Fragment outputs with `Index 1` become Private, in shader modules and in inline stage code.
- SRC1 blend factors become source alpha: `SRC1_COLOR` and `SRC1_ALPHA` → `SRC_ALPHA`, their `ONE_MINUS_` forms → `ONE_MINUS_SRC_ALPHA`.
- Pipelines and `vkCmdSetColorBlendEquationEXT` both.
- Why alpha: output 0's color is the paint, its alpha is the usual coverage. Per-channel coverage collapses to one value; blending stays plain alpha blending, not tinted by the paint.
Files:
- `layer.c`: loader plumbing, feature and limit reporting, device creation, the hook table.
- `pipeline.c`: pipelines, shader modules, viewports.
- `spirv.c`: the SPIR-V rewriter for clip and cull distances.
- `spirv.c`: the SPIR-V rewriter for clip and cull distances and the second blend source.
- `bc.c`: BC formats, images and uploads.
- `VkLayer_droiddeck_mali_compat.json`: implicit layer manifest.
@@ -142,7 +147,8 @@ How it ships:
- Guest paths: `usr/local/lib/droiddeck-mali/` and `usr/local/share/vulkan/implicit_layer.d/`.
Not done yet:
- Unit tests for the SPIR-V rewriter. It is untested beyond DXVK's shaders, and unknown whether Silksong's shaders used clip distances at all.
- Unit tests for the clip and cull distance rewriter. It is untested beyond DXVK's shaders, and unknown whether Silksong's shaders used clip distances at all.
- The dual-source rewrite has them: `tools/tests/test_mali_compat_layer.py`.
- Performance: BC decoding on the CPU makes loads slow. A compute-shader decoder would be the next step.
## Changes on the branch
+91
View File
@@ -0,0 +1,91 @@
# Pen input
A pen on the phone's screen, or an external drawing tablet, drives the session's pointer like a mouse: hover moves
the pointer, the tip holds the left button and the side button right-clicks. Fingers keep their touch mode.
The settings are a "Pen" group after the touch settings, in the Steam and Desktop sheets' **Controls** tab and on
the session drawer's **Controller** page. The group is shown once the phone has a stylus device or a pen event was
seen; the first of either sets `penSeen`, which a settings reset keeps. Before Android 14 every touchscreen whose
driver reports a tool type has the stylus source, pen or not, so there a touchscreen counts only with its first pen
event.
## Modes
`pen`: Mouse (default) or Touch.
| | Mouse | Touch |
|---|---|---|
| Hover | moves the pointer and the cursor | ignored |
| Tip | holds the left button | a finger in the current touch mode |
| Side button | as the Side button setting says | ignored; a Bluetooth pen key is an ordinary key |
- With the picture on the glasses, or while a program in gamescope holds a pointer lock, Mouse drives the touchpad
as a finger does: a tap clicks and a drag moves the pointer relatively.
- App UI on top (the drawer, achievements, input settings, picture in picture) takes the pen as Android input, as
it takes a mouse.
- The Touch column is for a pen on the phone's screen. In Touch an external tablet stays on the mouse path, so its
hover moves the pointer. The stylus rules under Android capture apply in both modes.
- A touch mode change ends the pen whatever its route, so it cannot leave a pen click held
([#318](https://github.com/Droid-Deck/DroidDeck/issues/318)).
## Side button
`penButton`: Right click (default), Middle click or Off. It applies to the pen's first barrel button. A second
barrel button, where a pen has one, sends the other click: middle when the setting is Right click, right otherwise.
Off sends nothing. The row is hidden in Touch.
Some pens send their button as a key from a separate Bluetooth keyboard; the OPPO AI Pen sends `KEYCODE_F21`. Such a
key is the side button when its device is external, keyboard-only and not alphabetic, and has a word starting with
"pen" or "stylus" in its name. In Mouse the pen always takes it, so neither the program nor the key bindings see
it, and it acts only while the pen is near: a key held when the pen comes back presses the button. Pause, focus
loss, pointer-capture loss and removing its device forget it. In Touch it is an ordinary key.
## Android capture
- Pens are found by tool type (stylus or eraser), or by `SOURCE_STYLUS` when the tool type is unknown. External
tablets report `SOURCE_MOUSE | SOURCE_STYLUS`, so the source alone is not enough. Events that mix a finger and a
pen are split, and the finger keeps its route.
- Contact is taken at the top of `SessionActivity.onTouchEvent`, after the Compose UI and the on-screen controls
declined it, so the pen presses on-screen buttons like a finger. Hover is taken in `dispatchGenericMotionEvent`
before the mouse branch. The lower-screen game takes both.
- With Low latency mode on (the default) the window asks for unbuffered pointer dispatch, so pen samples are not
batched per frame. Every historical sample is forwarded in order, and `pointerSubset` keeps the history when it
splits an event.
- `PenStream` keeps proximity, tip and buttons. A `HOVER_EXIT` followed within 50 ms by a hover or a `DOWN` does not
leave proximity: Android splits a landing into an exit and a down with the same time, and a digitizer can flicker
out and in at the top of its hover range. A hover that sends no sample for 2 s leaves proximity.
- Stylus devices are not hardware mice, so a drawing tablet does not turn on pointer capture.
- On the desktop a hardware mouse makes KWin grab the pointer. A pen that comes near releases the grab, so it
moves KWin's pointer, and the mouse takes the grab back when it moves after the pen has left.
- Where the session hides the mouse pointer it also hides Android's stylus hover icon.
## What ends the pen
Everything that cancels touches: touch mode, touch route and pen setting changes, app UI opening, configuration
changes, surface resize, the game moving between screens, picture in picture, pause, focus loss, pointer-capture
loss and the activity's end. So do a change of the pen's own route and the removal of its device. `UP` with
`FLAG_CANCELED` and `ACTION_CANCEL` end it at once instead of lifting into hover. Ending the pen releases every
button and leaves proximity; `wl_pointer` has no cancel, so on the pointer a cancelled tap still clicks.
## Compositor
Each sample is one input record, type 13: the flags (in proximity, tip, right, middle) and the position in input
space as 24.8 fixed point. A record is the pen's whole state, so the next record makes good any lost one.
`deliver_pen` emulates the pointer, as the touch `pointer_fallback` does: hover is motion, the tip is `BTN_LEFT`,
the side button `BTN_RIGHT` or `BTN_MIDDLE`, and a record without the in-proximity bit releases every button. A
button pressed or released mid-stroke keeps the implicit grab on the window the stroke started in. The
relative-motion origin is reset when the pen comes and goes, so its jump never reaches a program as relative
motion. Under a program's pointer lock only the buttons pass, which also covers the time before the app sees the
lock.
The app logs `pen route <old> -> <new> (mode=<mode>)` and the compositor `[pen] <client> gets the pen as the
pointer`.
## Limits
- A hardware eraser end clicks like the tip.
- The pen and a mouse share the pointer's buttons, so a release from one ends a press of the other, as with the
touch fallback.
- Some systems keep the pen's button for themselves, such as Samsung's Air actions. ColorOS opens its stylus
palette for the OPPO AI Pen's key unless that action is turned off in the system's stylus settings.
+193
View File
@@ -0,0 +1,193 @@
# Android's child-process limit and the guest session
Since Android 12 the platform counts the processes an app forks as "phantom processes" and
kills them under pressure. A Wine, FEX or Steam session forks dozens of them, so this limit
decides whether a session survives. This note records how the platform counts, what it kills,
why the guest cannot leave the count, and what DroidDeck changes on the device.
## What the platform counts
Discovery is a cgroup scan, not a parent-child relation. For every app process the platform
knows, it reads the cgroup member list of that process and takes every pid that is not a known
app process as a phantom of it:
- `frameworks/base/services/core/java/com/android/server/am/PhantomProcessList.java:117-122`
holds the two cgroup roots (`/acct/uid_` for cgroup v1, `/sys/fs/cgroup/uid_` for v2) and
the `cgroup.procs` file name.
- `PhantomProcessList.java:136-208` scans every app process; `:220-222` builds the path
`/…/uid_<uid>/pid_<appPid>/cgroup.procs`; `:238-275` turns a pid that is not a known app
process into a phantom of that app process.
- The mechanism is the same in Android 12.0, 12.1, 13, 14, 15, 16 and in `main`. Only the
path lookup moved to a native helper in 16 and `main`
(`PhantomProcessList.java:205`).
DroidDeck's guest is forked by the main app process: `SessionService` starts it with
`HostProcess.start` (`app/src/main/java/com/droiddeck/launcher/session/SessionService.kt:779`),
and both `SessionService` and `SessionActivity` run in the main process
(`app/src/main/AndroidManifest.xml:284-293`, `:326-329`). Every guest process is therefore a
phantom of the main app process.
## What the platform kills
1. Count trim. When the number of phantom processes in the system passes
`MAX_PHANTOM_PROCESSES` (32 by default, `ActivityManagerConstants.java:192`), the surplus
is killed, starting with the phantoms whose parent app has the least importance
(`PhantomProcessList.java:423-466`).
2. Excessive CPU group kill. Every five minutes the platform measures each app's CPU use. For
an app whose process state is HOME or less important (backgrounded), a phantom process that
used more than its threshold (25, 25, 10 or 2 percent) is killed together with its phantom
siblings **and the app process itself**
(`ActivityManagerService.java:16114-16152`, `PhantomProcessList.java:496-515`). A
foreground DroidDeck is exempt; a backgrounded one is not.
The second path is the one that ends a session without an error message in the guest log: the
app process dies with it.
## The gate, and how the versions differ
Both paths are behind the feature flag `settings_enable_monitor_phantom_procs`, whose default
is on. The flag is read from `Settings.Global` first
(`frameworks/base/core/java/android/util/FeatureFlagUtils.java:68-70`, `:272-283`). When it is
off, the trim returns early (`PhantomProcessList.java:423-427`) and the phantom CPU check is
skipped (`ActivityManagerService.java:16117-16118`, `:16144-16148`). From 12L on it also stops
the periodic cgroup scan that discovers phantom processes (`AppProfiler.java:1788-1829` at
`android-12.1.0_r1`).
| Android | flag `settings_enable_monitor_phantom_procs` | count limit | CPU group kill |
| --- | --- | --- | --- |
| 12.0 (SDK 31) | does not exist | DeviceConfig `activity_manager/max_phantom_processes`, default 32 | not gated |
| 12L (SDK 32) | exists | flag | flag |
| 13 and later (SDK 33+) | exists | flag | flag |
The flag was added in 12.1. On 12.0 the count limit comes from DeviceConfig
(`ActivityManagerConstants.java:1202-1206` in 12.0) and the CPU group kill has no gate at all
(`ActivityManagerService.java:14237-14271` in 12.0).
## Why the guest cannot leave the count
- **Reparenting does not help.** A double fork, `setsid()` or an orphaning parent changes the
parent and the session, not the cgroup. Cgroup membership is inherited at fork and only a
write into another cgroup's `cgroup.procs` changes it, so the platform still finds the pid
in the app process's cgroup and still counts it. On cgroup v2 the uid group cannot take
processes while it has the per-process groups as children, so there is no unscanned group to
move into.
- **A separate `:process` service only moves the count.** The scan covers every app process the
platform knows, so the guest tree started from another service of the same app is counted
against that service. The manifest already has such services
(`app/src/main/AndroidManifest.xml:78`, `:244`, `:255`), and the guest tree is one coupled
userspace whose graphics, input and session state would not survive the split.
- **The platform's own blind spot is out of reach.** Processes forked from an app zygote are
skipped by the scan (`PhantomProcessList.java:153-155`), but `android.os.AppZygote` is
`@hide` (`frameworks/base/core/java/android/os/AppZygote.java:36-38`) and hidden API
enforcement keeps it away from apps.
- **Detaching would break the session.** The guest tree is deliberately kept under a reaper: the
processes that load the session library mark themselves as child subreapers, so that a
double-forked Xwayland is reparented inside the session instead of to init, where a vendor
kernel's orphan reaper would kill it (`tools/linuxfs/preload/subreaper.c:1-16`). A guest
tree that leaves the app's process tree leaves that arrangement with nothing to reap it.
## What DroidDeck changes on the device
`PhantomProcessLimit` (`app/src/main/java/com/droiddeck/launcher/core/PhantomProcessLimit.kt`)
holds the platform lever per version: the DeviceConfig count limit on SDK 31 and the flag from
SDK 32 up (`:23-37`). `WirelessAdbFix`
(`app/src/main/java/com/droiddeck/launcher/core/WirelessAdbFix.kt:219-228`) runs those shell
commands over wireless debugging when the user has no computer at hand, and the gate screen
shows the result. The names on that screen come from `strings.xml` (`phantom_title_on`
"Child-process limit is on", `phantom_instructions_fix`, `phantom_fix_toggle`).
## The remaining gap on Android 12.0
On SDK 31 the count trim is covered by the DeviceConfig write, but the backgrounded CPU group
kill is not: the flag does not exist there, and the CPU thresholds live in the global string
`activity_manager_constants` (`power_check_max_cpu_1` … `power_check_max_cpu_4`), not in
DeviceConfig. In 12.0 the DeviceConfig listener reacts to `max_phantom_processes` only
(`ActivityManagerConstants.java:654-757`), while the thresholds are parsed from
`Settings.Global activity_manager_constants` (`:852-892`). Raising them means rewriting that
global string, which changes the CPU kill thresholds for every app on the device. That is a
trade the developers have to accept; DroidDeck does not do it on its own.
## Probe to run on hardware
The mechanism above is source-verified. The probe below settles the two points a source read
cannot: what a device actually does with detached children, and whether the app uid may write
another cgroup's `cgroup.procs`. It needs a device with the guest running.
Precondition: keep `settings_enable_monitor_phantom_procs` enabled on Android 12L (SDK 32) and
later, because disabling it also stops the cgroup scan, so no snapshot would discover either batch
(`AppProfiler.java:1788-1829` at `android-12.1.0_r1`). Android 12.0 (SDK 31) has no such flag and
scans unconditionally (`AppProfiler.java:1833-1834` at `android-12.0.0_r1`). An enabled flag, and
every 12.0 device, also keeps the backgrounded CPU group kill active, which can end the guest
together with the app process (see "What the platform kills", item 2). Keep DroidDeck in the
foreground and stop CPU-intensive guest programs before the probe.
The limit counts phantom processes of every app on the device, not only the probe's, so raise it
before anything can trim. Record the current flag and limit values first. Then raise
`max_phantom_processes` well above any plausible device-wide count, and only after that enable the
flag if it was disabled, because a flag enabled under the default limit of 32 can trim existing
phantoms of every app at once. Wait for the platform to discover the existing phantoms, read the
device-wide phantom count, and check that the limit is above that count, plus both batches (80),
plus headroom for processes the guest and other apps start meanwhile; raise it again if not. With
the limit at its default, starting 80 long-lived processes can trigger the platform trim and
disrupt the guest session and processes of other apps. Restore the recorded values once the probe
processes have exited, in reverse order: the flag first, then the limit, because lowering the limit
schedules a trim that is skipped only while the flag is disabled.
Run the `sleep` loops from the app's own shell so the children run under the app uid. Run each
`dumpsys activity processes` snapshot from an authorized ADB shell, because the app uid normally
cannot read that dump. After each batch, record the child PIDs and wait long enough for the
platform to discover them before taking the snapshot.
```sh
# record the current values
adb shell settings get global settings_enable_monitor_phantom_procs
adb shell device_config get activity_manager max_phantom_processes
# raise the limit first, then enable the flag on SDK 32 and later
adb shell device_config put activity_manager max_phantom_processes 1000
adb shell settings put global settings_enable_monitor_phantom_procs true
# after platform discovery: device-wide phantom count
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'
# from the app's own shell: attached children
for i in $(seq 1 40); do sleep 600 & echo $!; done
# from an authorized ADB shell, after platform discovery
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'
# from the app's own shell: detached children
# (the middle process exits, so the child is reparented to init)
for i in $(seq 1 40); do ( setsid sleep 600 & echo $! ) ; done
# from an authorized ADB shell, after platform discovery
adb shell 'dumpsys activity processes | grep -i -n -A 5 phantom'
# from the app's own shell
cat /proc/<appPid>/cgroup
# whether the uid may move a child out of the scanned cgroup
echo <childPid> > /sys/fs/cgroup/uid_<uid>/cgroup.procs
# from the app's own shell: end the probe processes
kill <childPids>
# restore the flag first: put the recorded value, or delete the key if it was "null"
adb shell settings put global settings_enable_monitor_phantom_procs <recordedFlag>
adb shell settings delete global settings_enable_monitor_phantom_procs
# then the limit: put the recorded value, or delete the key if it was "null"
adb shell device_config put activity_manager max_phantom_processes <recordedLimit>
adb shell device_config delete activity_manager max_phantom_processes
```
Compare the PIDs recorded for each batch with the phantom list in the snapshot taken after that
batch. Expected from the source: both batches are counted, the detached ones included, and the
cgroup write fails (no unscanned group, or no permission).
## References
- AOSP `frameworks/base`: `services/core/java/com/android/server/am/PhantomProcessList.java`,
`services/core/java/com/android/server/am/ActivityManagerService.java`,
`services/core/java/com/android/server/am/ActivityManagerConstants.java`,
`core/java/android/util/FeatureFlagUtils.java`, checked at tags android-12.0.0_r1,
android-12.1.0_r1, android-13.0.0_r1, android-14.0.0_r2, android-15.0.0_r1,
android-16.0.0_r1 and `main`.
- Pull request 1394, the OEM check of the same settings, and the issues it links, 713 and 1083.
- Termux meets the same limit on Android 12 and solves it the same way, with detection plus
the adb path (termux-app issues 4388 and 4857).
+2 -2
View File
@@ -204,7 +204,7 @@ call can be answered in-process with the 0014 design.
| syscalls | why proot traps them | can it bypass proot? |
|---|---|---|
| `openat`/`open`/`creat`, `newfstatat`/`stat`/`lstat`, `statx`, `faccessat`/`access`, `readlinkat` (exit), `mkdirat`, `unlinkat`, `renameat(2)`, `symlinkat`, `linkat`, `fchmodat`, `fchownat`, `utimensat`, `truncate`, `*xattr`, `inotify_add_watch`, `name_to_handle_at` | path translation (guest → host), plus exit fixups for `readlink` and `rename` | **Yes, through libc wrappers.** The prototype covers open, stat, statx, access, readlink, opendir and fopen; the write family is next. Raw `svc` and glibc's internal callers (ld.so, fts, realpath, nss) still go to proot. |
| `chdir`/`fchdir`, `getcwd` (exit) | proot emulates the cwd; until 0014 the kernel's cwd never moved | With 0014 the kernel's cwd follows the guest's. `getcwd` stays in proot (cheap, rare). |
| `chdir`/`fchdir`, `getcwd` (exit) | proot emulates the cwd; until 0014 the kernel's cwd never moved | With 0014 the kernel's cwd follows the guest's. With 0028 `fchdir` takes the path of the open directory from `/proc/<pid>/fd` instead of walking it again. `getcwd` stays in proot (cheap, rare). |
| `execve`/`execveat` | runs the loader, maps `PT_INTERP` inside the rootfs, shebangs, tracks `/proc/self/exe` | **No.** This is the core of what proot is for. Costs 0.4–0.8 ms per exec; the session scripts already avoid exec-heavy loops (`nap`). |
| `brk` (entry and exit) | heap emulation: programs are mapped by proot's loader, so the kernel's brk area is the loader's | No (`PR_SET_MM` needs `CAP_SYS_RESOURCE`). **Fewer calls:** `GLIBC_TUNABLES=glibc.malloc.top_pad=…` grows the heap in larger steps. |
| `bind`, `connect`, `accept(4)`, `getsockname`, `getpeername` | `sun_path` of Unix sockets | Same-path binds (runtime dir, files dir) need no translation, but the filter can't see the address. Possible fast-path candidate. |
@@ -325,7 +325,7 @@ or repeatedly hit a path the wrappers cannot resolve.
### Opt-in tracer profiling
With **Setup > Diagnostics > Debugging tools** enabled, queue profiling for one session:
With **Setup > Developer > Debugging tools** enabled, queue profiling for one session:
```sh
tools/droiddeckctl proot-profile enable --slow-us 1000
+78
View File
@@ -0,0 +1,78 @@
# Soundtracks
Steam soundtracks get their own tab under Library, a built-in music player, and an Android media session.
## Where soundtracks live
Steam installs a soundtrack to `<library>/steamapps/music/<installdir>`, next to a normal `appmanifest_<appid>.acf`. This holds for the internal Steam library and for a second library folder.
`Library.steamGames()` skips any manifest whose install directory exists only under `steamapps/music`. `Library.soundtracks()` returns exactly those entries, marked with `SteamGame.soundtrack`. While the Music tab is enabled, games and soundtracks therefore never mix in the Library tab, the launch drawer, game file sync or component preparation.
Folders added by hand (Soundtracks tab, plus button) are stored in `added-soundtracks.json` and carry a negative app id, so they cannot collide with a Steam app id.
## Turning it off
Setup > Launcher > Soundtracks. When off, the tab disappears and installed Steam soundtracks show in Library again, as they did before.
## Tracks, discs and duplicates
`Soundtrack.load()` walks the folder (four levels deep) for mp3, flac, ogg, opus, wav, m4a and aac. Tags come from `MediaMetadataRetriever` and are cached per folder in `files/soundtrack-index`, keyed by path, size and modification time.
`Soundtrack.group()` is pure and unit tested:
1. The same track in several formats collapses to one. Identity is disc and track number when both tags exist, otherwise the cleaned title. Lossless wins over lossy.
2. Disc comes from the disc tag, otherwise from the subfolder (natural order), labelled with the folder name when it is numeric (for example `3+4`). A folder with no subfolders is one disc and shows no disc headers. Tags missing on the kept copy are filled from its duplicates, since FLAC files often use tag names Android does not read.
3. Tracks sort by the number at the start of the file name, then by track tag, then by name. This matches Valve's soundtrack documentation, which says the Steam music player takes play order from file names and not from metadata. Numbers shown on screen are positions inside the disc.
4. Titles come from the tag, otherwise from the file name with the artist, album and track number removed.
## Cover art
Steam's own library cache image first, then `AlbumArtwork`, `cover`, `folder` and similar files in the soundtrack folder. When none exists, the picture embedded in the first track that has one is used, so the grid shows it without opening the album. The player page shows the embedded picture of the track that is playing and falls back to the album cover for tracks without one. The media notification and the system media panel follow the same rule: while a track plays, its embedded picture replaces the item artwork in place, which does not restart playback, unless a cover was chosen in the art changer. The SteamGridDB artwork changer applies to Steam soundtracks like any other Steam entry.
## Player page
The layout follows Steam's soundtrack page and uses the DroidDeck theme colors and shapes, so every theme works. Cover, title, artist and total length sit on the left with seek, shuffle, previous, play or pause, next, repeat and volume. The track list with disc headers sits on the right. Portrait stacks the two. The action buttons (game files, shortcut, edit art, uninstall) use the same wide pill style as Steam's See More button.
Controller: d-pad moves between buttons and rows, A confirms, B goes back, the sliders respond to left and right.
Shortcuts use `droiddeck://soundtrack/<appid>` and open the soundtrack page.
## Playback and Android media controls
`SoundtrackService` is a media3 `MediaSessionService` with an `ExoPlayer`. It runs as a foreground service of type `mediaPlayback`, so playback keeps going when DroidDeck is closed and the notification and lock screen controls show the cover, title and artist. `SoundtrackController` connects a `MediaController` to it and exposes Compose state.
Launching a game pauses the music unless Enable ingame is on (see Playing during games). Audio focus and headphone unplug are handled by ExoPlayer.
Added dependencies: `androidx.media3:media3-exoplayer` and `androidx.media3:media3-session` 1.3.1.
## Playback options
The player page has a Playback options button that opens a panel with:
- Speed and pitch, from 0.5x to 2x in 0.05 steps, applied through ExoPlayer's playback parameters.
- Skip silence.
- A sleep timer for 15, 30 or 60 minutes or the end of the current track. The timer runs in `SoundtrackService`, so it still fires when DroidDeck is closed.
- An equalizer with the device presets, one slider per band, and bass boost where the device supports it. The effects are attached to the player's audio session in the service.
Settings are saved in `soundtrack_settings` and sent to the service whenever the controller connects. The last album, track and position are saved too, so the play button on an album resumes where it stopped. The position is saved on track changes, pauses and seeks.
## Playing during games
Setup › Launcher has an Enable ingame toggle, shown while soundtracks are on. When it is off, launching a game pauses the soundtrack. When it is on, the soundtrack keeps playing and the service stops requesting audio focus, so the game's own audio mixes with it. The setting is sent to the service with the `INGAME` session command and is read again when the service starts.
## Searching and sorting
Inside a soundtrack, a search field above the track list filters by title, artist and album, and a sort button orders the list by album order, title or length. Track numbers always count from 1 by position in the list shown.
Custom (added) soundtracks, collections and Favorites can be reordered: select tracks first (long-press one, or use the select button), then with Album order selected and no search text, long-press a selected track and drag it. The order of an added soundtrack is stored in `soundtrack-order.json` and applied by `Soundtrack.load` within each disc; a collection stores its order in `soundtrack-collections.json`. Steam soundtracks cannot be reordered. The Music tab search also looks up tracks: soundtracks and collections whose names match come first, followed by a Tracks section.
## Favorites and collections
- The heart under the transport controls adds or removes the current track from Favorites. The bookmark button next to it opens the Saved panel to add the track to a collection or create one.
- The Music tab has a Collections chip. Favorites is the first entry under it. The bookmark in the Music header opens the same Saved panel to open or create a collection.
- Long-press a track to select. The selection bar has Select all, Deselect all, Add to collection, Add to favorites and, on a collection page, Remove from collection.
- A collection page has a Manage button to rename, add tracks, remove tracks or delete. Favorites cannot be renamed or deleted.
- Collection pages have Manage, Playback options, Shortcut and Edit art. Edit art changes the cover only, from a track cover or an image of your own, and is stored in `soundtrack-art/<id>`. Added soundtracks have the same Edit art, with the images in their folder and the first track cover as the choices; Steam soundtracks keep the Steam art editor.
- Collections are stored in `soundtrack-collections.json` in the app files directory as snapshots of path, title, artist, album, length and cover. Tracks whose files are gone are skipped when a collection is played.
- Collection and Favorites playback does not overwrite the saved resume position of an album.
+6
View File
@@ -52,6 +52,12 @@ again. A failed title lookup undoes nothing. The launcher likewise drops artwork
fetched for the app the files named before and fetches it again; pictures the user chose
are kept.
A game that stays a shortcut but sits in a Steam install directory with a single matching
manifest links its shortcut prefix to that app's existing `compatdata/<appid>`, so cloud
saves the client downloaded are the ones the shortcut sees. A Steam library install only
uses its own library's prefix. An existing shortcut prefix is never replaced, a link to a
missing prefix is removed first, and nothing is copied.
The account's `.droiddeck-routes.json` maps shortcut IDs to real Steam app IDs so the
Android launcher uses the same title and Proton prefix as Steam. Other accounts do not
inherit those routes. Managed shortcuts are replaced; user-created shortcuts and
+8 -2
View File
@@ -296,7 +296,10 @@ it, the cloud copies before an upload replaces them, under
A game launched before Proton has made its prefix (a first launch) gets its download deferred: the
request is answered at once (`result=deferred reason=no-prefix`) and the download runs as soon as
the prefix's user folder appears, within a minute. Every path logs
`cloud <store> <id> down|up result=ok|skipped|deferred|failed files= bytes= reason=`.
`cloud <store> <id> down|up result=ok|skipped|deferred|failed files= bytes= reason=`. A failure adds
`detail="..."`: the exception chain with the step (`list`, `get`, `put`), HTTP status, file and the
start of the server's error body, with URLs cut to their host and tokens, secrets and codes redacted.
GOG uploads stage their gzip body in the app's cache folder, which is created if it is missing.
- **The folder:** GOG's public remote-config gives a location template per game (by its Galaxy client
id), e.g. `<?APPLICATION_DATA_LOCAL_LOW?>/Hyperstrange/ELDERBORN`; Epic's catalog gives
@@ -328,7 +331,10 @@ the prefix's user folder appears, within a minute. Every path logs
migration runs once per game (`cloud_layout_<id>`), so a game that legitimately keeps a folder
named like the location is not relocated again; a non-prefixed listing is left unchanged.
- **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
own client (the client secret is kept at install; the Galaxy token is the fallback). Every
cloudstorage request sends Galaxy's communication-service `User-Agent` (`GOG_CLOUD_UA`, the
same string Heroic's gogdl and Lutris send), and PUT repeats it as `X-Object-Meta-User-Agent`;
the bare `GOG Galaxy` value is now refused with HTTP 400 `invalid_version`. Epic's
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`).
+28 -6
View File
@@ -33,11 +33,12 @@ followed by a proto2 message, except on `uplay_service_ipc_pipe_`.
| Pipe | Client | Exchange |
|---|---|---|
| `game_start_ipc_pipe_` | `UbisoftGameLauncher.exe` | `game_starter.Upstream{1:{1:{1: build, 2: product, 10: exe, 11: arguments, ...}}}` → `Downstream{2:{1:{1:0 (overlay off), 2:0, 3: <root>/ + "/" + <exe under root>, 4: <root>/, 8:3, 9:{1:{1,113,0,1,0} 1:{3,123,0,0,0}}}}}` |
| `uplay_api_process_ipc_pipe_` | game | `Req.initProcessReq{1: product, 2: game pid, 5: env set}` → `Rsp.initProcessRsp(13){1:1, 3:0 (overlay off), 4:3, 6:0}`. Kept open. Answering it is what releases the starter (below) |
| `uplay_ipc_pipe_` | game (`uplay_r1.dll`) | `Req.initReq(1)` → `Rsp.initRsp(1)`, answered every time it is asked. `Req.installerReq(13)` with `initInstallerReq` → `Rsp.installerRsp(10){1:{1:1, 2:"", 3: language}}` |
| `uplay_api_process_ipc_pipe_` | game | `Req.initProcessReq{1: product, 2: game pid, 5: env set}` → `Rsp.initProcessRsp(13){1:1, 3:0 (overlay off), 4:3, 6:0}`. Kept open. Answering it is what releases the starter (below). Far Cry 3 Blood Dragon sends only `{2: pid, 5:1}`; a missing pid is taken from the pipe's client process |
| `uplay_ipc_pipe_` | game (`uplay_r1.dll`, `uplay_r2.dll`) | `Req.initReq(1)` → `Rsp.initRsp(1)`, answered every time it is asked. `Req.installerReq(13)` with `initInstallerReq` → `Rsp.installerRsp(10){1:{1:1, 2:"", 3: language}}`. `Req.userReq(11).getCredentialsReq(1){1: id}` → `Rsp.userRsp(8).getCredentialsRsp(1){1: id, 2: username, 3: "" (password), 4: userId, 5: email}`. `Req.streamingReq(27)` → `Rsp.streamingRsp(20){1: id, 2:1, 4:{1:0}}` for the streaming type (not streamed), `{1: id, 2:4}` for any other streaming query |
| `uplay_aux_ipc_pipe_` | `uplay_aux_r1(64).dll` (Denuvo) | `{1: rid, 2: init}` → `{1: rid, 2:{1:1, 2: pid, 3:3367, 3:3368, 3:3962}}`; `{1: rid, 3:{2:{2: challenge}}}` → `{1: rid, 3:{2:{2:1, 3:0, 4: game token, 5:""}}}` |
| `uplay_service_ipc_pipe_` | Ubisoft helpers | Server sends `{3:{1:1, 3:{1: <hwscore path>}}}` once, then only reads, unframed |
| `upc_api_process_ipc_pipe_standard`, `uplay_protocol_ipc_pipe_`, `uplay_overlay_ipc_pipe_`, `orbit_ipc_pipe_`, `uplay_crash_reporter_ipc_pipe_` | — | Held open, never answered |
| `orbit_ipc_pipe_` | game (`ubiorbitapi_r2.dll`) | `mg.protocol.orbitdll` from the DLL's own `proto_orbitdll/OrbitDll.proto`. `Req{1: id, 12: init{1: product}}` → `Rsp{1: id, 12:{1: save folder, 2:1}}`; `getLoginDetails(2)` → `{1: username, 2:"", 3:""}`; `getOsi(3){1: sub}` → `{2:1}` (failed, no online-services pipe) |
| `upc_api_process_ipc_pipe_standard`, `uplay_protocol_ipc_pipe_`, `uplay_overlay_ipc_pipe_`, `uplay_crash_reporter_ipc_pipe_` | — | Held open, never answered |
### The session (`InitRsp`)
@@ -52,14 +53,36 @@ followed by a proto2 message, except on `uplay_service_ipc_pipe_`.
| 7 isInOfflineMode | 0 |
| 8 upcTicket | the PC ticket from `GetUplayPCTicket`, never the Denuvo token |
| 11, 12, 15, 16, 18, 19, 21, 23 | the values a real launch carries (`{1:0}`, 0, overlay `{1:0, 2:3}`, hardware score `{6211, 22395, 1.0f}`, empty, `{1:1, 2:1}`, `{2:1}`, empty) |
| 14 gameInstall | `{1:1, 2: installed chunks, 3: language}` |
| 17 storage | `{1: "C:/users/steamuser/Saved Games/Ubisoft/<userId>/<product>/"}`; the game appends file names directly, so the trailing slash matters |
| 22 ubiServices | `{1: applicationId}` from the account's entitlements, left out when unknown |
### R2 titles
`uplay_r2.dll` speaks the same `mg.protocol.uplaydll` messages (its embedded `UplayDll.proto` is identical to
`uplay_r1.dll`'s), but its `InitReq` names the subsystems the game uses: fields 4 to 11 (friend, overlay,
product, storage, install, multiplayer, store, streaming). Its `ApiContext` creates one object per requested
subsystem and copies the session into them. Friends, overlay, game session, store and crossboot are checked
for a missing object first; install and storage are not. A `gameInstall` sent to a game that did not ask for
install is copied into a null object: Prince of Persia: The Lost Crown (6145) asks for overlay, product and store
only, and crashed reading `0x68` in `uplay_r264.dll+0xaca2` two seconds after the session arrived.
So when the request names subsystems, 14 is sent only with `subSystemInstall` (8), 17 only with
`subSystemStorage` (7), and an empty `multiplayerInit` (20) is added, which `uplay_r2.dll` asks for even when
empty. A request that names none gets the session above unchanged. The Lost Crown also opens a second context
that asks for every subsystem, and it gets the full session.
The overlay is reported off in all three places. `uplay_r1.dll` still loads `overlay.dll` from the
runtime folder right after the session arrives, whatever the session says; without that file it gives up
with `UplayAPI [ERROR]: Startup failed: cannot load uplay library` (Assassin's Creed Chronicles: China
then sits on a black screen and aborts with code 3 after about 160 s), so the runtime includes it.
### Orbit titles
Older titles such as Far Cry 3 Blood Dragon (205) load `ubiorbitapi_r2.dll` next to `uplay_r1.dll` and ask
`orbit_ipc_pipe_` for `init` before anything else; unanswered, the game waits forever on a black screen. The DLL
keeps savegames itself as `*.save` files in the folder `init` returns, the same save folder as field 17 above.
## Start sequence
1. `droiddeck-upc.exe` creates the pipes and an auto-reset event marked inheritable, then starts the
@@ -84,7 +107,6 @@ titles without Denuvo never open the aux pipe.
## Not covered yet
- R2 (`UPC_*`) titles use `uplay_r2.dll`; their pipe traffic has not been captured, so whether the
same server answers them is unverified.
- Orbit (`ubiorbitapi_r2`) titles.
- R2 titles other than The Lost Crown, and R2 requests beyond the session, credentials, product list and streaming type.
- Orbit's online-services pipe (`getOsi` is declined) and Orbit titles other than Far Cry 3 Blood Dragon.
- Achievements, friends, overlay, cloud saves.
+1 -1
View File
@@ -1,6 +1,6 @@
# Reported video memory budget
The Performance VRAM setting enables `VK_LAYER_DROIDDECK_vram_cap` for games and reports smaller device-local `VK_EXT_memory_budget` budgets. DXVK exposes these through DXGI's `QueryVideoMemoryInfo`, including to D3D12 games using DXVK's DXGI alongside vkd3d-proton. Games that consult this budget can choose smaller working sets. The driver still supplies real heap sizes, usage figures, memory types, and actual allocation results. DXVK also receives its existing `dxgi.maxDeviceMemory` setting, which separately reduces the adapter's advertised dedicated video memory. A lower driver budget remains lower; the layer never increases it.
The Performance VRAM setting enables `VK_LAYER_DROIDDECK_vram_cap` for games and reports smaller device-local `VK_EXT_memory_budget` budgets. DXVK exposes these through DXGI's `QueryVideoMemoryInfo`, including to D3D12 games using DXVK's DXGI alongside vkd3d-proton. Games that consult this budget can choose smaller working sets. The driver still supplies real heap sizes, usage figures, memory types, and actual allocation results. DXVK also receives `dxgi.maxDeviceMemory` and `dxgi.maxSharedMemory`, which separately reduce the adapter's advertised dedicated and shared video memory (on a single-heap GPU DXVK reports the heap as both, so a game adding the two would otherwise still see the whole heap as shared), and, for caps below DXVK's 4096 MiB D3D9 default, `d3d9.maxAvailableMemory`, which caps the texture memory DXVK's D3D9 frontend reports, since D3D9 games do not read the DXGI setting. Higher caps leave the D3D9 setting alone so DXVK's lower per-game limits still apply. OpenGL games are not covered. A lower driver budget remains lower; the layer never increases it.
This does not make vkd3d-proton automatically enforce the selected budget. In the [upstream allocator inspected during this investigation](https://github.com/HansKristian-Work/vkd3d-proton/blob/865b12ba0cc20796b3709397ce5d6d3b8a205b04/libs/vkd3d/memory.c), `heapBudget` is used for diagnostic reporting, while the [DXVK adapter](https://github.com/doitsujin/dxvk/blob/cf0a0d90f8965147741ad17dcd0b263817572ab3/src/dxgi/dxgi_adapter.cpp) returns the Vulkan budget to applications. Seeing a smaller budget in a VKD3D log verifies reporting, not reduced allocation or eviction.
+72
View File
@@ -0,0 +1,72 @@
# Lab builds
A Lab build is DroidDeck app code and resources built on the device itself, by the on-device agent
or by hand, and loaded over the installed APK at the next start. Nothing is reinstalled or
re-signed, so a tester on a release build keeps their games, sign-ins and settings while trying a
change.
While a Lab build is active, add-on packs reuse the newest complete copy already installed on the
device, even when the checkout pins another version. This keeps helpers such as proot available
after restarting. If no complete copy exists, the pack uses the checkout's pin.
## How it works
- `tools/agent/dd-lab-build` builds the checkout with Gradle on the device (`processReleaseResources`
and `mergeDexRelease`), packs the linked resources and dex files into `overlay.apk`, writes
`overlay.json`, and stages both in the app's `files/lab/next`. It then recompiles the app without
an app image and restarts DroidDeck.
- Run by the app's own agent (`DD_AGENT` set), it writes `files/agent/lab-request` instead, and the
app runs the build in a process of its own, logging to `~/.cache/dd-lab-build.log`; the agent's
copy follows that log and exits with the build. A turn's processes end with the turn, so a build
started there would otherwise die when the agent stops or finishes early.
- At start, `LabOverlay` (called from `App.attachBaseContext`) promotes `next` to `active`, checks
that the build was made for this install, puts its dex files ahead of the APK's, and adds its
resources through `ResourcesLoader` to the app and every activity. Contexts made from them
(presentations on the second screen) inherit the loader.
- The watermark shows `LAB | <branch> @ <commit>`. When the app comes back on a new build it posts
a "Lab build installed" notification, so the restart does not look like a crash.
- A build that is replaced, turned off or refused is kept in `files/lab/builds` (the newest 12).
Updates lists them under Lab builds: the one in use can be turned off, one built for this
install can be used again, and any can be deleted.
The build targets the package owning `DD_AGENT_INBOX` when run from the Agent tab.
For a manual build of another package, set `DROIDDECK_PACKAGE`, for example
`DROIDDECK_PACKAGE=com.tencent.ig dd-lab-build`. This also selects the control provider,
Lab storage, and package to restart.
## What a Lab build cannot change
The manifest, native code (`cpp`, `jniLibs`, Rust), Gradle files, `App`, `AppLanguage`, and `LabOverlay` itself:
they are loaded before a Lab build can be, or are not part of it. `dd-lab-build` refuses those
changes; they need a new APK.
## Safety
- A build is only used on the install it was built for: `overlay.json` carries the APK's commit
(`apkCommit` in `droiddeckctl state`) and the APK's path, which changes with every install and
update. A build for another install is turned off.
- Two starts in a row that do not reach a resumed activity for 10 seconds turn the build off.
- It needs Android 11 or later (`ResourcesLoader`) and no app image (classes in one load before the
Lab build). `dd-lab-build` runs `cmd package compile -m verify` before restarting. Android's
background optimization can bring an app image back; the build is then paused, a notification
says so, and Restart in Updates recompiles through the app's wireless debugging pairing.
## Setting up a device
From the DroidDeck terminal, in a checkout of this repository:
```sh
tools/agent/setup
```
It installs Claude Code, git, gh and loopback adb, plus the build toolchain: JDK 17, the Android
SDK platform, and Google's x86-64 `aapt2` run under `qemu-user`. The first Lab build compiles the
whole app and takes about 8 minutes on a Snapdragon 865; later ones compile only what changed.
That needs the Kotlin daemon: Kotlin's in-process compiles always redo the whole app. BuildConfig
is given the installed commit, so committing a change does not change it. Setup
does that first build ahead of time with `dd-lab-build --prepare`, which compiles the installed
commit without making a Lab build.
`~/.cache/dd-lab-build.json` reports the stage, the current task, progress in thousandths and the
seconds left, estimated from how long each task took the last time (`~/.cache/dd-lab-build-times`).
`~/.cache/dd-lab-build-base` holds the installed commit the last successful build compiled, so the
Agent tab can offer to prepare again after DroidDeck updates.
+6 -5
View File
@@ -22,11 +22,11 @@ This describes the integrations implemented in DroidDeck as of 2026-10-24. A rec
| **VITURE Luma Ultra** | SDK-dependent Carina transport | Yes | **Experimental, opt-in** | **Experimental, opt-in** |
| Recognized RayNeo / TCL Air-series devices | Integrated RayNeo USB transport | Yes, with orientation calibration controls | No | No |
| RayNeo GT-series devices matching the supported USB identity, including GT Max identification | Integrated GT USB/IMU path | Yes, with orientation calibration controls | No | No |
| **XREAL 1S** | **Experimental**; exact USB identity plus the device's USB-Ethernet control/IMU connection | Yes, when that connection is ready | No | No |
| **XREAL 1S, One, One Pro, One Pro+, Aura** | **Experimental**; exact USB identity plus the device's USB-Ethernet control/IMU connection. Head tracking and 2D/3D switching are tested on the Aura | Yes, when that connection is ready | No | No |
| Rokid Max / Max 2; Rokid Air under the Max USB identity | Integrated Rokid USB transport (vendor control requests and HID IMU reports) | Yes | No | No |
| Other XREAL models; unrecognized glasses; display adapters and docks | Display-only where Android exposes a usable display; automatic glasses routing also requires display recognition | No supported app tracking connection | No | No |
| Other XREAL models (Air family and others); unrecognized glasses; display adapters and docks | Display-only where Android exposes a usable display; automatic glasses routing also requires display recognition | No supported app tracking connection | No | No |
RayNeo's Air-series recognition uses its known USB identity or a RayNeo/TCL Air name under the accepted vendor IDs; it is not a per-model certification list. The GT vendor path requires the specific supported product ID. Rokid recognition requires USB 04d2:162f (Max/Air) or 04d2:2002 (Max 2), plus a Rokid product name, since that vendor ID is shared with unrelated devices. Max 2 reports the USB product name "Rokid Max2". Hardware checks cover the Max and Max 2; the Air follows the same published protocol untested. XREAL support currently targets **1S only**: One, One Pro, Air-family devices, and recovery-mode products are not enabled by the 1S transport. VITURE Pro 2 is identified through SDK validation rather than a guessed product ID. A dock does not supply the connected glasses' sensors by itself.
RayNeo's Air-series recognition uses its known USB identity or a RayNeo/TCL Air name under the accepted vendor IDs; it is not a per-model certification list. The GT vendor path requires the specific supported product ID. Rokid recognition requires USB 04d2:162f (Max/Air) or 04d2:2002 (Max 2), plus a Rokid product name, since that vendor ID is shared with unrelated devices. Max 2 reports the USB product name "Rokid Max2". Hardware checks cover the Max and Max 2; the Air follows the same published protocol untested. XREAL support targets the 1S, One, One Pro, One Pro+ and Aura by exact USB product ID; Air-family devices and recovery-mode products are not enabled by this transport. VITURE Pro 2 is identified through SDK validation rather than a guessed product ID. A dock does not supply the connected glasses' sensors by itself.
The final column refers specifically to Luma Ultra's stereo tracking cameras. DroidDeck's separate phone-camera and physical-controller features are independent of this matrix.
@@ -43,6 +43,7 @@ All display modes depend on the phone's video output, the cable/adapter, and And
| VITURE Pro 2 | 1080p per eye; 2D and SBS | Brightness and volume; no electrochromic-film control |
| RayNeo Air/GT | 2D/SBS switching; resolution and refresh follow available Android modes | Orientation calibration; no app brightness, volume, or dimming commands |
| XREAL 1S | Supported 1S display-mode commands, including native 1200p/60 Hz and SBS | Brightness and dimming toggle; no app volume command |
| XREAL One, One Pro, One Pro+, Aura | 2D and SBS only, switched with the glasses' 3D input command; the display-mode set command is never sent (an unexpected index reboots the Aura) | No app brightness, dimming or volume commands |
| Rokid Max / Max 2 | 1080p at 60 or 120 Hz in 2D; SBS at 1080p/60, 1200p/60, or 1200p/90 | Brightness; volume follows Android's USB audio volume; no dimming film |
| Rokid Air | 1080p/60 in 2D and SBS | Brightness; volume follows Android's USB audio volume |
@@ -56,7 +57,7 @@ The pointer is left out of the picture when it cannot be drawn where the game is
## Setup and app-wide behavior
1. Connect the glasses through a compatible video/data connection. Accept USB access when requested. For XREAL 1S, Android must also expose the glasses' USB-Ethernet network; the app leaves Steam's Internet connection on its normal network.
1. Connect the glasses through a compatible video/data connection. Accept USB access when requested. For XREAL 1S, One, One Pro, One Pro+ and Aura, Android must also expose the glasses' USB-Ethernet network; the app leaves Steam's Internet connection on its normal network.
2. Open **Setup → Smart glasses**. Enable glasses output and **3DoF virtual screen**. This selects the tracked screen and saves the setting without forcing SBS or changing brightness.
3. Adjust screen width and distance, then recenter while looking where the screen should sit. The same settings apply when navigating DroidDeck, opening a non-Steam launcher, or entering a game/desktop session.
4. On an SDK-enabled Luma Ultra, optionally enable positional tracking and set the floor from the current eye height. Use the tracking setup and recovery controls for calibration or recentering. SteamVR startup defers Luma positional initialization until two seconds after SteamVR reports running.
@@ -85,4 +86,4 @@ If only a flat picture is available, check video output first, then the control
- [Agent diagnostics and capture commands](agent-control.md)
- [RayNeo attribution and protocol references](third-party/rayneo/README.md)
The capability definitions are maintained in [VITURE models](../app/src/main/java/com/droiddeck/launcher/glasses/VitureProtocol.kt), [RayNeo models](../app/src/main/java/com/droiddeck/launcher/glasses/RayNeoModel.kt), [XREAL 1S](../app/src/main/java/com/droiddeck/launcher/glasses/XrealModel.kt), [Rokid](../app/src/main/java/com/droiddeck/launcher/glasses/RokidModel.kt), and [connection capability routing](../app/src/main/java/com/droiddeck/launcher/glasses/Glasses.kt). Update this matrix when those integrations change.
The capability definitions are maintained in [VITURE models](../app/src/main/java/com/droiddeck/launcher/glasses/VitureProtocol.kt), [RayNeo models](../app/src/main/java/com/droiddeck/launcher/glasses/RayNeoModel.kt), [XREAL](../app/src/main/java/com/droiddeck/launcher/glasses/XrealModel.kt), [Rokid](../app/src/main/java/com/droiddeck/launcher/glasses/RokidModel.kt), and [connection capability routing](../app/src/main/java/com/droiddeck/launcher/glasses/Glasses.kt). Update this matrix when those integrations change.