# emulator-tools

Everything this machine uses to drive an Android emulator, in one place:
which emulator a command means, whether there is room to start it, reading a
screen as text, and taking a screenshot that does not cost a thousand tokens.

    ./install.sh

symlinks `bin/*` into `~/.local/bin` and `share/ui-trace` into
`~/.local/share`, so editing this repo is editing what runs. It keeps
anything it replaces as `<name>.bak`.

## What is here

| | |
|---|---|
| `emu` | this checkout's emulator: `name`, `serial`, `list`, `up`, `down` |
| `adb` | adb, aimed at this checkout's emulator, with screenshots scaled |
| `ui-trace` | records a screen as text at 60Hz, and drives it |
| `lib/project-avd.sh` | the rules all three share |
| `share/ui-trace/` | the device recorder (`UiTrace.java`) and its build |

## One emulator per checkout, named after it

`emu` and `adb` both work out which AVD you mean from the enclosing git
checkout: in `~/repos/ai-app-2` that is `ai-app-2`. Nothing has to be
configured, and `AVD_NAME` overrides it where the guess is wrong.

This is the rule that lets several agent sessions work here at once. The
emulator used to be the one resource that could not be parallelised: taking
it meant messaging the other sessions, waiting, and handing it back — and
installing an app onto somebody else's running emulator steals the foreground
from whatever they were looking at.

It is also why `adb` fills in `-s`. With two emulators attached, a bare
`adb shell pm list packages` comes back **empty** rather than failing, which
reads as the app having been uninstalled rather than as the question being
ambiguous. An explicit `-s`, `ANDROID_SERIAL`, or a subcommand that is not
about one device (`adb devices`) all turn the defaulting off, and nothing is
guessed when this checkout's emulator is not running: adb's own error is
better than a wrapper picking a stranger's device.

## Rendering on the GPU with no display

This machine has no screen, and for a long time that meant the emulator
rasterised in software. It does not have to: the VM sees the host's GPU
through virtio-gpu, and `/dev/dri/renderD128` is readable without being in
the `video` group.

What was in the way is that the emulator's `-gpu host` renderer speaks GLX,
so with no `DISPLAY` it cannot open a context at all -- it says
`GlxEnginegetDefaultDisplay: Failed to open display 0` and falls back. So
`emu up` starts a **headless sway** whose only job is to provide an
Xwayland, and Xwayland's GLX runs on the render node. The guest's GLES then
reports `virgl (AMD Radeon RX 7900 XT)` instead of a software rasteriser.
One compositor is started for the machine and reused, on a named socket
under `XDG_RUNTIME_DIR`; it needs no seat, no DRM master and no card node.

Measured 2026-08-31, scrolling the same list in the stock **Settings** app
on the same AVD with the same gesture -- so this is the platform's own cost,
with no app of ours in it:

| | janky frames | legacy janky | 90th percentile | slow UI-thread frames |
|---|---|---|---|---|
| software | 57.4% | 100% | 73ms | 18 |
| on the GPU | 2.3% | 5.7% | 26ms | 0 |

Read **both** jank columns. The legacy figure counts a frame against the
16.7ms deadline and the modern one against what the compositor actually
needed, so on a fast enough path the modern number can barely move while the
legacy one halves. When comparing two builds of an app in here, the legacy
column is usually the one carrying the signal.

An emulator also costs about **620 MB less** resident this way: measured
twenty seconds after boot on one AVD, 3537 MB on software against 2918 MB on
the GPU. (An earlier draft of this file said 1.1 GB. That number came from
`emu list` before the prefix bug in it was fixed, and was one emulator's size
reported against another's.)

This matters for more than speed. Before it, frame timings measured in here
said nothing at all about an app: every app was bounded by the rasteriser
rather than by anything it was doing, and the stock Settings app missed
*every single frame's* deadline while scrolling its own list. Now the
platform floor is low enough that an app's own jank is visible above it.

`GPU_HOST_FEATURES` carries the one workaround: host Vulkan is switched off,
because gfxstream asks Venus for a memory type for its ColorBuffers that
Venus does not offer, and the emulator dies before adb sees it. GLES is
unaffected. It is worth retrying whenever mesa moves -- the failure is loud
and costs one boot to find.

If sway is missing, or the compositor will not start, `emu up` says so and
starts on software rendering as it always did. None of this is essential.

## Refusing to start one

`emu up` checks `MemAvailable` first and refuses if starting an emulator
would leave the machine short, printing what is attached, what is large, and
what usually frees enough. `EMU_FORCE=1` overrides it.

The reason is a real incident rather than tidiness. On 2026-08-30 an emulator
was started on this box with 2.8 GB available; the OOM killer ran, and what
it took was not the emulator that had just started — it walked the user slice
and killed pipewire, dbus-broker and *another session's* emulator first. The
cost of one too many lands on somebody else's work, minutes later, looking
like an unrelated crash.

Measured numbers behind the defaults: a headless x86_64 AVD is about 3.8 GB
resident, this VM has 23 GB with a swap that is routinely full, two emulators
are comfortable, and three were not.

## Reading a screen without screenshots

`ui-trace` drives a small resident recorder on the device and samples the
accessibility tree at 60Hz, so an animation or a settling layout is visible
rather than happening between two samples.

    ui-trace record -d 3000 --do 'tap 540 800' -o /tmp/t.txt
    ui-trace elements /tmp/t.txt              # what is on screen, to pick from
    ui-trace show /tmp/t.txt                  # what moved
    ui-trace show /tmp/t.txt -m 'Send|Stop' --field box

Bounds come out in **device** pixels, so they feed straight back into a
`--do tap`. Prefer this to a screenshot for anything positional: two buttons
that measured identically at 171x105 looked different in a screenshot,
because the filled one read as larger than the disabled grey one. Screenshots
are for appearance — colour, weight, whether it looks right.

`adb exec-out screencap -p` still works and comes back scaled to 800px on its
long edge, which is ~380 tokens to read instead of ~1460 and still legible
for layout, contrast and small labels. `ADB_SCREENCAP_MAX_EDGE` raises it for
one call.

## Using it from a project

A project's own `run-android.sh` should build and install; the emulator half
belongs here:

    SERIAL=$(emu up)
    ./gradlew :androidApp:assembleDebug
    adb install -r <apk>          # already aimed at this checkout's emulator