Release: Steam Frame installer, release signing, Frame import kept

- A Steam Frame installer for players, opened in Desktop Mode (Install-Halo-VR.desktop, a release asset): it downloads the latest release's bundle (tools/steam_frame_bundle.py) and runs steam_frame_install.sh, with zenity dialogs and no keyboard: the APK and launcher in ~/Documents/HaloCE, the maps copied out of a disc image it finds or is given (steam_frame_xiso.py, the app's XisoExtractor in Python), and Halo VR in the Steam library with its pictures and OpenVR set. Running it again updates the game. - The release job adds the bundle and the desktop file to each release. - build.gradle signs with port/android/signing.properties (ignored) when the workflow's key is not given, so local builds and releases install over each other. - On the Frame the launcher and host take ~/Documents/HaloCE whenever it can be written, not only once it holds maps: a disc image imported in the app is no longer emptied with Lepton's folders. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge feature/vr-lefthanded-graphics: left-handed mode, graphics presets, refresh rate and resolution in VR
2026-10-17 18:00:25 +02:00 · 2026-10-06 22:06:21 +02:00 · 2026-10-06 21:21:38 +02:00 · 2026-10-06 21:21:35 +02:00 · 2026-10-06 20:55:22 +02:00 · 2026-10-06 20:40:01 +02:00
821 changed files with 90822 additions and 1695 deletions
@@ -67,7 +67,9 @@ jobs:
        run: python tools/ci_build.py linux release

      - name: Test
-        run: python -m pytest -q tools/test_linux_port.py
+        run: |
+          python -m pytest -q tools/test_linux_port.py
+          python tools/test_light_storage.py

      - name: Compile cache
        run: ccache --show-stats
@@ -200,6 +202,9 @@ jobs:
      - name: Release
        run: python tools/ci_build.py windows release

+      - name: Test light storage
+        run: python tools/test_light_storage.py
+
      - name: Compile cache
        run: ccache --show-stats

@@ -232,6 +237,13 @@ jobs:
      GH_TOKEN: ${{ github.token }}
      GH_REPO: ${{ github.repository }}
    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            port/android
+            port/third_party/extract-xiso
+            tools
+
      - uses: actions/download-artifact@v4
        with:
          pattern: halo-*
@@ -242,11 +254,11 @@ jobs:
          mkdir release
          for build in artifacts/*/; do
            name="$(basename "$build")"
-            # stored, not deflated: the updater in builds up to 57 waits for
-            # an end of stream the game's zlib 1.1 does not always report,
-            # and fails on a deflated entry that unpacked correctly
-            (cd "$build" && zip -0 -qr "$GITHUB_WORKSPACE/release/$name.zip" .)
+            (cd "$build" && zip -qr "$GITHUB_WORKSPACE/release/$name.zip" .)
          done
+          # the Steam Frame's installer (port/android/STEAM_FRAME.md): its
+          # bundle with the release APK, and the desktop file that fetches it
+          python3 tools/steam_frame_bundle.py artifacts/halo-android-release/app-release.apk release "$GH_REPO"
          ls -l release

      - name: Publish
@@ -260,7 +272,7 @@ jobs:
          subject="$(printf '%s' "${MESSAGE:-manual run}" | head -n 1)"
          printf '%s\n\nCommit: %s\nBuild: %s\n\nThe release builds are for playing; the debug builds stop at the first failed assertion and log it.\n' \
            "$subject" "$COMMIT_URL" "$RUN_URL" > notes.md
-          gh release create "$tag" release/*.zip --target "$GITHUB_SHA" --latest \
+          gh release create "$tag" release/* --target "$GITHUB_SHA" --latest \
            --title "Build $GITHUB_RUN_NUMBER (${GITHUB_SHA:0:7})" --notes-file notes.md
          echo "tag=$tag" >> "$GITHUB_OUTPUT"

@@ -24,7 +24,14 @@ xbox/

 # Locally extracted proprietary game data (never commit)
 assets/
+# (but the high-res assets, drawn for the port: tools/hud_assets.py)
+!port/assets/
 original/

 # CI build outputs (tools/ci_build.py)
 dist/
+
+# The app signing key's local settings and keys (port/android/app/build.gradle; never commit)
+port/android/signing.properties
+*.jks
+*.keystore
@@ -19,9 +19,9 @@ builds of the latest release:

 | Platform | Release | Debug |
 | --- | --- | --- |
-| Linux | [halo-linux-release.zip](https://github.com/cybersecurity/halo-ce-universal/releases/latest/download/halo-linux-release.zip) | [halo-linux-debug.zip](https://github.com/cybersecurity/halo-ce-universal/releases/latest/download/halo-linux-debug.zip) |
-| Windows | [halo-windows-release.zip](https://github.com/cybersecurity/halo-ce-universal/releases/latest/download/halo-windows-release.zip) | [halo-windows-debug.zip](https://github.com/cybersecurity/halo-ce-universal/releases/latest/download/halo-windows-debug.zip) |
-| Android | [halo-android-release.zip](https://github.com/cybersecurity/halo-ce-universal/releases/latest/download/halo-android-release.zip) | [halo-android-debug.zip](https://github.com/cybersecurity/halo-ce-universal/releases/latest/download/halo-android-debug.zip) |
+| Linux | [halo-linux-release.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-linux-release.zip) | [halo-linux-debug.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-linux-debug.zip) |
+| Windows | [halo-windows-release.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-windows-release.zip) | [halo-windows-debug.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-windows-debug.zip) |
+| Android | [halo-android-release.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-android-release.zip) | [halo-android-debug.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-android-debug.zip) |

 Use the release build to play. The debug build stops at the first failed
 assertion and writes it to the log. Use the debug build to find and report
@@ -32,7 +32,7 @@ if you want to install it. Refer to "Updates" in
 [port/linux/README.md](port/linux/README.md#updates).

 Each build of the `main` branch that passes on all three platforms is a new
-release. The [Releases](https://github.com/cybersecurity/halo-ce-universal/releases)
+release. The [Releases](https://github.com/OpenCommunityEdition/OpenCE/releases)
 page keeps the last five releases. If the latest build has a problem, get
 an older build from that page.

@@ -155,7 +155,15 @@ select "Yes":
 To install over the previous version, each build must have the same
 signature. GitHub Actions signs each build with the key in the
 `ANDROID_KEYSTORE_BASE64` and `ANDROID_KEYSTORE_PASSWORD` secrets of the
-repository. If you installed a build that has a different signature, remove
+repository. A computer that builds for its own devices signs with the same
+key when `port/android/signing.properties` (not in the repository) names it:
+
+    storeFile=/path/to/halo-vr-release.jks
+    password=<the keystore's password>
+    keyAlias=halo
+
+Keep the keystore and its password safe: a lost key means every player must
+remove the app before the next version. If you installed a build that has a different signature, remove
 that build before you install a new build. Removing the app deletes its data
 folder: first make a copy of `maps/` and `save/`.

@@ -168,7 +176,8 @@ the Xbox:
 - The HUD stays at the edges of the screen.
 - The menus, the loading bar and the screens after a game have 640
  columns, at the center of the screen.
- Black bars and fades cover all of the screen.
+- Black bars and fades cover all of the screen, and so do the menus' dims
+  and backgrounds (the pause menu's dim, dialogs, the menus' gradient).

 ## VR

@@ -0,0 +1,169 @@
+# Steam Frame
+
+The same APK as for the Quest runs on the Steam Frame, in Lepton (SteamOS's
+Android, a Waydroid fork: Android 11, arm64), with SteamVR's OpenXR runtime.
+What differs is found at run time, not by a build of its own.
+
+## Installing it (players)
+
+On the Frame, in Desktop Mode (Steam menu > Power > Switch to Desktop):
+1. Put a disc image of Halo: Combat Evolved for the Xbox (`.iso` or
+   `.xiso`, any version) in Downloads (or Documents, the Desktop, a memory
+   card).
+2. Download `Install-Halo-VR.desktop` from the latest release and open it
+   (double-click; confirm running it).
+3. Answer the dialogs: the installer finds the disc image (or asks for it),
+   copies the game data out of it, adds "Halo VR" to the Steam library and
+   switches back to Gaming Mode. Start Halo VR from the library there.
+
+Opening the same file again updates the game (settings, saves and game data
+stay).
+
+The desktop file (`steam_frame_installer.desktop`) downloads the latest
+release's `halo-vr-steam-frame.zip` (`tools/steam_frame_bundle.py`, made by
+the release job of `.github/workflows/build.yml`) and runs its
+`install.sh` (`steam_frame_install.sh`), with zenity dialogs:
+- `~/Documents/HaloCE`: the launcher (`halo-vr.sh`) and the release APK;
+- the maps folder out of the disc image (`steam_frame_xiso.py`, the app's
+  `XisoExtractor.java` in Python), unless `maps/ui.map` is there;
+- the Steam shortcut (`shortcuts.vdf` as below, with `OpenVR` set, and the
+  library pictures), unless it is there: Steam is closed for that, as it
+  writes its shortcuts back when it quits.
+
+`HALO_VR_UNATTENDED=1` (and `HALO_VR_IMAGE=<image>`) runs it without
+dialogs, for testing over adb; it leaves Steam and its shortcuts alone.
+
+## The device
+
+- Steam Settings > System > Enable Developer Mode; then start "Lepton
+  Development" from the library. While the headset sleeps Lepton stops, and
+  adb with it.
+- adb over the network: `adb connect <frame-ip>:5555`; over USB:
+  `adb forward tcp:5555 tcp:5555` then `adb connect localhost:5555`.
+  Always name the device (`adb -s <frame-ip>:5555 ...`): a Quest may be
+  connected as well.
+- Install with `adb install -r --no-streaming`. It prints "Lepton post
+  installation failed due to APP_PATH being unset", but installs. Start the
+  game with `am start -n com.halo.decomp/.LauncherActivity`.
+- Lepton empties `/sdcard/Android/data` whenever it starts again: the game's
+  data must live elsewhere (stage 2). `/sdcard/Documents` and
+  `/sdcard/Download` are the SteamOS user's folders and are kept.
+
+## What the port does for it
+
+- SDL3's clipboard handler takes a clipboard service for granted, which
+  Lepton has not: `tools/android_build.py` patches it to do without.
+- SteamVR lists an implicit OpenXR layer for Vulkan apps whose library an
+  app cannot load: the APK carries a pass-through layer under its name
+  (`port/android/xr_layer/fdm_injection_stub.c`).
+
+## Stages
+
+| # | Stage | State |
+| --- | --- | --- |
+| 1 | Base: the fixes above on the current main | done |
+| 2 | The game's data where Lepton keeps it | done: `/home/steamos/Documents/HaloCE` |
+| 3 | Menus, HUD and text visible (quad layers) | done: their alpha from their colour |
+| 4 | The freeze at the cryo bay's calibration | not seen again (2026-10-04) |
+| 5 | The Frame's controllers | done: their own profile, the Xbox's layout |
+| 6 | Frame rate, resolution | done: 72 Hz steady, multiview on |
+| 7 | Multiplayer, voice, cross-play with the Quest | |
+| 8 | A button in the Steam library | done: `steam_frame_launch.sh` |
+
+## Starting it on the Frame
+
+A button in the Steam library ("Halo VR", a non-Steam game) runs
+`~/Documents/HaloCE/halo-vr.sh` (`port/android/steam_frame_launch.sh`),
+which starts the game as Steam starts an Android title of its own:
+`lepton waitforexitandrun -- ~/Documents/HaloCE/HaloVR.apk`, in a container
+of its own (`steamlaunch-4290000001`) that Lepton installs the APK into
+anew whenever the file is newer. Updating the game is replacing that APK.
+
+What the script does that Steam would for an Android title:
+- a compat data path (`steamapps/compatdata/4290000001/internal`): after an
+  install Lepton links the app's data to it, a dangling link without it;
+  and the shader path, which Lepton reads Steam's shader dump path against;
+- a container id of its own: with the shortcut's id, SteamVR's client in the
+  container stalled in xrCreateInstance;
+- a few starts: a new APK's first start only installs it, and a start that
+  ends within 30 s is tried again (up to three times), unless the game was
+  quit (it writes `quit_requested.txt`).
+
+Steam's "Exit game" does not reach the game (its process is the container's,
+not Steam's): quit it with the VR options' "Quit Halo" (Y in the main or
+pause menu, twice). A container ended within 30 s of its start makes
+Lepton drop the app's install, so the next start installs it again.
+
+The shortcut is in `userdata/<id>/config/shortcuts.vdf` (Steam reads it when
+it starts; appid 3151454348 for this name and path), its pictures in
+`userdata/<id>/config/grid/` (from `port/android/steam_frame_grid/`). From
+the Mac, over USB the Frame's SteamOS is an adb device of its own, `frame`,
+beside Lepton's `<frame-ip>:5555`.
+
+## The game's data
+
+Lepton uninstalls the app and empties its folders whenever it starts again.
+The game's data lives in the SteamOS user's Documents instead: when
+`/home/steamos/Documents` can be written, the launcher makes
+`/home/steamos/Documents/HaloCE` and the launcher and the game take it as
+their data folder (config.toml, saves and debug.txt go there too), so a
+disc image imported in the app stays as well. The installer above fills it;
+by hand, once:
+
+    adb -s <frame-ip>:5555 shell mkdir -p /home/steamos/Documents/HaloCE/maps
+    adb -s <frame-ip>:5555 push assets/maps/. /home/steamos/Documents/HaloCE/maps/
+    adb -s <frame-ip>:5555 shell chmod -R 777 /home/steamos/Documents/HaloCE
+
+After a Lepton restart only the APK is installed again. (Use the path under
+/home, not /sdcard/Documents: Android 11's scoped storage stands between the
+app and the latter.)
+
+## The controllers
+
+SteamVR offers the Frame's controllers as themselves
+(`XR_VALVE_frame_controller_interaction`,
+`/interaction_profiles/valve/frame_controller_valve`; Valve's "Steam Frame
+Input" page). Without bindings for it, SteamVR maps the Quest's onto them,
+and the left Touch controller's X and Y land on the D-pad. With them the
+game gets the Xbox's layout, as the right controller has it: A jump, B
+flashlight (held: switch grenades), X action and reload, Y switch weapon,
+menu pause; the left one's View is Back (scores), its D-pad the D-pad, the
+bumpers switch grenades (left) and the flashlight (right). The VR options'
+page of buttons shows this layout on the Frame.
+
+## Findings
+
+- 2026-10-02: runs flat and in VR (GLES 3.2 by Mesa zink on Turnip, eyes
+  1728x1728, 72 Hz, XR_FB_display_refresh_rate absent). Quad layers
+  (menus, HUD, instructions) are not shown; the projection layer is. Froze
+  at the cryo bay's look calibration; its log was lost to Lepton's wipe.
+- 2026-10-04: SteamVR draws a quad's texels by their alpha alone; the
+  game's menus and HUD have none in their additive parts, so nothing showed.
+  On SteamVR (by the runtime's name) the overlays' alpha now comes from their
+  colour (host_xr.c; `HALO_XR_QUAD_ALPHA=colour|keep` overrides). With it,
+  menus, HUD and the campaign ran well (the user: "lief 1a"); no freeze.
+- 2026-10-04: no online games found: the public MQTT brokers had banned the
+  home connection for a while (too many connections from tests that day);
+  broker.emqx.io came back within minutes. Lepton's network is the Frame's
+  own (same IP), DNS works.
+- 2026-10-04: the refresh rate is SteamOS's setting; the runtime offers
+  only that one (the game asks for the highest at or below
+  `vr.refresh_rate`, and logs the rates offered). At 72 Hz the game holds
+  72 fps (about 11.6 ms a frame with multiview, eyes 7.6 ms; without it
+  eyes about 9 ms). At 90 Hz it cannot (11.1 ms a frame), and SteamVR's
+  making up of the missed frames showed as a doubled picture when turning
+  the head. Keep the Frame at 72 Hz, or lower `vr.resolution_scale` (about
+  0.85) for 90.
+- 2026-10-05: doubled pictures when turning at 72 Hz too, the game at the
+  edge of its frame (12.5 of 13.9 ms; SteamVR reprojecting 2-8% of the
+  frames). The time was not the drawing's but waits: the layer copies read
+  the GL state back (glGet*) and released each image at once, and with
+  Mesa's GL thread (zink) every read waits for the thread to run all that
+  is queued, every release for the GPU (the left eye's copy took 4.5-7 ms
+  of the frame, the right one's, just after it, 0.7). On SteamVR the copies
+  are now deferred (host_xr.c): no state read back (the game sets its own
+  again), the images released together as the frame ends, and the eyes'
+  work flushed to the GPU as soon as they are copied.
+  `debug.xr_deferred_copies` = 0 brings back the old copies for comparing,
+  1 defers them on any runtime; `vr.log_performance` logs the frame's parts
+  and, with the compositor's counters, each copy's time.
@@ -0,0 +1,230 @@
+# VR roadmap
+
+What the VR port (Quest 3, Steam Frame) has, and what comes next, in the
+agreed order. Updated with every step: a step is **done** once the user has
+tried it in the headset and it is merged into `main`; **built** means in a
+branch, not yet tried in the headset.
+
+Several of the next steps follow
+[HaloCE-Quest-VR](https://github.com/moistman42069/HaloCE-Quest-VR) and the
+Steam Frame work it grew from,
+[astromaddie/HaloCE-VR](https://github.com/astromaddie/HaloCE-VR) (both
+CC0): their ideas, rebuilt into this port's own structure, with the source
+named where code is taken over.
+
+## Done (in `main`)
+
+| Area | What |
+| --- | --- |
+| Headsets | Quest 3; Steam Frame (Lepton): its controllers' layout, a Steam library tile that installs, starts, updates and quits the game, data kept in `~/Documents/HaloCE` |
+| Rendering | Both eyes in one pass (multiview) on the Quest; one by one on SteamVR, where multiview's eyes did not fuse; lens flares at their depth in stereo; HUD, menus, scope, crosshair and names as layers of their own |
+| Aiming | The weapon in the hand, its shots from the muzzle, laser and crosshair options |
+| Body | Physical crouch (`vr.crouch_limit`) beside the crouch button, leaning (`vr.lean_limit`), melee by swinging, grenades thrown with the left hand, two-handed weapons |
+| Vehicles | The Warthog's wheel turned with the hands, right trigger throttle, left brake; first-person seats; turrets with handles |
+| Comfort | Snap or smooth turning, a comfort vignette in vehicles, VR options in the main and pause menus (Y), a page of every controller button |
+| Menus | The PC version's menus in VR (`vr.menus`), clicked with a laser; text typed on the on-screen keyboard |
+| Multiplayer | Up to date with OpenCE (network version 20): cross-play, its server browser, co-op campaign, password lobbies; join codes and the VR online list |
+| Bots | Bots in multiplayer: on foot (paths, items, objectives), in vehicles and at turrets; they make room for a joining person |
+| Controls | Left-handed mode (`vr.handedness`): the weapon in the left hand, the arms and grips mirrored, sticks and buttons mirrored on both controllers (`vr.mirror_controls`), the assault rifle's counter read the right way round (2026-10-06) |
+| Graphics | Presets low / medium / high / max (`vr.graphics`), refresh rate and resolution in the VR options, all kept over a restart (2026-10-06) |
+| Arms and hands | Both arms by IK from shoulders that follow the torso, the elbow led by the hand's roll; fingers from trigger, grip and touch; `vr.body` arms / hands / off, `vr.fingers` (2026-10-06) |
+
+## Next, in order
+
+| # | Step | State |
+| --- | --- | --- |
+| 1 | Steam Frame CPU time: Mesa's trace markers off (after astromaddie/HaloCE-VR), no `glGet` stalls in the visibility counters' copies | **done** (in `main` 2026-10-06): markers quieted, no problems; the frame's work about unchanged (11-12.5 ms of 13.9 in a bot game) |
+| 3a | Visible arms and hands: the arms by IK to the controllers, fingers by trigger and grip | **done** (in `main` 2026-10-06; Quest 3 and Steam Frame good; 0.02 ms a frame) |
+| 2 | Controls and comfort: left-handed mode, buttons remapped, flashlight by tapping the head, finer turning and vignette choices, graphics presets and refresh rate in the VR options | first part **done** (in `main` 2026-10-06; Quest 3 and Steam Frame good): left-handed mode, graphics presets, refresh rate and resolution in the VR options. Left: buttons remapped, flashlight by tapping the head, finer turning and vignette choices |
+| 3b | The whole body: torso from head and hands, legs and feet following in the room; full / arms only / hands only | |
+| 3c | Weapons held physically, holsters at shoulder and hip (the buttons stay) | |
+| 3d | Other VR players shown with their heads, hands and bodies (today their bodies move as flat players' do: only their aim and throws come from their hands) | |
+| 4 | Later: disc image import in the launcher, sprint by arm swing (offline) | import **built** (branch `feature/release-install`): the app's import (Quest; on the Frame now kept in `~/Documents/HaloCE`), a Steam Frame installer from Desktop Mode (`STEAM_FRAME.md`), a release signing key; test pending |
+
+## Step 2, first part (done)
+
+Left-handed mode and graphics presets, after HaloCE-Quest-VR (CC0): its
+mirrored first-person model, its graphics switches.
+
+Left-handed (`vr.handedness = "left"`):
+- The weapon in the left hand: aim, shots, muzzle, laser, crosshair,
+  scope disc, turret aim. The first-person model is posed as the right
+  hand's in a mirror image of the room ("model space", `halo_vr.h`) and
+  mirrored back; a model whose node matrices mirror has its triangles'
+  winding turned over (`rasterizer_set_model_skinning`, `d3d8_gl.c`). The
+  arms reach to the other shoulders, the foregrip is gripped with the
+  right hand, the right hand's fingers follow its controller.
+- Grenades held and thrown with the right trigger and hand; melee by the
+  left grip (a swing of either hand, as before); the motion tracker on the
+  right wrist (`halo_xr_submit.wrist_hand`); the rumble's light motor in
+  the weapon hand.
+- The left trigger fires, the right one throws; at the Warthog's wheel the
+  left trigger accelerates, the right one brakes.
+- With `vr.mirror_controls` (default): the right stick moves, the left
+  turns and steers; their clicks, the bumpers and the face buttons change
+  sides (Quest: X jumps, Y light / held grenades, A action and reload, B
+  switch weapon; Steam Frame: the left D-pad does A, B, X, Y as their
+  mirror image, down jump, left light, right action, up switch weapon,
+  and A, B, X, Y do the D-pad's). The menus keep their buttons; the
+  laser pointer works from either hand as before.
+- Other machines see the shots leave the left hand (the network message
+  is unchanged: aim and muzzle from the camera).
+- The assault rifle's ammo counter and compass read the right way round
+  on the mirrored model (2026-10-06): their geometry stays mirrored, each
+  digit's bitmap is drawn turned over in u and the digits' order across
+  the display swapped (numeric shaders drawn mirrored,
+  `rasterizer_xbox_transparent_geometry.c`). Checked flat in the emulator
+  with `debug.mirror_first_person` (the first-person weapon mirrored off
+  the headset): 60, 48, 36 ... 06 read correctly. Steam Frame good
+  (2026-10-06).
+- Kept as they are (accepted 2026-10-06): the small static icons under the
+  counter (round and "x") stay mirror images (a texture atlas, not
+  numeric). The game's prompts still name the Xbox's buttons.
+- Settings kept: on Android `config.toml` is written beside itself and
+  renamed over (`port_config.c`), so one pushed by adb (the shell's, which
+  the app could not open for writing) no longer loses the VR options'
+  changes at a restart.
+- Headset tests 2026-10-06: Quest 3 and Steam Frame good (left hand,
+  controls mirrored and not, counter, presets, refresh rates, resolution,
+  settings kept over a restart).
+
+Graphics (`vr.graphics`, `port/linux/game/vr_graphics.c`), set each frame
+on the game's own switches:
+
+| Preset | Leaves out |
+| --- | --- |
+| `"high"` (default) | nothing: as before |
+| `"medium"` | object shadows, environment reflections, lens flares |
+| `"low"` | also specular light, bump maps, grass and other detail objects, the screen's fog layer, contrails, weather, camouflage's second pass |
+| `"max"` | nothing; models lit for each pixel, shadows at 512x512 |
+
+A client in another's game keeps grass, lens flares and the fog layer as
+the host's rules have them (`cheats.c`). Shadows, specular passes,
+reflections and detail objects are draws (CPU, which the Frame's GL
+driver is short of); bump maps, fog, camouflage and per-pixel lighting
+the GPU's fill.
+
+VR options (Y): two pages, PLAY (the comfort rows, "Weapon hand",
+"Mirrored controls") and MORE ("Graphics", "Refresh rate", "Resolution",
+the controller buttons page, Quit). The refresh rate steps through what
+the runtime offers and changes at once; on the Steam Frame the row shows
+SteamOS's rate. The resolution (`vr.resolution_scale`, 70-120%) takes a
+restart. The controller buttons page shows the layout as set.
+
+| Setting | Values |
+| --- | --- |
+| `vr.handedness` | `"right"` (default), `"left"` |
+| `vr.mirror_controls` | `true` (default): sticks and buttons mirrored when left-handed; `false`: as right-handed (triggers and grips still follow the hands) |
+| `vr.graphics` | `"low"`, `"medium"`, `"high"` (default), `"max"` |
+| `vr.refresh_rate` | Hz, as offered (Quest 3: 72, 80, 90, 120) |
+| `vr.resolution_scale` | 0.7 to 1.2, on restart |
+
+To try in the headset (Quest 3 and Steam Frame):
+1. Left-handed: aim, laser, crosshair, scope of sniper and rocket
+   launcher; weapon held right in the left hand, arms from the right
+   shoulders, nothing inside out (faces culled the wrong way would show
+   the inside of the gun or the glove).
+2. Two-handed grip with the right hand; grenades in the right hand (held
+   and thrown); melee by grip and by swing; motion tracker on the right
+   wrist.
+3. Buttons and sticks mirrored on the Touch and the Frame controllers
+   (every function reachable), then `Mirrored controls: Off`.
+4. Vehicles: wheel, throttle and brake, steering stick, a gunner's aim;
+   menus and the laser pointer; a network game (shots from the left hand
+   on the other machine).
+5. Graphics: each preset's look and smoothness (`vr.log_performance`),
+   in a bot game; Max on the Quest at 90 Hz; refresh rates 72/80/90/120
+   on the Quest; the Frame's row.
+
+## Step 3a (done)
+
+Tried on the Quest 3 and the Steam Frame, in `main`. The arm IK,
+the forearm's twist and the fingers' poses follow HaloCE-Quest-VR (CC0),
+in `port/linux/game/vr_arms.c`.
+
+- The first-person pose (weapon, arms) is built once a frame instead of
+  per eye and scope view (SteamVR: two to three times before).
+- `vr.log_performance` reports its cost (`VR:   first person: ... ms a
+  frame in ... builds (arms ... ms), ... kept`) and, once, how the hands'
+  skin hangs from its bones (none from the root: no triangle filter
+  needed).
+- Both arms bend from shoulders below the neck, square to the torso. The
+  torso follows the head beyond 15 degrees and turns towards the hands;
+  snap and smooth turns carry it at once.
+- The free left arm bends at the elbow to the controller (before: carried
+  rigidly). The hand's roll is shared along forearm and upper arm.
+- The free hand's fingers follow the controller: index from the trigger,
+  the others from the grip, the thumb from where it rests (touch on the
+  Quest's, Index and Steam Frame controllers; half curled where unknown),
+  closed round a held grenade. The weapon hand keeps its grip; its index
+  finger lifts off the trigger when the controller says it is off.
+- host_xr: touch actions for thumb and index; `suggest()` takes 64
+  bindings (was 32, silently cut) and retries a profile without the
+  touch paths should the runtime refuse them.
+
+Settings (`[vr]` in config.toml; the first two also in the VR options,
+Y on the main or pause menu):
+
+| Setting | Values |
+| --- | --- |
+| `vr.body` | `"arms"` (default), `"hands"` (hands alone, the arms shrunk behind the wrists), `"off"` (the weapon alone) |
+| `vr.fingers` | `true` (default): fingers follow the controller; `false`: as the weapon's animation has them |
+| `vr.arm_ik` | `true` (default): the free arm bends at the elbow; `false`: rigid as before, should its skin tear |
+
+After the first Quest tries (2026-10-06):
+- The shoulders 13 cm behind the eyes and 20 cm below the neck: the open
+  end of the sleeve was in view. Looking hard down to the side one still
+  sees into the arm (the model ends at the shoulder): left as it is.
+- The elbow bends in the arm's plane (`vr_align_elbow`): it had turned in
+  with the elbow out to the side; the upper arm takes none of the hand's
+  roll.
+- The free arm is solved first and its hand turned after (as
+  HaloCE-Quest-VR does): turned first, its skin stretched like a rubber
+  band.
+- The elbow follows the hand's roll (lifted out, the controller rolls in):
+  before, it bent only towards a fixed direction.
+- Arm length, shoulder width, fingers, grenade grip, body modes, scope,
+  vehicles: fine.
+
+Not in it (3a.7): the glove fitted to each weapon's grip (gun anchor) and
+the left hand animated through reloads.
+
+## Open points outside the order
+
+- Multiview on the Steam Frame: why the eyes do not fuse there (suspected
+  Mesa zink/Turnip); tools in branch `frame/doubled-images` (86335828),
+  not merged.
+- Transparent geometry groups: the Xbox's 384 a window overflow in games
+  of 30 and more players.
+- The VR on-screen keyboard shows a password in the clear while it is
+  typed.
+
+## Headset tests (2026-10-06, all three in `main`)
+
+Quest 3, 2026-10-06: menus, laser, VR options, head turning, arms and
+hands, fingers, body modes, scope, vehicles, a bot game (bots spread and
+leave their bases) and a large online game: all good.
+Steam Frame, 2026-10-06: buttons, picture (no doubled image), arms, hands,
+fingers, wheel: all good; SteamVR reprojected 18% of the frames, unseen.
+What follows is left for the two headsets together.
+
+Upstream merge (`merge/upstream-2026-10-06`):
+- Menus, a bot game, head turning (no doubled image), co-op briefly.
+- A password game hosted on the Frame, joined from the Quest.
+- A bot making room for a person joining a full lobby.
+
+Performance (`frame/performance-2`, and the merge's upstream speed-ups),
+with `vr.log_performance = true`:
+- Frame: the log says `trace markers: N descriptors to /dev/null`; frame
+  time ("working") against before (about 12.5 ms in a bot game on Blood
+  Gulch); SteamVR's reprojected share (vrcompositor.txt) against before
+  (2 to 17 %); no doubled image.
+- Lens flares still appear and hide as before (their visibility counters'
+  copies changed).
+- The pose cache (3a.1): `first person: ... builds` about one a frame;
+  scope, crosshair, laser and the weapon in the hand as before.
+- Quest: 90 Hz held as before in a bot game and in a large online game;
+  nothing slower than the last build.
+
+Arms and hands (3a): on the Steam Frame, as on the Quest (fingers on its
+controllers, every button still working).
@@ -13,9 +13,22 @@ def buildNumberText = System.getenv("HALO_BUILD_NUMBER") ?: "0"
 def buildNumber = buildNumberText.isInteger() ? buildNumberText.toInteger() : 0

 // the workflow's signing key (.github/workflows/build.yml): every build of
-// main signed with it can install over the one before; without it, the
+// main signed with it can install over the one before; on a computer that
+// builds for its own devices, the same key from port/android/signing.properties
+// (not in the repository: storeFile, password, keyAlias), so that its
+// builds and the releases install over each other; without either, the
 // debug key of the computer that builds
 def signingKey = System.getenv("HALO_ANDROID_KEYSTORE")
+def signingPassword = System.getenv("HALO_ANDROID_KEYSTORE_PASSWORD")
+def signingAlias = System.getenv("HALO_ANDROID_KEY_ALIAS") ?: "halo"
+def signingProperties = new File(rootDir, "signing.properties")
+if (!signingKey && signingProperties.isFile()) {
+    def properties = new Properties()
+    signingProperties.withInputStream { properties.load(it) }
+    signingKey = properties.getProperty("storeFile")
+    signingPassword = properties.getProperty("password")
+    signingAlias = properties.getProperty("keyAlias", "halo")
+}

 android {
    namespace "com.halo.decomp"
@@ -60,9 +73,9 @@ android {
        if (signingKey) {
            halo {
                storeFile file(signingKey)
-                storePassword System.getenv("HALO_ANDROID_KEYSTORE_PASSWORD")
-                keyAlias System.getenv("HALO_ANDROID_KEY_ALIAS") ?: "halo"
-                keyPassword System.getenv("HALO_ANDROID_KEYSTORE_PASSWORD")
+                storePassword signingPassword
+                keyAlias signingAlias
+                keyPassword signingPassword
            }
        }
    }
@@ -35,6 +35,7 @@ import java.nio.channels.FileChannel;
 */
 public class LauncherActivity extends Activity {
    private static final int PICK_IMAGE = 1;
+    private static final String SHARED_DATA_ROOT = "/home/steamos/Documents/HaloCE";

    private File dataRoot;
    private TextView status;
@@ -46,6 +47,17 @@ public class LauncherActivity extends Activity {
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        dataRoot = getExternalFilesDir(null);
+        // the Steam Frame: Lepton empties the app's own folders whenever it
+        // starts again; the game's data lives in the SteamOS user's
+        // Documents instead, whenever they can be written, so that a disc
+        // image imported here stays too (port/android/STEAM_FRAME.md; the
+        // same choice as host_main.c's)
+        File shared = new File(SHARED_DATA_ROOT);
+        if (shared.getParentFile().canWrite() || shared.canWrite()) {
+            shared.mkdirs();
+            if (shared.canWrite())
+                dataRoot = shared;
+        }
        // created by the app, so that files pushed into it with adb stay
        // readable (a directory adb creates there belongs to the shell user)
        if (dataRoot != null)
@@ -68,6 +68,9 @@ int host_sdl_gl_swap_window(unsigned int window);
 int host_sdl_poll_event(void *event);
 int host_sdl_set_clipboard_text(const char *text);
 void host_sdl_get_clipboard_text(char *buffer, unsigned int size);
+/* the keyboard's keys by name (the controls' bindings, xinput_sdl.c) */
+void host_sdl_scancode_name(int scancode, char *buffer, unsigned int size);
+int host_sdl_scancode_from_name(const char *name);
 int host_sdl_show_toast(const char *message, int duration, int gravity, int x, int y);
 int host_sdl_show_simple_message_box(unsigned int flags, const char *title, const char *message);
 int host_sdl_get_gamepads(unsigned int *ids, int capacity);
@@ -116,7 +119,9 @@ headset before the game started, and set HALO_VR); 0 on failure */
 int host_xr_initialize(struct halo_xr_info *info, float wanted_refresh_rate);
 /* waits for the next frame and reports the predicted poses */
 int host_xr_begin_frame(struct halo_xr_frame *frame);
-/* copies a render target texture (0: clears) into a layer's image */
+/* copies a render target texture (0: clears) into a layer's image: 0 not
+copied, 1 copied with the GL state put back, 2 copied with the copy's GL
+state left (the deferred copies, host_xr.c), which the game sets again */
 int host_xr_copy_layer(int layer, unsigned int texture, int clear_alpha);
 /* the same for part of the texture: left, top, right, bottom, 0..1 from its
 top left */
@@ -130,6 +135,11 @@ into a layer's image, opaque */
 int host_xr_copy_layer_array(int layer, unsigned int texture, int array_layer);
 /* darkens the eye images from their edges, strength 0..1 (0: off) */
 void host_xr_set_vignette(float strength);
+/* the refresh rates the headset offers (Hz, at most maximum of them; 0 when
+it lets none be chosen), and the one it runs at (0: unknown); and asking
+for the highest offered at or below wanted (0: the highest) */
+int host_xr_refresh_rates(float *rates, int maximum, float *current);
+void host_xr_set_refresh_rate(float wanted);

 /* ---------- Android */

@@ -39,6 +39,19 @@ const char *SDL_GetError(void)
 	return buffer;
 }

+const char *SDL_GetScancodeName(SDL_Scancode scancode)
+{
+	static __thread char buffer[64];
+
+	host_sdl_scancode_name((int)scancode, buffer, sizeof(buffer));
+	return buffer;
+}
+
+SDL_Scancode SDL_GetScancodeFromName(const char *name)
+{
+	return (SDL_Scancode)host_sdl_scancode_from_name(name);
+}
+
 Uint64 SDL_GetTicks(void)
 {
 	return (Uint64)host_sdl_ticks();
@@ -92,6 +92,7 @@ void *host_resolve_import(const char *name);
 /* ---------- SDL / GL (host_sdl.c, host_gl.c) */

 void *host_gl_resolve(const char *name);
+int host_gl_quiet_trace_markers(void);

 /* ---------- VR (host_xr.c) */

@@ -11,8 +11,52 @@ already have host types by then. Only strings need copying back.
 #include <EGL/egl.h>
 #include <GLES3/gl32.h>
 #include <GLES2/gl2ext.h>
+#include <dirent.h>
 #include <dlfcn.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
 #include <string.h>
+#include <unistd.h>
+
+/* Valve's Mesa (the Steam Frame's Lepton) writes a marker to the kernel's
+trace_marker around every flush and context switch, a couple of hundred a
+frame, whether or not anything traces. The descriptors it holds open on that
+file are pointed at /dev/null instead (not closed: a reused descriptor would
+take the markers elsewhere). After astromaddie/HaloCE-VR (CC0). Returns how
+many were. */
+int host_gl_quiet_trace_markers(void)
+{
+	DIR *directory = opendir("/proc/self/fd");
+	struct dirent *entry;
+	int quieted = 0, null_fd;
+
+	if (!directory)
+		return 0;
+	null_fd = open("/dev/null", O_WRONLY | O_CLOEXEC);
+	while (null_fd >= 0 && (entry = readdir(directory)) != NULL)
+	{
+		char link[64], target[256];
+		ssize_t length;
+		int fd = atoi(entry->d_name);
+
+		if (entry->d_name[0] < '0' || entry->d_name[0] > '9' || fd == null_fd)
+			continue;
+		snprintf(link, sizeof(link), "/proc/self/fd/%d", fd);
+		length = readlink(link, target, sizeof(target) - 1);
+		if (length <= 0)
+			continue;
+		target[length] = 0;
+		if (strstr(target, "tracing/trace_marker") && dup3(null_fd, fd, O_CLOEXEC) == fd)
+			quieted++;
+	}
+	if (null_fd >= 0)
+		close(null_fd);
+	closedir(directory);
+	if (quieted)
+		host_logf(HOST_LOG_INFO, "trace markers: %d descriptors to /dev/null", quieted);
+	return quieted;
+}

 void *host_gl_resolve(const char *name)
 {
@@ -88,14 +132,13 @@ half-drawn targets out of tile memory, for every lens flare. */
 static GLuint counter_snapshots[COUNTER_SNAPSHOTS];
 static uint32_t counter_snapshot_sizes[COUNTER_SNAPSHOTS];

+/* (the copy bindings are left unbound after: the renderer binds them itself
+for each copy. Asking GL what they were would wait for Mesa's GL thread, on
+the Frame, to run everything queued) */
 void host_gl_counters_snapshot(uint32_t buffer, uint32_t size, uint32_t slot)
 {
-	GLint read_binding = 0, write_binding = 0;
-
 	if (slot >= COUNTER_SNAPSHOTS || !buffer || !size)
 		return;
-	glGetIntegerv(GL_COPY_READ_BUFFER_BINDING, &read_binding);
-	glGetIntegerv(GL_COPY_WRITE_BUFFER_BINDING, &write_binding);
 	if (!counter_snapshots[slot])
 		glGenBuffers(1, &counter_snapshots[slot]);
 	glBindBuffer(GL_COPY_WRITE_BUFFER, counter_snapshots[slot]);
@@ -108,19 +151,17 @@ void host_gl_counters_snapshot(uint32_t buffer, uint32_t size, uint32_t slot)
 	glMemoryBarrier(GL_ATOMIC_COUNTER_BARRIER_BIT | GL_BUFFER_UPDATE_BARRIER_BIT);
 	glBindBuffer(GL_COPY_READ_BUFFER, buffer);
 	glCopyBufferSubData(GL_COPY_READ_BUFFER, GL_COPY_WRITE_BUFFER, 0, 0, size);
-	glBindBuffer(GL_COPY_READ_BUFFER, (GLuint)read_binding);
-	glBindBuffer(GL_COPY_WRITE_BUFFER, (GLuint)write_binding);
+	glBindBuffer(GL_COPY_READ_BUFFER, 0);
+	glBindBuffer(GL_COPY_WRITE_BUFFER, 0);
 }

 /* copies a snapshot out; its frame must be finished (host_gl_wait_frame) */
 int host_gl_counters_read(uint32_t slot, void *out, uint32_t size)
 {
-	GLint write_binding = 0;
 	const void *mapping;

 	if (slot >= COUNTER_SNAPSHOTS || !counter_snapshots[slot] || size > counter_snapshot_sizes[slot])
 		return 0;
-	glGetIntegerv(GL_COPY_WRITE_BUFFER_BINDING, &write_binding);
 	glBindBuffer(GL_COPY_WRITE_BUFFER, counter_snapshots[slot]);
 	mapping = glMapBufferRange(GL_COPY_WRITE_BUFFER, 0, size, GL_MAP_READ_BIT);
 	if (mapping)
@@ -128,7 +169,7 @@ int host_gl_counters_read(uint32_t slot, void *out, uint32_t size)
 		memcpy(out, mapping, size);
 		glUnmapBuffer(GL_COPY_WRITE_BUFFER);
 	}
-	glBindBuffer(GL_COPY_WRITE_BUFFER, (GLuint)write_binding);
+	glBindBuffer(GL_COPY_WRITE_BUFFER, 0);
 	return mapping != NULL;
 }

@@ -90,6 +90,8 @@ int host_errno(void)

 static char data_root[512];
 static char save_root[512];
+/* where a device that empties the app's folders keeps the game's data */
+#define SHARED_DATA_ROOT "/home/steamos/Documents/HaloCE"

 void host_android_path(int which, char *buffer, uint32_t size)
 {
@@ -269,6 +271,12 @@ static void *game_main(void *unused)
 	external = SDL_GetAndroidExternalStoragePath();
 	if (!external)
 		host_fatal("Android storage is unavailable: %s", SDL_GetError());
+	/* the Steam Frame: Lepton empties the app's own folders whenever it
+	starts again; the game's data lives in the SteamOS user's Documents
+	instead, whenever they can be written (port/android/STEAM_FRAME.md; the
+	same choice as LauncherActivity's, which makes the folder) */
+	if (access(SHARED_DATA_ROOT, W_OK) == 0)
+		external = SHARED_DATA_ROOT;
 	snprintf(data_root, sizeof(data_root), "%s", external);
 	snprintf(save_root, sizeof(save_root), "%s/save", external);
 	/* readable by adb (the shell user), for managing saves */
@@ -293,6 +301,19 @@ static void *game_main(void *unused)
 	environment_set(&environment, "HALO_SAVE_ROOT", save_root);
 	time_zone(zone, sizeof(zone));
 	environment_set(&environment, "TZ", zone);
+	/* internet play's MQTT brokers (network.brokers_file): the APK's list,
+	written beside config.toml at each start, as a desktop update replaces
+	the file beside its game */
+	{
+		size_t brokers_size = 0;
+		void *brokers = SDL_LoadFile("brokers.txt", &brokers_size);
+
+		snprintf(path, sizeof(path), "%s/brokers.txt", data_root);
+		if (!brokers || !SDL_SaveFile(path, brokers, brokers_size))
+			host_logf(HOST_LOG_ERROR, "cannot write %s: %s", path, SDL_GetError());
+		SDL_free(brokers);
+	}
+	snprintf(path, sizeof(path), "%s/config.toml", data_root);

 	image = SDL_LoadFile("halo_guest.elf", &image_size);
 	if (!image)
@@ -305,6 +326,26 @@ static void *game_main(void *unused)
 	ranges: the headset's runtime, loaded by the probe, maps its libraries
 	wherever there is room, the Xbox window at 0x80000000 included */
 	snprintf(path, sizeof(path), "%s/config.toml", data_root);
+	{
+		/* (debug.gl_thread: Mesa's GL thread on or off, as the driver's
+		mesa_glthread, before the GL context is made; -1 leaves it be) */
+		double gl_thread = config_number(path, "debug.gl_thread", -1.0);
+
+		if (gl_thread >= 0.0)
+		{
+			setenv("mesa_glthread", gl_thread != 0.0 ? "true" : "false", 1);
+			host_logf(HOST_LOG_INFO, "Mesa's GL thread %s (debug.gl_thread)", gl_thread != 0.0 ? "on" : "off");
+		}
+	}
+	{
+		/* (debug.xr_deferred_copies: the headset's layer copies deferred,
+		host_xr.c, or one by one; -1 as the runtime has it, deferred on
+		SteamVR) */
+		double deferred = config_number(path, "debug.xr_deferred_copies", -1.0);
+
+		if (deferred >= 0.0)
+			setenv("HALO_XR_DEFERRED", deferred != 0.0 ? "1" : "0", 1);
+	}
 	{
 		int eye_width, eye_height;

@@ -98,6 +98,16 @@ void host_sdl_get_error(char *buffer, uint32_t size)
 	SDL_strlcpy(buffer, SDL_GetError(), size);
 }

+void host_sdl_scancode_name(int32_t scancode, char *buffer, uint32_t size)
+{
+	SDL_strlcpy(buffer, SDL_GetScancodeName((SDL_Scancode)scancode), size);
+}
+
+int32_t host_sdl_scancode_from_name(const char *name)
+{
+	return (int32_t)SDL_GetScancodeFromName(name);
+}
+
 int64_t host_sdl_ticks(void)
 {
 	return (int64_t)SDL_GetTicks();
@@ -141,7 +151,11 @@ uint32_t host_sdl_gl_create_context(uint32_t window)
 {
 	SDL_Window *object = handle_get(window, _handle_window);

-	return object ? handle_new(_handle_context, SDL_GL_CreateContext(object)) : 0;
+	uint32_t context = object ? handle_new(_handle_context, SDL_GL_CreateContext(object)) : 0;
+
+	/* (the driver opens its trace markers with the context) */
+	host_gl_quiet_trace_markers();
+	return context;
 }

 int host_sdl_gl_make_current(uint32_t window, uint32_t context)
@@ -38,6 +38,8 @@ picture; the copy flips them to GL's bottom-up images.
 #include <string.h>
 #include <time.h>
 #include <unistd.h>
+#include <sched.h>
+#include <stdio.h>

 #define XR_USE_PLATFORM_ANDROID
 #define XR_USE_GRAPHICS_API_OPENGL_ES
@@ -56,6 +58,7 @@ struct xr_swapchain
 	GLuint framebuffers[MAXIMUM_SWAPCHAIN_IMAGES];
 	uint32_t acquired_index;
 	int filled; /* this frame */
+	int held;   /* acquired, released only as the frame ends (xr.deferred) */
 };

 struct xr_hand_actions
@@ -102,15 +105,54 @@ static struct
 	XrAction button_b; /* B on the right controller, Y on the left */
 	XrAction menu;
 	XrAction thumbrest;
+	/* the fingers' touch, for the hands drawn (where the runtime has it):
+	the thumb on the stick, a button or the rest, the index on the trigger */
+	XrAction thumb_touch;
+	XrAction index_touch;
+	/* the Steam Frame's controllers' own (XR_VALVE_frame_controller_interaction) */
+	int has_frame_controller;
+	int frame_layout;
+	XrAction button_x;
+	XrAction button_y;
+	XrAction view;
+	XrAction bumper;
+	XrAction dpad[4];
 	XrAction haptic;
 	struct xr_hand_actions hands[HALO_XR_HAND_COUNT];

-	/* where the head and the left hand are this frame (the wrist layer) */
+	/* where the head and the hands are this frame (the wrist layer) */
 	XrPosef head;
-	XrPosef left_grip;
-	int left_grip_valid;
+	XrPosef grips[HALO_XR_HAND_COUNT];
+	int grips_valid[HALO_XR_HAND_COUNT];

 	int has_performance_settings;
+	/* (XR_META_performance_metrics: the compositor's counts, in the log,
+	for telling frames shown late from the game's own pace) */
+	int has_metrics;
+	PFN_xrQueryPerformanceMetricsCounterMETA query_metric;
+	XrPath metric_paths[16];
+	uint32_t metric_count;
+	struct timespec metrics_logged;
+	/* (SteamVR: the frames' thread kept on the fast cores, xr_fast_cores) */
+	int steamvr;
+	int cores_pinned;
+	/* (with the metrics: the time the copies into the layers' images and
+	xrEndFrame took, since the last line, and the frames) */
+	double copy_seconds[HALO_XR_LAYER_COUNT];
+	double end_seconds;
+	double acquire_seconds;
+	double release_seconds;
+	int timed_frames;
+	/* The copies without waits in the frame (SteamVR: HALO_XR_DEFERRED,
+	debug.xr_deferred_copies). Each copy otherwise reads the GL state back
+	to restore it (glGet*), and releases its image at once: with Mesa's GL
+	thread (the Steam Frame's zink) each read waits for the thread to run
+	everything queued, and each release for the GPU to finish it, so the
+	game's one thread stood still for the eyes' whole drawing in the middle
+	of every frame. Deferred, a copy leaves its GL state for the game to set
+	again (host_xr_copy_layer's 2) and keeps its image until the frame ends,
+	where all are released at once. */
+	int deferred;
 	int has_refresh_rate;
 	PFN_xrRequestDisplayRefreshRateFB request_refresh_rate;
 	PFN_xrGetDisplayRefreshRateFB get_refresh_rate;
@@ -122,6 +164,11 @@ static struct
 	GLint rect_uniform;
 	GLint cut_disc_uniform;
 	GLint vignette_uniform;
+	GLint alpha_from_colour_uniform;
+	/* the runtime draws a quad's texels by their alpha alone, ignoring the
+	colour of those with none (SteamVR on the Steam Frame): the game's
+	overlays, whose additive parts have none, get alpha from their colour */
+	int quad_alpha_from_colour;
 	GLint tangents_uniform;
 	float vignette;
 	/* the same copy from a layer of a texture array (the eyes drawn at
@@ -223,6 +270,7 @@ static const char copy_fragment_shader[] =
 	"precision highp float;\n"
 	"uniform sampler2D source;\n"
 	"uniform float cut_disc;\n"
+	"uniform float alpha_from_colour; /* 1: as opaque as it is bright (a quad's, SteamVR) */\n"
 	"uniform float vignette; /* 0..1: the eye images darken from their edges */\n"
 	"uniform vec4 tangents; /* the eye's edges: left, right, down, up */\n"
 	"in vec2 coordinate;\n"
@@ -236,6 +284,8 @@ static const char copy_fragment_shader[] =
 	"{\n"
 	"	vec4 texel = texture(source, coordinate);\n"
 	"	color = vec4(to_linear(texel.rgb), texel.a);\n"
+	"	if (alpha_from_colour > 0.5)\n"
+	"		color.a = max(color.a, max(color.r, max(color.g, color.b)));\n"
 	"	if (cut_disc > 0.5)\n"
 	"	{\n"
 	"		float inside = 1.0 - smoothstep(0.95, 1.0, length(disc));\n"
@@ -326,6 +376,7 @@ static int copy_initialize(void)
 	xr.rect_uniform = glGetUniformLocation(xr.program, "rect");
 	xr.cut_disc_uniform = glGetUniformLocation(xr.program, "cut_disc");
 	xr.vignette_uniform = glGetUniformLocation(xr.program, "vignette");
+	xr.alpha_from_colour_uniform = glGetUniformLocation(xr.program, "alpha_from_colour");
 	xr.tangents_uniform = glGetUniformLocation(xr.program, "tangents");
 	xr.copy_array_layer = -1;
 	{
@@ -538,22 +589,51 @@ struct binding
 	const char *path;
 };

-static void suggest(const char *profile, const struct binding *bindings, int count)
-{
-	XrActionSuggestedBinding suggested[32];
-	XrInteractionProfileSuggestedBinding information = { XR_TYPE_INTERACTION_PROFILE_SUGGESTED_BINDING };
-	int index;
+/* a profile's bindings: those it has to have, and those it may (a path the
+runtime does not know refuses the whole suggestion, which leaves the
+profile with none: then the first alone, as before). Nonzero if taken. */
+#define MAXIMUM_SUGGESTED_BINDINGS 64

-	for (index = 0; index < count && index < 32; index++)
+static int suggest_bindings(const char *profile, const struct binding *bindings, int count,
+	const struct binding *optional, int optional_count)
+{
+	XrActionSuggestedBinding suggested[MAXIMUM_SUGGESTED_BINDINGS];
+	XrInteractionProfileSuggestedBinding information = { XR_TYPE_INTERACTION_PROFILE_SUGGESTED_BINDING };
+	XrResult result;
+	int index, total = 0;
+
+	if (count + optional_count > MAXIMUM_SUGGESTED_BINDINGS)
 	{
-		suggested[index].action = *bindings[index].action;
-		suggested[index].binding = path_from_string(bindings[index].path);
+		host_logf(HOST_LOG_ERROR, "xr: %d bindings for %s, room for %d: the rest left out", count + optional_count,
+			profile, MAXIMUM_SUGGESTED_BINDINGS);
+	}
+	for (index = 0; index < count + optional_count && total < MAXIMUM_SUGGESTED_BINDINGS; index++)
+	{
+		const struct binding *binding = index < count ? &bindings[index] : &optional[index - count];
+
+		suggested[total].action = *binding->action;
+		suggested[total].binding = path_from_string(binding->path);
+		total++;
 	}
 	information.interactionProfile = path_from_string(profile);
 	information.suggestedBindings = suggested;
-	information.countSuggestedBindings = (uint32_t)index;
-	if (!XR_SUCCEEDED(xrSuggestInteractionProfileBindings(xr.instance, &information)))
-		host_logf(HOST_LOG_WARN, "xr: no bindings for %s", profile);
+	information.countSuggestedBindings = (uint32_t)total;
+	result = xrSuggestInteractionProfileBindings(xr.instance, &information);
+	if (XR_SUCCEEDED(result))
+		return 1;
+	if (optional_count > 0)
+	{
+		host_logf(HOST_LOG_WARN, "xr: %s refused with its optional bindings (%d); suggested without them", profile,
+			(int)result);
+		return suggest_bindings(profile, bindings, count, NULL, 0);
+	}
+	host_logf(HOST_LOG_WARN, "xr: no bindings for %s (%d)", profile, (int)result);
+	return 0;
+}
+
+static void suggest(const char *profile, const struct binding *bindings, int count)
+{
+	suggest_bindings(profile, bindings, count, NULL, 0);
 }

 static int actions_initialize(void)
@@ -580,6 +660,16 @@ static int actions_initialize(void)
 	xr.button_b = action_create("button_upper", "B / Y", XR_ACTION_TYPE_BOOLEAN_INPUT);
 	xr.menu = action_create("menu", "Menu", XR_ACTION_TYPE_BOOLEAN_INPUT);
 	xr.thumbrest = action_create("thumbrest", "Thumb rest", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.thumb_touch = action_create("thumb_touch", "Thumb resting", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.index_touch = action_create("index_touch", "Finger on the trigger", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.button_x = action_create("button_x", "X", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.button_y = action_create("button_y", "Y", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.view = action_create("view", "View", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.bumper = action_create("bumper", "Bumper", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.dpad[0] = action_create("dpad_up", "D-pad up", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.dpad[1] = action_create("dpad_down", "D-pad down", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.dpad[2] = action_create("dpad_left", "D-pad left", XR_ACTION_TYPE_BOOLEAN_INPUT);
+	xr.dpad[3] = action_create("dpad_right", "D-pad right", XR_ACTION_TYPE_BOOLEAN_INPUT);
 	xr.haptic = action_create("haptic", "Rumble", XR_ACTION_TYPE_VIBRATION_OUTPUT);

 	{
@@ -644,8 +734,95 @@ static int actions_initialize(void)
 			{ &xr.haptic, "/user/hand/right/output/haptic" },
 		};

-		suggest("/interaction_profiles/oculus/touch_controller", touch, sizeof(touch) / sizeof(touch[0]));
-		suggest("/interaction_profiles/valve/index_controller", index, sizeof(index) / sizeof(index[0]));
+		/* the Steam Frame's controllers, as themselves: the right one has
+		A, B, X, Y and a menu button, the left one a D-pad and a View button
+		(port/android/STEAM_FRAME.md) */
+		static const struct binding frame_controller[] =
+		{
+			{ &xr.grip_pose, "/user/hand/left/input/grip/pose" },
+			{ &xr.grip_pose, "/user/hand/right/input/grip/pose" },
+			{ &xr.aim_pose, "/user/hand/left/input/aim/pose" },
+			{ &xr.aim_pose, "/user/hand/right/input/aim/pose" },
+			{ &xr.trigger, "/user/hand/left/input/trigger/value" },
+			{ &xr.trigger, "/user/hand/right/input/trigger/value" },
+			{ &xr.squeeze, "/user/hand/left/input/squeeze/value" },
+			{ &xr.squeeze, "/user/hand/right/input/squeeze/value" },
+			{ &xr.thumbstick, "/user/hand/left/input/thumbstick" },
+			{ &xr.thumbstick, "/user/hand/right/input/thumbstick" },
+			{ &xr.thumbstick_click, "/user/hand/left/input/thumbstick/click" },
+			{ &xr.thumbstick_click, "/user/hand/right/input/thumbstick/click" },
+			{ &xr.button_a, "/user/hand/right/input/a/click" },
+			{ &xr.button_b, "/user/hand/right/input/b/click" },
+			{ &xr.button_x, "/user/hand/right/input/x/click" },
+			{ &xr.button_y, "/user/hand/right/input/y/click" },
+			{ &xr.menu, "/user/hand/right/input/menu/click" },
+			{ &xr.view, "/user/hand/left/input/view/click" },
+			{ &xr.bumper, "/user/hand/left/input/bumper/click" },
+			{ &xr.bumper, "/user/hand/right/input/bumper/click" },
+			{ &xr.dpad[0], "/user/hand/left/input/dpad_up/click" },
+			{ &xr.dpad[1], "/user/hand/left/input/dpad_down/click" },
+			{ &xr.dpad[2], "/user/hand/left/input/dpad_left/click" },
+			{ &xr.dpad[3], "/user/hand/left/input/dpad_right/click" },
+			{ &xr.haptic, "/user/hand/left/output/haptic" },
+			{ &xr.haptic, "/user/hand/right/output/haptic" },
+		};
+
+		/* the fingers' touch, as each profile has it (after HaloCE-Quest-VR,
+		CC0; the Frame's from Valve's "Steam Frame Input" page): optional, a
+		profile refusing them keeps its buttons */
+		static const struct binding touch_fingers[] =
+		{
+			{ &xr.thumb_touch, "/user/hand/left/input/thumbstick/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/thumbstick/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/thumbrest/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/thumbrest/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/x/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/y/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/a/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/b/touch" },
+			{ &xr.index_touch, "/user/hand/left/input/trigger/touch" },
+			{ &xr.index_touch, "/user/hand/right/input/trigger/touch" },
+		};
+		static const struct binding index_fingers[] =
+		{
+			{ &xr.thumb_touch, "/user/hand/left/input/thumbstick/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/thumbstick/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/trackpad/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/trackpad/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/a/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/b/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/a/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/b/touch" },
+			{ &xr.index_touch, "/user/hand/left/input/trigger/touch" },
+			{ &xr.index_touch, "/user/hand/right/input/trigger/touch" },
+		};
+		static const struct binding frame_fingers[] =
+		{
+			{ &xr.thumb_touch, "/user/hand/left/input/thumbstick/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/thumbstick/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/a/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/b/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/x/touch" },
+			{ &xr.thumb_touch, "/user/hand/right/input/y/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/dpad_up/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/dpad_down/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/dpad_left/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/dpad_right/touch" },
+			{ &xr.thumb_touch, "/user/hand/left/input/view/touch" },
+			{ &xr.index_touch, "/user/hand/left/input/trigger/touch" },
+			{ &xr.index_touch, "/user/hand/right/input/trigger/touch" },
+		};
+
+		if (xr.has_frame_controller)
+		{
+			suggest_bindings("/interaction_profiles/valve/frame_controller_valve", frame_controller,
+				sizeof(frame_controller) / sizeof(frame_controller[0]), frame_fingers,
+				sizeof(frame_fingers) / sizeof(frame_fingers[0]));
+		}
+		suggest_bindings("/interaction_profiles/oculus/touch_controller", touch, sizeof(touch) / sizeof(touch[0]),
+			touch_fingers, sizeof(touch_fingers) / sizeof(touch_fingers[0]));
+		suggest_bindings("/interaction_profiles/valve/index_controller", index, sizeof(index) / sizeof(index[0]),
+			index_fingers, sizeof(index_fingers) / sizeof(index_fingers[0]));
 		suggest("/interaction_profiles/khr/simple_controller", simple, sizeof(simple) / sizeof(simple[0]));
 	}

@@ -688,6 +865,21 @@ static int action_boolean(XrAction action, int hand)
 	return state.currentState != XR_FALSE;
 }

+/* (and whether the runtime gives the action for the hand at all) */
+static int action_boolean_active(XrAction action, int hand, int *active)
+{
+	XrActionStateGetInfo information = { XR_TYPE_ACTION_STATE_GET_INFO };
+	XrActionStateBoolean state = { XR_TYPE_ACTION_STATE_BOOLEAN };
+
+	*active = 0;
+	information.action = action;
+	information.subactionPath = xr.hands[hand].path;
+	if (!XR_SUCCEEDED(xrGetActionStateBoolean(xr.session, &information, &state)) || !state.isActive)
+		return 0;
+	*active = 1;
+	return state.currentState != XR_FALSE;
+}
+
 static int action_vector(XrAction action, int hand, float vector[2])
 {
 	XrActionStateGetInfo information = { XR_TYPE_ACTION_STATE_GET_INFO };
@@ -713,6 +905,30 @@ static void hands_read(struct halo_xr_frame *frame)
 	sync.activeActionSets = &active;
 	if (!XR_SUCCEEDED(xrSyncActions(xr.session, &sync)))
 		return;
+	{
+		/* (the controllers' profile the runtime chose, in the log as it
+		changes) */
+		static XrPath logged[HALO_XR_HAND_COUNT];
+
+		for (hand = 0; hand < HALO_XR_HAND_COUNT; hand++)
+		{
+			XrInteractionProfileState state = { XR_TYPE_INTERACTION_PROFILE_STATE };
+
+			if (XR_SUCCEEDED(xrGetCurrentInteractionProfile(xr.session, xr.hands[hand].path, &state)) &&
+				state.interactionProfile != logged[hand])
+			{
+				char name[XR_MAX_PATH_LENGTH] = "none";
+				uint32_t length = 0;
+
+				logged[hand] = state.interactionProfile;
+				if (state.interactionProfile != XR_NULL_PATH)
+					xrPathToString(xr.instance, state.interactionProfile, sizeof(name), &length, name);
+				if (hand == HALO_XR_HAND_RIGHT)
+					xr.frame_layout = strstr(name, "frame_controller") != NULL;
+				host_logf(HOST_LOG_INFO, "xr: the %s hand's controller: %s", hand ? "right" : "left", name);
+			}
+		}
+	}
 	for (hand = 0; hand < HALO_XR_HAND_COUNT; hand++)
 	{
 		struct halo_xr_hand *out = &frame->hands[hand];
@@ -730,11 +946,8 @@ static void hands_read(struct halo_xr_frame *frame)
 		{
 			out->flags = flags_from_location(location.locationFlags);
 			pose_from_xr(&out->grip, &location.pose);
-			if (hand == HALO_XR_HAND_LEFT)
-			{
-				xr.left_grip = location.pose;
-				xr.left_grip_valid = (out->flags & HALO_XR_POSE_VALID) != 0;
-			}
+			xr.grips[hand] = location.pose;
+			xr.grips_valid[hand] = (out->flags & HALO_XR_POSE_VALID) != 0;
 		}
 		location.locationFlags = 0;
 		if (XR_SUCCEEDED(xrLocateSpace(xr.hands[hand].aim_space, xr.local_space,
@@ -757,7 +970,42 @@ static void hands_read(struct halo_xr_frame *frame)
 			(action_boolean(xr.menu, hand) ? HALO_XR_BUTTON_MENU : 0) |
 			(action_boolean(xr.thumbrest, hand) ? HALO_XR_BUTTON_THUMBREST : 0) |
 			(out->trigger > 0.5f ? HALO_XR_BUTTON_TRIGGER : 0) |
-			(out->squeeze > 0.5f ? HALO_XR_BUTTON_SQUEEZE : 0);
+			(out->squeeze > 0.5f ? HALO_XR_BUTTON_SQUEEZE : 0) |
+			(action_boolean(xr.view, hand) ? HALO_XR_BUTTON_VIEW : 0) |
+			(action_boolean(xr.bumper, hand) ? HALO_XR_BUTTON_BUMPER : 0) |
+			(action_boolean(xr.dpad[0], hand) ? HALO_XR_BUTTON_DPAD_UP : 0) |
+			(action_boolean(xr.dpad[1], hand) ? HALO_XR_BUTTON_DPAD_DOWN : 0) |
+			(action_boolean(xr.dpad[2], hand) ? HALO_XR_BUTTON_DPAD_LEFT : 0) |
+			(action_boolean(xr.dpad[3], hand) ? HALO_XR_BUTTON_DPAD_RIGHT : 0);
+		{
+			/* the fingers' touch, and whether there is any */
+			int thumb_active = 0, index_active = 0;
+
+			if (action_boolean_active(xr.thumb_touch, hand, &thumb_active))
+				out->buttons |= HALO_XR_BUTTON_THUMB_TOUCH;
+			if (action_boolean_active(xr.index_touch, hand, &index_active))
+				out->buttons |= HALO_XR_BUTTON_INDEX_TOUCH;
+			if (thumb_active)
+				out->buttons |= HALO_XR_BUTTON_TOUCH_KNOWN;
+		}
+	}
+	frame->controller_layout = xr.frame_layout ? HALO_XR_LAYOUT_FRAME : HALO_XR_LAYOUT_TOUCH;
+	if (xr.frame_layout)
+	{
+		/* (the Frame's right X, Y and menu button: the game's X, Y and Start,
+		which the Quest has on the left) */
+		struct halo_xr_hand *left = &frame->hands[HALO_XR_HAND_LEFT];
+		struct halo_xr_hand *right = &frame->hands[HALO_XR_HAND_RIGHT];
+
+		if (action_boolean(xr.button_x, HALO_XR_HAND_RIGHT))
+			left->buttons |= HALO_XR_BUTTON_A;
+		if (action_boolean(xr.button_y, HALO_XR_HAND_RIGHT))
+			left->buttons |= HALO_XR_BUTTON_B;
+		if (right->buttons & HALO_XR_BUTTON_MENU)
+		{
+			right->buttons &= ~HALO_XR_BUTTON_MENU;
+			left->buttons |= HALO_XR_BUTTON_MENU;
+		}
 	}
 }

@@ -774,6 +1022,13 @@ static void refresh_rate_choose(float wanted)
 	{
 		return;
 	}
+	{
+		char line[128] = "";
+
+		for (index = 0; index < count; index++)
+			snprintf(line + strlen(line), sizeof(line) - strlen(line), " %.0f", rates[index]);
+		host_logf(HOST_LOG_INFO, "xr: refresh rates offered:%s Hz", line);
+	}
 	/* the highest rate not above the one wanted (0: the highest) */
 	for (index = 0; index < count; index++)
 	{
@@ -790,10 +1045,18 @@ On the back of the left wrist, like a watch: behind the palm, where the
 grip pose is, and out of the back of the hand. In the left grip pose -Z
 runs to the fingers, +Y up the handle and -X out of the back of the hand;
 the layer faces -X with its top towards the elbow, as the wrist turned to
-the eyes reads it. Shown only while it is. */
+the eyes reads it. Shown only while it is. Left-handed (wrist_hand), on the
+right wrist, as the mirror image: there +X runs out of the back of the
+hand. */

 #define WRIST_IMAGE_SIZE 512
 #define CROSSHAIR_IMAGE_SIZE 256
+/* the names layer: HALO_XR_MAXIMUM_NAMES slots of 4:1, one over another */
+#define NAMES_IMAGE_WIDTH 512
+#define NAMES_IMAGE_HEIGHT (NAMES_IMAGE_WIDTH / 4 * HALO_XR_MAXIMUM_NAMES)
+/* a name's slot, as the game draws it: wider than its image's 4:1 (the
+game's 640x480 drawn square): the height a slot shows at, to its width */
+#define NAME_SLOT_ASPECT (30.0f / 160.0f)
 #define WRIST_BEHIND_PALM 0.05f
 #define WRIST_DOWN_HANDLE 0.02f
 #define WRIST_ABOVE_HAND 0.04f
@@ -824,26 +1087,32 @@ static void quaternion_rotate_vector(const XrQuaternionf *q, const XrVector3f *v

 static int wrist_pose(const struct halo_xr_submit *submit, XrPosef *pose)
 {
-	/* the layer's axes in the grip's: x = -Y, y = +Z, z = -X, so the
-	layer's right and down, as it is read, are the grip's -Y and -Z */
-	static const XrQuaternionf layer_in_grip = { 0.5f, -0.5f, -0.5f, 0.5f };
-	const XrVector3f offset = { -WRIST_ABOVE_HAND, -WRIST_DOWN_HANDLE - submit->wrist_right,
-		WRIST_BEHIND_PALM - submit->wrist_down };
+	/* the layer's axes in the left grip's: x = -Y, y = +Z, z = -X, so the
+	layer's right and down, as it is read, are the grip's -Y and -Z; in the
+	right grip's x = +Y, y = +Z, z = +X (the mirror image, read the right
+	way round: its x turned back) */
+	static const XrQuaternionf layer_in_left_grip = { 0.5f, -0.5f, -0.5f, 0.5f };
+	static const XrQuaternionf layer_in_right_grip = { 0.5f, 0.5f, 0.5f, 0.5f };
+	int right = submit->wrist_hand == HALO_XR_HAND_RIGHT;
+	const XrPosef *grip = &xr.grips[right ? HALO_XR_HAND_RIGHT : HALO_XR_HAND_LEFT];
+	const XrVector3f offset = { right ? WRIST_ABOVE_HAND : -WRIST_ABOVE_HAND,
+		-WRIST_DOWN_HANDLE - submit->wrist_right, WRIST_BEHIND_PALM - submit->wrist_down };
 	const XrVector3f layer_normal = { 0.0f, 0.0f, 1.0f };
-	/* clockwise as read: about the layer's normal, negatively */
-	float half_turn = -submit->wrist_turn * WRIST_PI / 360.0f;
+	/* clockwise as read: about the layer's normal, negatively (the mirror
+	image's the other way) */
+	float half_turn = (right ? 1.0f : -1.0f) * submit->wrist_turn * WRIST_PI / 360.0f;
 	XrQuaternionf turn = { 0.0f, 0.0f, sinf(half_turn), cosf(half_turn) };
 	XrQuaternionf unturned;
 	XrVector3f moved, normal, to_eyes;
 	float distance;

-	if (!xr.left_grip_valid)
+	if (!xr.grips_valid[right ? HALO_XR_HAND_RIGHT : HALO_XR_HAND_LEFT])
 		return 0;
-	quaternion_rotate_vector(&xr.left_grip.orientation, &offset, &moved);
-	pose->position.x = xr.left_grip.position.x + moved.x;
-	pose->position.y = xr.left_grip.position.y + moved.y;
-	pose->position.z = xr.left_grip.position.z + moved.z;
-	quaternion_multiply(&xr.left_grip.orientation, &layer_in_grip, &unturned);
+	quaternion_rotate_vector(&grip->orientation, &offset, &moved);
+	pose->position.x = grip->position.x + moved.x;
+	pose->position.y = grip->position.y + moved.y;
+	pose->position.z = grip->position.z + moved.z;
+	quaternion_multiply(&grip->orientation, right ? &layer_in_right_grip : &layer_in_left_grip, &unturned);
 	quaternion_multiply(&unturned, &turn, &pose->orientation);

 	quaternion_rotate_vector(&pose->orientation, &layer_normal, &normal);
@@ -889,6 +1158,12 @@ int host_xr_probe(float resolution_scale, int *eye_width, int *eye_height)
 	/* the loader and the runtime keep the activity */
 	activity = (*environment)->NewGlobalRef(environment, activity);

+	/* (The Steam Frame lists an implicit API layer of its own for Vulkan
+	apps, XR_APILAYER_VALVE_fdm_injection, whose library an app cannot load
+	from its namespace, failing xrCreateInstance; the Android loader reads
+	no variable to turn it off, so the app carries a pass-through layer
+	under that library's name: port/android/xr_layer/fdm_injection_stub.c) */
+
 	if (!XR_SUCCEEDED(xrGetInstanceProcAddr(XR_NULL_HANDLE, "xrInitializeLoaderKHR",
 		(PFN_xrVoidFunction *)&initialize_loader)) || !initialize_loader)
 	{
@@ -916,6 +1191,23 @@ int host_xr_probe(float resolution_scale, int *eye_width, int *eye_height)
 		extensions[index].next = NULL;
 	}
 	xrEnumerateInstanceExtensionProperties(NULL, extension_count, &extension_count, extensions);
+	{
+		/* (the runtime's extensions, in the log: what a headset offers) */
+		char line[512] = "";
+
+		for (index = 0; index < extension_count; index++)
+		{
+			if (strlen(line) + strlen(extensions[index].extensionName) + 2 >= sizeof(line))
+			{
+				host_logf(HOST_LOG_INFO, "xr: extensions %s", line);
+				line[0] = 0;
+			}
+			strcat(line, " ");
+			strcat(line, extensions[index].extensionName);
+		}
+		if (line[0])
+			host_logf(HOST_LOG_INFO, "xr: extensions %s", line);
+	}
 	if (!has_extension(extensions, extension_count, XR_KHR_OPENGL_ES_ENABLE_EXTENSION_NAME))
 	{
 		host_logf(HOST_LOG_ERROR, "xr: the runtime has no OpenGL ES support");
@@ -927,9 +1219,15 @@ int host_xr_probe(float resolution_scale, int *eye_width, int *eye_height)
 	xr.has_performance_settings = has_extension(extensions, extension_count, XR_EXT_PERFORMANCE_SETTINGS_EXTENSION_NAME);
 	if (xr.has_performance_settings)
 		enabled[enabled_count++] = XR_EXT_PERFORMANCE_SETTINGS_EXTENSION_NAME;
+	xr.has_frame_controller = has_extension(extensions, extension_count, "XR_VALVE_frame_controller_interaction");
+	if (xr.has_frame_controller)
+		enabled[enabled_count++] = "XR_VALVE_frame_controller_interaction";
 	xr.has_refresh_rate = has_extension(extensions, extension_count, XR_FB_DISPLAY_REFRESH_RATE_EXTENSION_NAME);
 	if (xr.has_refresh_rate)
 		enabled[enabled_count++] = XR_FB_DISPLAY_REFRESH_RATE_EXTENSION_NAME;
+	xr.has_metrics = has_extension(extensions, extension_count, XR_META_PERFORMANCE_METRICS_EXTENSION_NAME);
+	if (xr.has_metrics)
+		enabled[enabled_count++] = XR_META_PERFORMANCE_METRICS_EXTENSION_NAME;

 	android.applicationVM = machine;
 	android.applicationActivity = activity;
@@ -954,6 +1252,23 @@ int host_xr_probe(float resolution_scale, int *eye_width, int *eye_height)
 	}
 	xrGetSystemProperties(xr.instance, xr.system, &properties);
 	strncpy(xr.system_name, properties.systemName, sizeof(xr.system_name) - 1);
+	{
+		/* (SteamVR: the quads' alpha from their colour; HALO_XR_QUAD_ALPHA
+		"colour" or "keep" says otherwise, for trying) */
+		XrInstanceProperties instance = { XR_TYPE_INSTANCE_PROPERTIES };
+		const char *choice = getenv("HALO_XR_QUAD_ALPHA");
+
+		if (XR_SUCCEEDED(xrGetInstanceProperties(xr.instance, &instance)))
+		{
+			xr.quad_alpha_from_colour = strstr(instance.runtimeName, "SteamVR") != NULL;
+			xr.steamvr = xr.quad_alpha_from_colour;
+			host_logf(HOST_LOG_INFO, "xr: runtime %s", instance.runtimeName);
+		}
+		if (choice)
+			xr.quad_alpha_from_colour = !strcmp(choice, "colour");
+		if (xr.quad_alpha_from_colour)
+			host_logf(HOST_LOG_INFO, "xr: the overlays' alpha from their colour");
+	}

 	views[0].type = views[1].type = XR_TYPE_VIEW_CONFIGURATION_VIEW;
 	views[0].next = views[1].next = NULL;
@@ -1032,8 +1347,15 @@ int host_xr_initialize(struct halo_xr_info *info, float wanted_refresh_rate)
 	{
 		int size = layer == HALO_XR_LAYER_WRIST || layer == HALO_XR_LAYER_SCOPE ? WRIST_IMAGE_SIZE :
 			layer == HALO_XR_LAYER_CROSSHAIR ? CROSSHAIR_IMAGE_SIZE : 0;
+		int width = size ? size : xr.eye_width;
+		int height = size ? size : xr.eye_height;

-		if (!swapchain_create(&xr.swapchains[layer], size ? size : xr.eye_width, size ? size : xr.eye_height))
+		if (layer == HALO_XR_LAYER_NAMES)
+		{
+			width = NAMES_IMAGE_WIDTH;
+			height = NAMES_IMAGE_HEIGHT;
+		}
+		if (!swapchain_create(&xr.swapchains[layer], width, height))
 			return 0;
 	}
 	if (!copy_initialize() || !actions_initialize())
@@ -1053,6 +1375,29 @@ int host_xr_initialize(struct halo_xr_info *info, float wanted_refresh_rate)
 			xr.get_refresh_rate(xr.session, &info->refresh_rate);
 	}

+	/* (the runtime's GL binding brings contexts of its own, with their own
+	trace markers: host_gl.c) */
+	host_gl_quiet_trace_markers();
+
+	if (xr.has_metrics)
+	{
+		PFN_xrEnumeratePerformanceMetricsCounterPathsMETA enumerate = NULL;
+		PFN_xrSetPerformanceMetricsStateMETA set_state = NULL;
+		XrPerformanceMetricsStateMETA state = { XR_TYPE_PERFORMANCE_METRICS_STATE_META };
+
+		xrGetInstanceProcAddr(xr.instance, "xrEnumeratePerformanceMetricsCounterPathsMETA",
+			(PFN_xrVoidFunction *)&enumerate);
+		xrGetInstanceProcAddr(xr.instance, "xrSetPerformanceMetricsStateMETA", (PFN_xrVoidFunction *)&set_state);
+		xrGetInstanceProcAddr(xr.instance, "xrQueryPerformanceMetricsCounterMETA",
+			(PFN_xrVoidFunction *)&xr.query_metric);
+		state.enabled = XR_TRUE;
+		xr.has_metrics = enumerate && set_state && xr.query_metric &&
+			XR_SUCCEEDED(enumerate(xr.instance, 16, &xr.metric_count, xr.metric_paths)) &&
+			XR_SUCCEEDED(set_state(xr.session, &state));
+		host_logf(HOST_LOG_INFO, "xr: performance metrics %s (%u counters)", xr.has_metrics ? "on" : "off",
+			xr.has_metrics ? xr.metric_count : 0);
+	}
+
 	if (xr.has_performance_settings)
 	{
 		/* the game's one busy thread and its GPU work both need the clocks
@@ -1069,6 +1414,16 @@ int host_xr_initialize(struct halo_xr_info *info, float wanted_refresh_rate)
 		}
 	}

+	{
+		/* (deferred on SteamVR; HALO_XR_DEFERRED "1" or "0" says otherwise:
+		debug.xr_deferred_copies, host_main.c) */
+		const char *choice = getenv("HALO_XR_DEFERRED");
+
+		xr.deferred = choice && *choice ? atoi(choice) != 0 : xr.steamvr;
+		host_logf(HOST_LOG_INFO, "xr: layer copies %s", xr.deferred ?
+			"deferred (no waits for the GL thread or the GPU in the frame)" : "restored and released one by one");
+	}
+
 	info->eye_width = xr.eye_width;
 	info->eye_height = xr.eye_height;
 	info->overlay_width = xr.eye_width;
@@ -1205,7 +1560,7 @@ int host_xr_begin_frame(struct halo_xr_frame *frame)
 		pose_from_xr(&frame->head, &head.pose);
 		xr.head = head.pose;
 	}
-	xr.left_grip_valid = 0;
+	xr.grips_valid[HALO_XR_HAND_LEFT] = xr.grips_valid[HALO_XR_HAND_RIGHT] = 0;
 	if (xr.focused)
 		hands_read(frame);
 	return 1;
@@ -1232,8 +1587,30 @@ int host_xr_copy_layer_array(int layer, uint32_t texture, int array_layer)

 /* copies part of a render target (left, top, right, bottom, 0..1 from its
 top left) into a layer's image */
+static double seconds_now(void)
+{
+	struct timespec now;
+
+	clock_gettime(CLOCK_MONOTONIC, &now);
+	return (double)now.tv_sec + (double)now.tv_nsec * 1e-9;
+}
+
+static int copy_layer_region(int layer, uint32_t texture, int clear_alpha, float left, float top, float right,
+	float bottom);
+
 int host_xr_copy_layer_region(int layer, uint32_t texture, int clear_alpha, float left, float top, float right,
 	float bottom)
+{
+	double start = xr.has_metrics ? seconds_now() : 0.0;
+	int copied = copy_layer_region(layer, texture, clear_alpha, left, top, right, bottom);
+
+	if (xr.has_metrics && layer >= 0 && layer < HALO_XR_LAYER_COUNT)
+		xr.copy_seconds[layer] += seconds_now() - start;
+	return copied;
+}
+
+static int copy_layer_region(int layer, uint32_t texture, int clear_alpha, float left, float top, float right,
+	float bottom)
 {
 	struct xr_swapchain *swapchain;
 	XrSwapchainImageAcquireInfo acquire = { XR_TYPE_SWAPCHAIN_IMAGE_ACQUIRE_INFO };
@@ -1245,17 +1622,27 @@ int host_xr_copy_layer_region(int layer, uint32_t texture, int clear_alpha, floa
 		return 0;
 	swapchain = &xr.swapchains[layer];
 	if (swapchain->filled)
-		return 1;
-	if (!xr_ok(xrAcquireSwapchainImage(swapchain->handle, &acquire, &swapchain->acquired_index),
-		"xrAcquireSwapchainImage"))
-	{
-		return 0;
-	}
+		return xr.deferred ? 2 : 1;
 	wait.timeout = XR_INFINITE_DURATION;
-	if (!xr_ok(xrWaitSwapchainImage(swapchain->handle, &wait), "xrWaitSwapchainImage"))
-		return 0;
+	{
+		double start = xr.has_metrics ? seconds_now() : 0.0;

-	gl_save(&saved);
+		if (!xr_ok(xrAcquireSwapchainImage(swapchain->handle, &acquire, &swapchain->acquired_index),
+			"xrAcquireSwapchainImage"))
+		{
+			return 0;
+		}
+		if (!xr_ok(xrWaitSwapchainImage(swapchain->handle, &wait), "xrWaitSwapchainImage"))
+			return 0;
+		if (xr.has_metrics)
+			xr.acquire_seconds += seconds_now() - start;
+	}
+
+	/* (deferred: nothing read back; the game sets its state again) */
+	if (xr.deferred)
+		glActiveTexture(GL_TEXTURE0);
+	else
+		gl_save(&saved);
 	glBindFramebuffer(GL_DRAW_FRAMEBUFFER, swapchain->framebuffers[swapchain->acquired_index]);
 	glViewport(0, 0, swapchain->width, swapchain->height);
 	glDisable(GL_SCISSOR_TEST);
@@ -1303,6 +1690,8 @@ int host_xr_copy_layer_region(int layer, uint32_t texture, int clear_alpha, floa
 		glUniform1i(xr.source_uniform, 0);
 		glUniform4f(xr.rect_uniform, left, top, right, bottom);
 		glUniform1f(xr.cut_disc_uniform, clear_alpha == HALO_XR_COPY_DISC ? 1.0f : 0.0f);
+		glUniform1f(xr.alpha_from_colour_uniform, xr.quad_alpha_from_colour && clear_alpha == HALO_XR_COPY_ALPHA &&
+			layer != HALO_XR_LAYER_EYE_LEFT && layer != HALO_XR_LAYER_EYE_RIGHT ? 1.0f : 0.0f);
 		if ((layer == HALO_XR_LAYER_EYE_LEFT || layer == HALO_XR_LAYER_EYE_RIGHT) && xr.vignette > 0.001f)
 		{
 			const XrFovf *fov = &xr.views[layer - HALO_XR_LAYER_EYE_LEFT].fov;
@@ -1318,13 +1707,22 @@ int host_xr_copy_layer_region(int layer, uint32_t texture, int clear_alpha, floa
 		glBindVertexArray(xr.vertex_array);
 		glBindTexture(GL_TEXTURE_2D, texture);
 		glBindSampler(0, xr.sampler);
-		glGetTexParameteriv(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_R, &swizzle_r);
-		glGetTexParameteriv(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_B, &swizzle_b);
-		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_R, GL_RED);
-		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_B, GL_BLUE);
-		glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
-		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_R, swizzle_r);
-		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_B, swizzle_b);
+		if (xr.deferred)
+		{
+			/* (the game's render targets, all a copy reads, have no
+			swizzle: only its uploaded textures get one, xbox_textures.c) */
+			glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
+		}
+		else
+		{
+			glGetTexParameteriv(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_R, &swizzle_r);
+			glGetTexParameteriv(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_B, &swizzle_b);
+			glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_R, GL_RED);
+			glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_B, GL_BLUE);
+			glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
+			glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_R, swizzle_r);
+			glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_B, swizzle_b);
+		}
 		if (clear_alpha == HALO_XR_COPY_OPAQUE)
 		{
 			/* an opaque layer: the game's alpha channel holds other things */
@@ -1338,13 +1736,95 @@ int host_xr_copy_layer_region(int layer, uint32_t texture, int clear_alpha, floa
 		glClearColor(0.0f, 0.0f, 0.0f, clear_alpha ? 1.0f : 0.0f);
 		glClear(GL_COLOR_BUFFER_BIT);
 	}
+	swapchain->filled = 1;
+	if (xr.deferred)
+	{
+		swapchain->held = 1;
+		/* (the eyes, most of the frame's work, on to the GPU while the
+		game draws the rest) */
+		if (layer == HALO_XR_LAYER_EYE_RIGHT)
+			glFlush();
+		return 2;
+	}
 	gl_restore(&saved);

 	xrReleaseSwapchainImage(swapchain->handle, &release);
-	swapchain->filled = 1;
 	return 1;
 }

+/* deferred: the images the frame's copies kept, released before it ends */
+static void release_held(void)
+{
+	double start = xr.has_metrics ? seconds_now() : 0.0;
+	int layer;
+
+	for (layer = 0; layer < HALO_XR_LAYER_COUNT; layer++)
+	{
+		XrSwapchainImageReleaseInfo release = { XR_TYPE_SWAPCHAIN_IMAGE_RELEASE_INFO };
+		struct xr_swapchain *swapchain = &xr.swapchains[layer];
+
+		if (!swapchain->held)
+			continue;
+		swapchain->held = 0;
+		xr_ok(xrReleaseSwapchainImage(swapchain->handle, &release), "xrReleaseSwapchainImage");
+	}
+	if (xr.has_metrics)
+		xr.release_seconds += seconds_now() - start;
+}
+
+/* The Steam Frame: Android in a container, without XR_EXT_performance_settings
+to ask for the clocks, and the scheduler free to put the game's one busy
+thread, which simulates and draws each frame, on a slow core (its two
+2.3 GHz ones) now and then: frames late to the compositor, shown twice,
+the picture doubled as the head turns. The thread that ends the frames is
+kept on the cores no slower than nine tenths of the fastest. */
+static void xr_fast_cores(void)
+{
+	cpu_set_t set;
+	long fastest = 0, speeds[CPU_SETSIZE];
+	int cpu, count = 0;
+	char line[128] = "";
+
+	for (cpu = 0; cpu < CPU_SETSIZE && cpu < 64; cpu++)
+	{
+		char path[96];
+		FILE *file;
+
+		speeds[cpu] = 0;
+		snprintf(path, sizeof(path), "/sys/devices/system/cpu/cpu%d/cpufreq/cpuinfo_max_freq", cpu);
+		file = fopen(path, "r");
+		if (!file)
+			continue;
+		if (fscanf(file, "%ld", &speeds[cpu]) != 1)
+			speeds[cpu] = 0;
+		fclose(file);
+		if (speeds[cpu] > fastest)
+			fastest = speeds[cpu];
+	}
+	if (!fastest)
+	{
+		host_logf(HOST_LOG_INFO, "xr: the cores' speeds unknown: the frames' thread left where it runs");
+		return;
+	}
+	CPU_ZERO(&set);
+	for (cpu = 0; cpu < CPU_SETSIZE && cpu < 64; cpu++)
+	{
+		if (speeds[cpu] && speeds[cpu] * 10 >= fastest * 9)
+		{
+			char item[8];
+
+			CPU_SET(cpu, &set);
+			count++;
+			snprintf(item, sizeof(item), " %d", cpu);
+			strcat(line, item);
+		}
+	}
+	if (count && sched_setaffinity(0, sizeof(set), &set) == 0)
+		host_logf(HOST_LOG_INFO, "xr: the frames' thread on the fast cores:%s (fastest %ld MHz)", line, fastest / 1000);
+	else
+		host_logf(HOST_LOG_INFO, "xr: the frames' thread could not be kept on the fast cores");
+}
+
 int host_xr_end_frame(const struct halo_xr_submit *submit)
 {
 	XrFrameEndInfo end = { XR_TYPE_FRAME_END_INFO };
@@ -1354,13 +1834,15 @@ int host_xr_end_frame(const struct halo_xr_submit *submit)
 	XrCompositionLayerQuad wrist = { XR_TYPE_COMPOSITION_LAYER_QUAD };
 	XrCompositionLayerQuad scope = { XR_TYPE_COMPOSITION_LAYER_QUAD };
 	XrCompositionLayerQuad crosshair = { XR_TYPE_COMPOSITION_LAYER_QUAD };
-	const XrCompositionLayerBaseHeader *layers[5];
+	XrCompositionLayerQuad names[HALO_XR_MAXIMUM_NAMES];
+	const XrCompositionLayerBaseHeader *layers[5 + HALO_XR_MAXIMUM_NAMES];
 	uint32_t layer_count = 0;
 	int eye;

 	if (!xr.frame_begun)
 		return 0;
 	xr.frame_begun = 0;
+	release_held();

 	if (xr.frame_state.shouldRender && submit->eyes && xr.views_valid &&
 		xr.swapchains[HALO_XR_LAYER_EYE_LEFT].filled && xr.swapchains[HALO_XR_LAYER_EYE_RIGHT].filled)
@@ -1458,11 +1940,111 @@ int host_xr_end_frame(const struct halo_xr_submit *submit)
 		layers[layer_count++] = (const XrCompositionLayerBaseHeader *)&crosshair;
 	}

+	if (xr.frame_state.shouldRender && submit->name_count > 0 && xr.swapchains[HALO_XR_LAYER_NAMES].filled)
+	{
+		struct xr_swapchain *swapchain = &xr.swapchains[HALO_XR_LAYER_NAMES];
+		int slot_height = swapchain->height / HALO_XR_MAXIMUM_NAMES;
+		int name;
+
+		for (name = 0; name < submit->name_count && name < HALO_XR_MAXIMUM_NAMES; name++)
+		{
+			XrCompositionLayerQuad *quad_name = &names[name];
+
+			memset(quad_name, 0, sizeof(*quad_name));
+			quad_name->type = XR_TYPE_COMPOSITION_LAYER_QUAD;
+			quad_name->layerFlags = XR_COMPOSITION_LAYER_BLEND_TEXTURE_SOURCE_ALPHA_BIT;
+			quad_name->space = xr.local_space;
+			quad_name->eyeVisibility = XR_EYE_VISIBILITY_BOTH;
+			quad_name->subImage.swapchain = swapchain->handle;
+			/* (slot 0 at the image's top: GL's rows run bottom up) */
+			quad_name->subImage.imageRect.offset.x = 0;
+			quad_name->subImage.imageRect.offset.y = swapchain->height - (name + 1) * slot_height;
+			quad_name->subImage.imageRect.extent.width = swapchain->width;
+			quad_name->subImage.imageRect.extent.height = slot_height;
+			quad_name->size.width = submit->name_widths[name];
+			quad_name->size.height = submit->name_widths[name] * NAME_SLOT_ASPECT;
+			pose_to_xr(&quad_name->pose, &submit->name_poses[name]);
+			layers[layer_count++] = (const XrCompositionLayerBaseHeader *)quad_name;
+		}
+	}
+
+	if (xr.steamvr && !xr.cores_pinned)
+	{
+		xr.cores_pinned = 1;
+		if (!getenv("HALO_XR_ANY_CORE"))
+			xr_fast_cores();
+	}
+	/* (every five seconds, the compositor's counters, and the core the
+	frames' thread is on) */
+	if (xr.has_metrics)
+	{
+		struct timespec now;
+
+		clock_gettime(CLOCK_MONOTONIC, &now);
+		if (now.tv_sec - xr.metrics_logged.tv_sec >= 5)
+		{
+			char line[768] = "";
+			uint32_t counter;
+
+			xr.metrics_logged = now;
+			for (counter = 0; counter < xr.metric_count && counter < 16; counter++)
+			{
+				XrPerformanceMetricsCounterMETA value = { XR_TYPE_PERFORMANCE_METRICS_COUNTER_META };
+				char name[XR_MAX_PATH_LENGTH];
+				uint32_t length = 0;
+				char item[96];
+
+				if (!XR_SUCCEEDED(xr.query_metric(xr.session, xr.metric_paths[counter], &value)) ||
+					!XR_SUCCEEDED(xrPathToString(xr.instance, xr.metric_paths[counter], sizeof(name), &length, name)))
+				{
+					continue;
+				}
+				snprintf(item, sizeof(item), " %s=%g", strrchr(name, '/') ? strrchr(name, '/') + 1 : name,
+					(value.counterFlags & XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_META) ?
+						(double)value.floatValue : (double)value.uintValue);
+				if (strlen(line) + strlen(item) < sizeof(line))
+					strcat(line, item);
+			}
+			host_logf(HOST_LOG_INFO, "xr: metrics%s, on core %d", line, sched_getcpu());
+			if (xr.timed_frames)
+			{
+				double frames = (double)xr.timed_frames;
+				char copies[256] = "";
+				int timed;
+
+				for (timed = 0; timed < HALO_XR_LAYER_COUNT; timed++)
+				{
+					char item[24];
+
+					snprintf(item, sizeof(item), " %d:%.2f", timed, xr.copy_seconds[timed] * 1e3 / frames);
+					strcat(copies, item);
+					xr.copy_seconds[timed] = 0.0;
+				}
+				host_logf(HOST_LOG_INFO, "xr: per frame ms: copies (layer:ms)%s; of them acquiring images %.2f; "
+					"releasing them at the end %.2f; xrEndFrame %.2f (copies %s)", copies,
+					xr.acquire_seconds * 1e3 / frames, xr.release_seconds * 1e3 / frames, xr.end_seconds * 1e3 / frames,
+					xr.deferred ? "deferred" : "one by one");
+				xr.acquire_seconds = xr.release_seconds = xr.end_seconds = 0.0;
+				xr.timed_frames = 0;
+			}
+		}
+	}
+
 	end.displayTime = xr.frame_state.predictedDisplayTime;
 	end.environmentBlendMode = XR_ENVIRONMENT_BLEND_MODE_OPAQUE;
 	end.layerCount = layer_count;
 	end.layers = layers;
-	return xr_ok(xrEndFrame(xr.session, &end), "xrEndFrame");
+	{
+		double start = xr.has_metrics ? seconds_now() : 0.0;
+		int ended = xr_ok(xrEndFrame(xr.session, &end), "xrEndFrame");
+
+		if (xr.has_metrics)
+		{
+			xr.end_seconds += seconds_now() - start;
+			xr.timed_frames++;
+		}
+		return ended;
+	}
 }

 void host_xr_set_vignette(float strength)
@@ -1470,6 +2052,34 @@ void host_xr_set_vignette(float strength)
 	xr.vignette = strength < 0.0f ? 0.0f : strength > 1.0f ? 1.0f : strength;
 }

+/* the VR options' refresh rates: those the runtime offers (none where it
+lets none be chosen, as SteamVR, whose rate is SteamOS's), and the one it
+runs at, by XR_FB_display_refresh_rate or else by its frames' period */
+int host_xr_refresh_rates(float *rates, int maximum, float *current)
+{
+	float offered[16];
+	uint32_t count = 0, index;
+
+	*current = 0.0f;
+	if (!xr.initialized)
+		return 0;
+	if (xr.has_refresh_rate)
+		xr.get_refresh_rate(xr.session, current);
+	if (*current <= 0.0f && xr.frame_state.predictedDisplayPeriod > 0)
+		*current = 1e9f / (float)xr.frame_state.predictedDisplayPeriod;
+	if (!xr.has_refresh_rate || !XR_SUCCEEDED(xr.enumerate_refresh_rates(xr.session, 16, &count, offered)))
+		return 0;
+	for (index = 0; index < count && (int)index < maximum; index++)
+		rates[index] = offered[index];
+	return (int)index;
+}
+
+void host_xr_set_refresh_rate(float wanted)
+{
+	if (xr.initialized)
+		refresh_rate_choose(wanted);
+}
+
 void host_xr_haptic(int hand, float amplitude, float seconds)
 {
 	XrHapticActionInfo information = { XR_TYPE_HAPTIC_ACTION_INFO };
@@ -38,6 +38,8 @@ host_sdl_gamepad_axis
 host_sdl_gamepad_button
 host_sdl_gamepad_type
 host_sdl_rumble_gamepad
+host_sdl_scancode_name
+host_sdl_scancode_from_name
 host_sdl_open_audio_stream
 host_sdl_put_audio_stream_data
 host_sdl_resume_audio_stream_device
@@ -59,6 +61,8 @@ host_xr_end_frame
 host_xr_haptic
 host_xr_set_vignette
 host_xr_copy_layer_array
+host_xr_refresh_rates
+host_xr_set_refresh_rate
 host_android_path

 host_errno
@@ -24,10 +24,13 @@ enum
 	HALO_XR_LAYER_EYE_LEFT = 0,
 	HALO_XR_LAYER_EYE_RIGHT = 1,
 	HALO_XR_LAYER_OVERLAY = 2, /* HUD, menus, cinematics: a flat quad */
-	HALO_XR_LAYER_WRIST = 3,   /* the motion tracker, on the left wrist */
+	HALO_XR_LAYER_WRIST = 3,   /* the motion tracker, on the free hand's wrist */
 	HALO_XR_LAYER_SCOPE = 4,   /* the zoomed view, a disc over the weapon */
 	HALO_XR_LAYER_CROSSHAIR = 5, /* the weapon's crosshair, where it aims */
-	HALO_XR_LAYER_COUNT = 6,
+	HALO_XR_LAYER_NAMES = 6,   /* players' names, each a quad over a head */
+	HALO_XR_LAYER_COUNT = 7,
+	/* the names layer's slots, one a name, stacked from its top */
+	HALO_XR_MAXIMUM_NAMES = 8,

 	/* host_xr_copy_layer's clear_alpha: the source's alpha kept, made
 	opaque, or cut to a disc (premultiplied) */
@@ -50,6 +53,29 @@ enum
 	HALO_XR_BUTTON_TRIGGER = 1 << 4,    /* trigger past its click point */
 	HALO_XR_BUTTON_SQUEEZE = 1 << 5,    /* grip past its click point */
 	HALO_XR_BUTTON_THUMBREST = 1 << 6,  /* thumb resting (touch) */
+	/* the Steam Frame's controllers' (HALO_XR_LAYOUT_FRAME): the left one's
+	View button and D-pad, either one's bumper (their right one's X, Y and
+	menu button come as the left hand's A, B and MENU: the game's X, Y and
+	Start, as on the Quest) */
+	HALO_XR_BUTTON_VIEW = 1 << 7,
+	HALO_XR_BUTTON_BUMPER = 1 << 8,
+	HALO_XR_BUTTON_DPAD_UP = 1 << 9,
+	HALO_XR_BUTTON_DPAD_DOWN = 1 << 10,
+	HALO_XR_BUTTON_DPAD_LEFT = 1 << 11,
+	HALO_XR_BUTTON_DPAD_RIGHT = 1 << 12,
+	/* the fingers' touch (the hands drawn: vr.c): the thumb on the stick, a
+	button or the rest; the index finger on the trigger; and whether the
+	controller tells the thumb's at all */
+	HALO_XR_BUTTON_THUMB_TOUCH = 1 << 13,
+	HALO_XR_BUTTON_INDEX_TOUCH = 1 << 14,
+	HALO_XR_BUTTON_TOUCH_KNOWN = 1 << 15,
+};
+
+/* the controllers' layout, for what the game tells the player */
+enum
+{
+	HALO_XR_LAYOUT_TOUCH = 0, /* the Quest's: X, Y and menu on the left */
+	HALO_XR_LAYOUT_FRAME = 1, /* the Steam Frame's: A, B, X, Y and menu on the right, a D-pad on the left */
 };

 /* halo_xr_hand.flags, halo_xr_view.flags, halo_xr_frame.head_flags */
@@ -109,6 +135,7 @@ struct halo_xr_frame
 	struct halo_xr_pose head;
 	struct halo_xr_view views[HALO_XR_EYE_COUNT];
 	struct halo_xr_hand hands[HALO_XR_HAND_COUNT];
+	int controller_layout;  /* HALO_XR_LAYOUT_* */
 };

 /* halo_xr_submit.overlay_mode */
@@ -128,15 +155,18 @@ struct halo_xr_submit
 	float overlay_width;    /* metres; the height follows from 4:3 */
 	/* the screen's placement in LOCAL space (HALO_XR_OVERLAY_SCREEN) */
 	struct halo_xr_pose screen;
-	/* the wrist layer was filled: shown on the back of the left wrist,
-	this wide (metres), while the wrist is turned to the eyes */
+	/* the wrist layer was filled: shown on the back of the left wrist (of
+	the right one, left-handed: wrist_hand, a HALO_XR_HAND_*), this wide
+	(metres), while the wrist is turned to the eyes */
 	int wrist;
 	float wrist_size;
-	/* its placement as the wrist turned to the eyes reads it: turned this
-	many degrees clockwise, and moved this far right and down (metres) */
+	/* its placement as the left wrist turned to the eyes reads it: turned
+	this many degrees clockwise, and moved this far right and down (metres;
+	on the right wrist, the mirror image) */
 	float wrist_turn;
 	float wrist_right;
 	float wrist_down;
+	int wrist_hand;
 	/* the scope layer was filled: a disc this wide (metres), here in LOCAL
 	space, facing back along the weapon */
 	int scope;
@@ -147,6 +177,12 @@ struct halo_xr_submit
 	int crosshair;
 	float crosshair_size;
 	struct halo_xr_pose crosshair_pose;
+	/* the names layer was filled: its first name_count slots, each shown
+	this wide (metres, a slot's height following from its shape), here in
+	LOCAL space, facing the eyes */
+	int name_count;
+	float name_widths[HALO_XR_MAXIMUM_NAMES];
+	struct halo_xr_pose name_poses[HALO_XR_MAXIMUM_NAMES];
 };

 #endif
@@ -0,0 +1,266 @@
+#!/bin/bash
+# Halo VR's installer for the Steam Frame, run in its Desktop Mode from the
+# bundle the release's "Install Halo VR" desktop file downloads
+# (steam_frame_installer.desktop; the bundle: this script, HaloVR.apk,
+# halo-vr.sh = steam_frame_launch.sh, steam_frame_xiso.py and the library
+# pictures in grid/). Everything is answered with dialogs, no keyboard:
+# - the game in ~/Documents/HaloCE (port/android/STEAM_FRAME.md), its APK
+#   replaced (Lepton installs a newer one at the next start), so running the
+#   installer again updates the game;
+# - the game data: the maps folder copied out of a disc image of Halo
+#   (.iso or .xiso) found in Downloads, Documents, the Desktop or on a
+#   memory card, or chosen, unless it is there already;
+# - "Halo VR" in the Steam library, with its pictures, unless it is there
+#   already: Steam is closed for that (it keeps its shortcuts in memory and
+#   writes them back when it quits), and started again in Gaming Mode.
+# HALO_VR_UNATTENDED=1 answers every question with its default and prints
+# instead of showing dialogs (HALO_VR_IMAGE: the disc image to use), for
+# testing over adb; it never closes Steam.
+
+BUNDLE="$(cd "$(dirname "$0")" && pwd)"
+HALO_DIR="$HOME/Documents/HaloCE"
+STEAM_DIR="$HOME/.local/share/Steam"
+LEPTON="$STEAM_DIR/steamapps/common/Lepton/lepton"
+TITLE="Halo VR"
+NAME="Halo VR"
+EXE="\"$HALO_DIR/halo-vr.sh\""
+
+unattended() { [ "${HALO_VR_UNATTENDED:-0}" = 1 ] || ! command -v zenity >/dev/null; }
+
+info()
+{
+    if unattended; then printf "info: %b\n" "$1"; else zenity --info --title="$TITLE" --width=460 --text="$1"; fi
+}
+
+fail()
+{
+    if unattended; then printf "error: %b\n" "$1" >&2; else zenity --error --title="$TITLE" --width=460 --text="$1"; fi
+    exit 1
+}
+
+# yes/no; unattended: the default given ($2, "yes" or "no")
+ask()
+{
+    if unattended; then [ "$2" = yes ]; return; fi
+    zenity --question --title="$TITLE" --width=460 --text="$1"
+}
+
+# the disc image the player chooses
+choose_image()
+{
+    if unattended; then return 1; fi
+    zenity --file-selection --title="Choose a disc image of Halo: Combat Evolved (.iso or .xiso)" \
+        --filename="$HOME/Downloads/" --file-filter="Disc images | *.iso *.ISO *.xiso *.XISO" \
+        --file-filter="All files | *"
+}
+
+# the disc images near at hand, largest first (a Halo image is a few GB;
+# anything under 500 MB is not one)
+find_images()
+{
+    find "$HOME/Downloads" "$HOME/Documents" "$HOME/Desktop" /run/media -maxdepth 3 -type f \
+        \( -iname '*.iso' -o -iname '*.xiso' \) -size +500M -printf '%s\t%p\n' 2>/dev/null |
+        sort -rn | cut -f2-
+}
+
+extract_maps()
+{
+    local image="$1" log
+    log="$(mktemp)"
+    if unattended; then
+        python3 "$BUNDLE/steam_frame_xiso.py" "$image" "$HALO_DIR" 2>"$log" | grep '^#' | tail -n 1
+        status=${PIPESTATUS[0]}
+    else
+        python3 "$BUNDLE/steam_frame_xiso.py" "$image" "$HALO_DIR" 2>"$log" |
+            zenity --progress --title="$TITLE" --width=460 --auto-close --no-cancel \
+                --text="Copying the game data out of the disc image..."
+        status=${PIPESTATUS[0]}
+    fi
+    if [ "$status" != 0 ]; then
+        reason="$(sed -n 's/^error: //p' "$log" | head -n 1)"
+        rm -f "$log"
+        fail "The game data could not be copied out of\n$image\n\n${reason:-Unknown error.}"
+    fi
+    rm -f "$log"
+}
+
+# the shortcut's id as Steam makes it for a non-Steam game: its pictures in
+# config/grid are named after it
+shortcut_id()
+{
+    python3 -c 'import sys, zlib; print(zlib.crc32((sys.argv[1] + sys.argv[2]).encode()) | 0x80000000)' "$EXE" "$NAME"
+}
+
+# whether every Steam user's shortcuts.vdf already holds the game
+have_shortcut()
+{
+    local found=1 config
+    for config in "$STEAM_DIR"/userdata/*/config; do
+        [ -d "$config" ] || continue
+        case "$config" in */userdata/0/*) continue ;; esac
+        grep -qaF "$HALO_DIR/halo-vr.sh" "$config/shortcuts.vdf" 2>/dev/null || return 1
+        found=0
+    done
+    return $found
+}
+
+# "Halo VR" added to every Steam user's shortcuts.vdf (Steam closed), as a VR
+# title, with its pictures
+add_shortcut()
+{
+    local id config
+    id="$(shortcut_id)"
+    for config in "$STEAM_DIR"/userdata/*/config; do
+        [ -d "$config" ] || continue
+        case "$config" in */userdata/0/*) continue ;; esac
+        python3 - "$config/shortcuts.vdf" "$id" "$NAME" "$EXE" "\"$HALO_DIR/\"" <<'PYTHON' || return 1
+import os, struct, sys
+
+path, appid, name, exe, start = sys.argv[1], int(sys.argv[2]), sys.argv[3], sys.argv[4], sys.argv[5]
+
+# Steam's binary VDF: 0x00 a map, 0x01 a string, 0x02 an int32, 0x08 a map's end
+def read_map(data, at):
+    items = []
+    while True:
+        kind = data[at]; at += 1
+        if kind == 0x08:
+            return items, at
+        end = data.index(b"\0", at); key = data[at:end]; at = end + 1
+        if kind == 0x00:
+            value, at = read_map(data, at)
+        elif kind == 0x01:
+            end = data.index(b"\0", at); value = data[at:end]; at = end + 1
+        elif kind == 0x02:
+            value = struct.unpack_from("<I", data, at)[0]; at += 4
+        else:
+            raise ValueError("unknown VDF type %d" % kind)
+        items.append((kind, key, value))
+
+def write_map(items):
+    out = b""
+    for kind, key, value in items:
+        out += bytes([kind]) + key + b"\0"
+        if kind == 0x00:
+            out += write_map(value)
+        elif kind == 0x01:
+            out += value + b"\0"
+        else:
+            out += struct.pack("<I", value)
+    return out + b"\x08"
+
+shortcuts = []
+if os.path.exists(path):
+    with open(path, "rb") as file:
+        data = file.read()
+    if data:
+        top, _ = read_map(data, 0)
+        for kind, key, value in top:
+            if key.lower() == b"shortcuts" and kind == 0x00:
+                shortcuts = [entry for entry in value if entry[0] == 0x00]
+# (an older entry of the game's replaced)
+shortcuts = [entry for entry in shortcuts
+    if not any(k.lower() == b"exe" and v == exe.encode() for _, k, v in entry[2])]
+
+def text(key, value):
+    return (0x01, key.encode(), value.encode())
+
+def number(key, value):
+    return (0x02, key.encode(), value)
+
+entry = [
+    number("appid", appid), text("AppName", name), text("Exe", exe), text("StartDir", start),
+    text("icon", ""), text("ShortcutPath", ""), text("LaunchOptions", ""), number("IsHidden", 0),
+    number("AllowDesktopConfig", 1), number("AllowOverlay", 1), number("OpenVR", 1), number("Devkit", 0),
+    text("DevkitGameID", ""), number("DevkitOverrideAppID", 0), number("LastPlayTime", 0),
+    text("FlatpakAppID", ""), text("sortas", ""), (0x00, b"tags", []),
+]
+shortcuts.append((0x00, b"", entry))
+shortcuts = [(0x00, str(index).encode(), value) for index, (_, _, value) in enumerate(shortcuts)]
+data = write_map([(0x00, b"shortcuts", shortcuts)])
+with open(path + ".tmp", "wb") as file:
+    file.write(data)
+os.replace(path + ".tmp", path)
+PYTHON
+        mkdir -p "$config/grid"
+        cp "$BUNDLE/grid/library.png" "$config/grid/${id}.png"
+        cp "$BUNDLE/grid/libraryp.png" "$config/grid/${id}p.png"
+        cp "$BUNDLE/grid/library_hero.png" "$config/grid/${id}_hero.png"
+        cp "$BUNDLE/grid/library_logo.png" "$config/grid/${id}_logo.png"
+    done
+}
+
+# --- the game
+
+[ -x "$LEPTON" ] || fail "Lepton, which runs Android games on the Steam Frame, was not found.\n\nStart any Android game from the Steam store once, then run this installer again."
+for file in HaloVR.apk halo-vr.sh steam_frame_xiso.py grid/library.png; do
+    [ -f "$BUNDLE/$file" ] || fail "The installer is incomplete ($file is missing). Download it again."
+done
+
+if [ -f "$HALO_DIR/HaloVR.apk" ]; then
+    ask "Halo VR is installed already. Update it to this version?\n\n(Your settings, saves and game data stay.)" yes || exit 0
+else
+    ask "This installs Halo VR on your Steam Frame.\n\nYou need your own disc image of Halo: Combat Evolved for the Xbox (an .iso or .xiso file, any version), for example in Downloads.\n\nContinue?" yes || exit 0
+fi
+
+mkdir -p "$HALO_DIR/maps" || fail "Could not create $HALO_DIR."
+# (the game runs in Lepton's container as a user of its own)
+chmod 777 "$HALO_DIR" "$HALO_DIR/maps"
+cp "$BUNDLE/halo-vr.sh" "$HALO_DIR/halo-vr.sh.tmp" && chmod 755 "$HALO_DIR/halo-vr.sh.tmp" &&
+    mv -f "$HALO_DIR/halo-vr.sh.tmp" "$HALO_DIR/halo-vr.sh" || fail "Could not write $HALO_DIR/halo-vr.sh."
+# (newer than the installed one: Lepton installs it at the next start)
+cp "$BUNDLE/HaloVR.apk" "$HALO_DIR/HaloVR.apk.tmp" && chmod 666 "$HALO_DIR/HaloVR.apk.tmp" &&
+    mv -f "$HALO_DIR/HaloVR.apk.tmp" "$HALO_DIR/HaloVR.apk" && touch "$HALO_DIR/HaloVR.apk" ||
+    fail "Could not write $HALO_DIR/HaloVR.apk (is the storage full?)."
+
+# --- the game data
+
+if [ ! -f "$HALO_DIR/maps/ui.map" ]; then
+    image="${HALO_VR_IMAGE:-}"
+    if [ -z "$image" ]; then
+        mapfile -t images < <(find_images)
+        for candidate in "${images[@]}"; do
+            if ask "Use this disc image?\n\n$candidate" yes; then
+                image="$candidate"
+                break
+            fi
+        done
+    fi
+    if [ -z "$image" ]; then
+        if [ ${#images[@]} = 0 ]; then
+            info "No disc image was found in Downloads, Documents, on the Desktop or a memory card.\n\nChoose it in the next window."
+        fi
+        image="$(choose_image)" || fail "No disc image was chosen. Run the installer again once it is on the Frame (for example in Downloads)."
+    fi
+    extract_maps "$image"
+    chmod -R a+rwX "$HALO_DIR/maps"
+    image_note="\n\nThe disc image itself is no longer needed:\n$image"
+fi
+
+# --- Steam
+
+steam_closed=0
+if ! have_shortcut; then
+    if unattended; then
+        echo "info: the Steam shortcut is missing (not added unattended)"
+    else
+        info "Halo VR is now added to your Steam library. Steam closes for a moment for that."
+        if pgrep -x steam >/dev/null; then
+            steam -shutdown >/dev/null 2>&1 &
+            for _ in $(seq 60); do pgrep -x steam >/dev/null || break; sleep 1; done
+            pgrep -x steam >/dev/null && fail "Steam did not close. Close it (Steam menu > Exit) and run the installer again."
+        fi
+        steam_closed=1
+        add_shortcut || fail "Could not add Halo VR to the Steam library."
+    fi
+fi
+
+if unattended; then
+    echo "info: installed in $HALO_DIR"
+    exit 0
+fi
+if ask "Halo VR is installed.${image_note:-}\n\nSwitch to Gaming Mode now? Start Halo VR from your library there." yes; then
+    steamos-session-select gamescope >/dev/null 2>&1 ||
+        info "Switch to Gaming Mode yourself (the \"Return to Gaming Mode\" icon or the power menu)."
+elif [ "$steam_closed" = 1 ]; then
+    setsid steam >/dev/null 2>&1 < /dev/null &
+fi
@@ -0,0 +1,13 @@
+[Desktop Entry]
+# Halo VR's installer for the Steam Frame (port/android/STEAM_FRAME.md): a
+# release asset, "Install-Halo-VR.desktop", opened in Desktop Mode. It
+# downloads the latest release's bundle (tools/steam_frame_bundle.py, which
+# fills in the repository) and runs its installer, steam_frame_install.sh.
+# (no "$", "\" or "%" in Exec: the desktop entry format would need them
+# escaped)
+Type=Application
+Name=Install Halo VR
+Comment=Installs Halo VR for the Steam Frame, or updates it
+Icon=steam
+Terminal=false
+Exec=bash -c "if curl -fL --retry 3 -o /tmp/halo-vr-steam-frame.zip https://github.com/@REPOSITORY@/releases/latest/download/halo-vr-steam-frame.zip && rm -rf /tmp/halo-vr-install && python3 -m zipfile -e /tmp/halo-vr-steam-frame.zip /tmp/halo-vr-install; then exec bash /tmp/halo-vr-install/install.sh; else zenity --error --width=460 --title='Halo VR' --text='Halo VR could not be downloaded. Is the Steam Frame online?'; fi"
@@ -0,0 +1,85 @@
+#!/bin/bash
+# Halo VR on the Steam Frame: Lepton runs the APK in a container of its own,
+# and installs it anew whenever the APK is newer than the installed one
+# (port/android/STEAM_FRAME.md). The game's data: ~/Documents/HaloCE.
+# (a container of its own, not the shortcut's id: with that, SteamVR's
+# client in the container waited on xrCreateInstance)
+export SteamAppId="${HALO_LEPTON_APP_ID:-4290000001}"
+# (what Steam gives an Android title of its own, and a non-Steam game not:
+# the app's data in the container links to the compat data path's
+# internal/, a dangling link without it; and the shader paths: Lepton reads
+# the dump path against the other)
+export STEAM_COMPAT_DATA_PATH="$HOME/.local/share/Steam/steamapps/compatdata/$SteamAppId"
+export STEAM_COMPAT_SHADER_PATH="$HOME/.local/share/Steam/steamapps/shadercache/$SteamAppId"
+mkdir -p "$STEAM_COMPAT_DATA_PATH/internal" "$STEAM_COMPAT_SHADER_PATH"
+unset STEAM_FOSSILIZE_DUMP_PATH LD_PRELOAD
+LEPTON="$HOME/.local/share/Steam/steamapps/common/Lepton/lepton"
+APK="$HOME/Documents/HaloCE/HaloVR.apk"
+LOG="$HOME/Documents/HaloCE/launcher.log"
+# (written by the game when the player quits it: no start again)
+QUIT="$HOME/Documents/HaloCE/quit_requested.txt"
+rm -f "$QUIT"
+CONTEXT="steamlaunch-$SteamAppId"
+
+log() { echo "$(date '+%F %T') $*" >> "$LOG"; }
+log "start (pid $$, parent $PPID)"
+
+# Steam's "Exit game" ends the game's processes as Steam knows them (this
+# script, under Steam's reaper), not the container, which podman runs: a
+# signal here is passed on to Lepton, and a watcher of its own takes the
+# container down once this script is gone (killed)
+stopping=0
+child=0
+stop()
+{
+    log "signal $1"
+    stopping=1
+    [ "$child" -gt 0 ] && kill -TERM "$child" 2>/dev/null
+}
+trap 'stop TERM' TERM
+trap 'stop INT' INT
+trap 'stop HUP' HUP
+
+script=$$
+setsid bash -c '
+    while kill -0 '"$script"' 2>/dev/null; do sleep 1; done
+    echo "$(date "+%F %T") watcher: the game was ended, so its container" >> "'"$LOG"'"
+    "'"$LEPTON"'" kill "'"$CONTEXT"'" >/dev/null 2>&1
+' </dev/null >/dev/null 2>&1 &
+
+# the game's log while it runs (Lepton's logcat of its container), for
+# looking into problems: logcat.txt, anew each start
+LOGCAT="$HOME/Documents/HaloCE/logcat.txt"
+: > "$LOGCAT"
+setsid bash -c '
+    while kill -0 '"$script"' 2>/dev/null; do
+        "'"$LEPTON"'" logcat "'"$CONTEXT"'" 2>/dev/null | grep -v "^ERROR: \|^steamlaunch-\|^$" >> "'"$LOGCAT"'"
+        sleep 3
+    done
+' </dev/null >/dev/null 2>&1 &
+
+run()
+{
+    "$LEPTON" waitforexitandrun -- "$APK" &
+    child=$!
+    # (wait returns early when a signal comes: until Lepton is gone)
+    while kill -0 "$child" 2>/dev/null; do
+        wait "$child"
+    done
+    child=0
+}
+
+# (a new APK is only installed on its first start, not started; and a start
+# right after a game that was ended hard can fail in SteamVR, which then
+# needs a moment: again, up to three times, while it ends within 30 s)
+for attempt in 1 2 3; do
+    started=$SECONDS
+    run
+    if (( stopping || SECONDS - started >= 30 )) || [ -e "$QUIT" ]; then
+        break
+    fi
+    log "ended within $((SECONDS - started)) s: again"
+    sleep 5
+done
+rm -f "$QUIT"
+log "end"
@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+Copies the maps folder out of an Xbox disc image (an "xiso", or a whole
+disc's ".iso") on the Steam Frame's SteamOS side, for its installer
+(steam_frame_install.sh). It reads the image as the app's own import does
+(app/src/main/java/com/halo/decomp/XisoExtractor.java, which this follows;
+the desktop games' is port/linux/src/xiso.c).
+
+    steam_frame_xiso.py <image> <destination>
+
+writes <destination>/maps (through maps.partial, so an interrupted copy
+never leaves maps/ui.map behind) and prints its progress for zenity
+--progress: a percentage on a line of its own, and "# <text>" lines. On
+failure it prints "error: <reason the player can act on>" to stderr and
+exits 1.
+
+The image's file system is XDVDFS, read as extract-xiso does
+(https://github.com/XboxDev/extract-xiso, extract-xiso.c, whose format
+handling this follows; its license is below and in
+port/third_party/extract-xiso/LICENSE.TXT): 2048-byte sectors; a volume
+descriptor at 0x10000 that starts and ends with "MICROSOFT*XBOX*MEDIA" and
+gives the root directory's sector and size; and directories whose entries
+form a binary tree (each entry: left and right subtree offsets in 4-byte
+units, the start sector, the size, attributes, the name's length and the
+name). Images made from a whole disc put the game partition further in, at
+one of the offsets below.
+
+Some parts of this code are copyright in@fishtank.com. This product
+includes software developed by in <in@fishtank.com>.
+
+Copyright (c) 2003 in <in@fishtank.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. All advertising materials mentioning features or use of this software
+   must display the following acknowledgement:
+
+   This product includes software developed by in <in@fishtank.com>.
+
+4. Neither the name of "in" nor the email address "in@fishtank.com"
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED `AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
+AUTHOR OR ANY CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+import os
+import struct
+import sys
+
+SECTOR_SIZE = 2048
+VOLUME_DESCRIPTOR_OFFSET = 0x10000
+ENTRY_HEADER_SIZE = 14
+ATTRIBUTE_DIRECTORY = 0x10
+# directory tables are a few sectors; anything much larger is not one
+MAXIMUM_DIRECTORY_SIZE = 4 << 20
+MAXIMUM_FILES = 256
+COPY_BUFFER_SIZE = 1 << 20
+VOLUME_MAGIC = b"MICROSOFT*XBOX*MEDIA"
+# where the game partition starts: a plain image, and whole-disc images
+# (extract-xiso's GLOBAL, XGD3 and XGD1 offsets)
+PARTITION_OFFSETS = (0, 0x0FD90000, 0x02080000, 0x18300000)
+
+
+class ExtractError(Exception):
+    """a reason the player can act on"""
+
+
+def read_at(image, offset, size):
+    image.seek(offset)
+    data = image.read(size)
+    if len(data) != size:
+        raise ExtractError("Could not read the disc image (is it complete?).")
+    return data
+
+
+def find_volume(image):
+    """the game partition's offset, and the root directory's sector and size"""
+    for offset in PARTITION_OFFSETS:
+        try:
+            descriptor = read_at(image, offset + VOLUME_DESCRIPTOR_OFFSET, SECTOR_SIZE)
+        except ExtractError:
+            continue
+        if descriptor[:20] != VOLUME_MAGIC or descriptor[0x7EC:0x7EC + 20] != VOLUME_MAGIC:
+            continue
+        sector, size = struct.unpack_from("<II", descriptor, 20)
+        return offset, sector, size
+    raise ExtractError("This is not an Xbox disc image.")
+
+
+def read_directory(image, partition, sector, size, what):
+    if size <= 0 or size > MAXIMUM_DIRECTORY_SIZE:
+        raise ExtractError(what)
+    return read_at(image, partition + sector * SECTOR_SIZE, size)
+
+
+def walk(table, offset, depth, directories, out, visited):
+    """collects the entries (name, sector, size) of the subtree at offset
+    (4-byte units), files or directories as asked"""
+    at = offset * 4
+    # a malformed table must not loop or run off its end
+    visited[0] += 1
+    if depth > 64 or visited[0] > 4096 or at + ENTRY_HEADER_SIZE > len(table):
+        return
+    left, right, sector, size, attributes, name_length = struct.unpack_from("<HHIIBB", table, at)
+    # 0xFFFF: padding, an empty directory
+    if left == 0xFFFF:
+        return
+    if left:
+        walk(table, left, depth + 1, directories, out, visited)
+    is_directory = bool(attributes & ATTRIBUTE_DIRECTORY)
+    if (at + ENTRY_HEADER_SIZE + name_length <= len(table) and name_length > 0
+            and is_directory == directories and len(out) < MAXIMUM_FILES):
+        name = table[at + ENTRY_HEADER_SIZE:at + ENTRY_HEADER_SIZE + name_length].decode("latin-1")
+        # (as extract-xiso refuses them: no name may leave the folder)
+        if name not in (".", "..") and "/" not in name and "\\" not in name:
+            out.append((name, sector, size))
+    if right:
+        walk(table, right, depth + 1, directories, out, visited)
+
+
+def extract(image_path, destination):
+    with open(image_path, "rb") as image:
+        partition, root_sector, root_size = find_volume(image)
+
+        # the root's maps folder
+        table = read_directory(image, partition, root_sector, root_size,
+            "The disc image's file system is damaged.")
+        directories = []
+        walk(table, 0, 0, True, directories, [0])
+        maps = [entry for entry in directories if entry[0].lower() == "maps"]
+        if not maps:
+            raise ExtractError("The disc image has no maps folder: it is not a Halo disc.")
+
+        # its files
+        table = read_directory(image, partition, maps[-1][1], maps[-1][2],
+            "The disc image's maps folder is damaged.")
+        files = []
+        walk(table, 0, 0, False, files, [0])
+        if not any(name.lower() == "ui.map" for name, _, _ in files):
+            raise ExtractError("The disc image's maps folder has no ui.map: it is not a Halo disc.")
+        total = sum(size for _, _, size in files) or 1
+
+        partial = os.path.join(destination, "maps.partial")
+        finished = os.path.join(destination, "maps")
+        try:
+            os.makedirs(partial, exist_ok=True)
+        except OSError:
+            raise ExtractError("Could not create %s." % partial)
+        done = 0
+        shown = -1
+        for name, sector, size in files:
+            path = os.path.join(partial, name)
+            offset = partition + sector * SECTOR_SIZE
+            remaining = size
+            print("# Copying maps/%s" % name, flush=True)
+            try:
+                with open(path, "wb") as out:
+                    while remaining > 0:
+                        count = min(remaining, COPY_BUFFER_SIZE)
+                        out.write(read_at(image, offset, count))
+                        offset += count
+                        remaining -= count
+                        done += count
+                        # (zenity closes at 100: that is left to the caller)
+                        percent = min(99, done * 100 // total)
+                        if percent != shown:
+                            print(percent, flush=True)
+                            shown = percent
+            except ExtractError:
+                raise ExtractError("Could not read %s from the disc image (is it complete?)." % name)
+            except OSError:
+                raise ExtractError("Could not write %s (is the storage full?)." % path)
+
+    # (the maps folder may be there, empty)
+    try:
+        os.makedirs(finished, exist_ok=True)
+        for name, _, _ in files:
+            os.replace(os.path.join(partial, name), os.path.join(finished, name))
+        os.rmdir(partial)
+    except OSError as error:
+        raise ExtractError("Could not move the maps into %s (%s)." % (finished, error.strerror))
+
+
+def main():
+    if len(sys.argv) != 3:
+        print("usage: steam_frame_xiso.py <image> <destination>", file=sys.stderr)
+        return 2
+    try:
+        extract(sys.argv[1], sys.argv[2])
+    except ExtractError as error:
+        print("error: %s" % error, file=sys.stderr)
+        return 1
+    except OSError as error:
+        print("error: Could not open the disc image (%s)." % error.strerror, file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,62 @@
+/*
+FDM_INJECTION_STUB.C
+
+An OpenXR API layer that does nothing, named as the Steam Frame's
+XR_APILAYER_VALVE_fdm_injection names its library
+(libVkLayer_VALVE_fdm_injection.so). The Frame lists that layer as implicit
+for every OpenXR app (/vendor/etc/openxr/1/api_layers/implicit.d), but an
+Android app (in Lepton) cannot load the system's library from its own
+namespace, and the Khronos loader then fails xrCreateInstance altogether;
+nor does the Android loader read the variable that would turn the layer
+off. With this one in the app's libraries the loader finds a layer of that
+name, which hands every call on to the next. (The real layer adds fragment
+density maps to Vulkan apps; this game draws with OpenGL ES.) On a Quest no
+manifest names it and it is never loaded.
+*/
+
+#include <openxr/openxr.h>
+#include <openxr/openxr_loader_negotiation.h>
+#include <stddef.h>
+
+static PFN_xrGetInstanceProcAddr next_get_instance_proc_addr;
+
+static XRAPI_ATTR XrResult XRAPI_CALL layer_get_instance_proc_addr(XrInstance instance, const char *name,
+	PFN_xrVoidFunction *function)
+{
+	if (!next_get_instance_proc_addr)
+		return XR_ERROR_HANDLE_INVALID;
+	return next_get_instance_proc_addr(instance, name, function);
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL layer_create_api_layer_instance(const XrInstanceCreateInfo *info,
+	const XrApiLayerCreateInfo *layer_info, XrInstance *instance)
+{
+	XrApiLayerCreateInfo next_layer_info;
+
+	if (!layer_info || !layer_info->nextInfo)
+		return XR_ERROR_INITIALIZATION_FAILED;
+	next_get_instance_proc_addr = layer_info->nextInfo->nextGetInstanceProcAddr;
+	next_layer_info = *layer_info;
+	next_layer_info.nextInfo = layer_info->nextInfo->next;
+	return layer_info->nextInfo->nextCreateApiLayerInstance(info, &next_layer_info, instance);
+}
+
+__attribute__((visibility("default")))
+XRAPI_ATTR XrResult XRAPI_CALL xrNegotiateLoaderApiLayerInterface(const XrNegotiateLoaderInfo *loader_info,
+	const char *layer_name, XrNegotiateApiLayerRequest *request)
+{
+	(void)layer_name;
+	if (!loader_info || !request || loader_info->structType != XR_LOADER_INTERFACE_STRUCT_LOADER_INFO ||
+		request->structType != XR_LOADER_INTERFACE_STRUCT_API_LAYER_REQUEST ||
+		loader_info->minInterfaceVersion > XR_CURRENT_LOADER_API_LAYER_VERSION ||
+		loader_info->maxInterfaceVersion < XR_CURRENT_LOADER_API_LAYER_VERSION)
+	{
+		return XR_ERROR_INITIALIZATION_FAILED;
+	}
+	request->layerInterfaceVersion = XR_CURRENT_LOADER_API_LAYER_VERSION;
+	request->layerApiVersion = loader_info->maxApiVersion < XR_CURRENT_API_VERSION ? loader_info->maxApiVersion :
+		XR_CURRENT_API_VERSION;
+	request->getInstanceProcAddr = layer_get_instance_proc_addr;
+	request->createApiLayerInstance = layer_create_api_layer_instance;
+	return XR_SUCCESS;
+}
@@ -0,0 +1,32 @@
+Newtown
+Copyright (c) Roger White, 1994. Released by its author into the public domain.
+
+Newtown-Regular.ttf is the TrueType file of Newtown, as Roger White
+distributed it (NEWTOW__.TTF, version 1.00, SHA-256
+376d82c5b660c059c182d848d0a96da9dbe7277d7c8820f6e9a2c99b1a256c65), here
+renamed. OpenCE (OpenCE-Regular.ttf) is made from it by tools/title_font.py.
+
+The file's copyright notice ("All Rights Reserved - see .txt file for terms
+for distribution and use") and the readme it was first distributed with
+(personal use free, commercial use for a fee) date from 1994. Its author
+later released all of his fonts into the public domain. His website,
+rogersfonts.org.uk, said so from 2008 until it closed:
+
+    "Despite what is said in the readme files associated with the fonts all
+    fonts on this site are now public domain, whether used for personal use
+    or for commercial purposes. All that I ask is that the source is
+    acknowledged if you are using any for commercial purposes."
+
+The statement is in the Internet Archive's copies of the site's home page,
+the first of them from 24 July 2008:
+
+    https://web.archive.org/web/20080724224405/http://www.rogersfonts.org.uk/body_index.html
+    https://web.archive.org/web/20110724011202/http://www.rogersfonts.org.uk/body_index.html
+
+and Newtown was one of the site's fonts (its samples are archived from 2004,
+https://web.archive.org/web/20040909032418/http://www.rogersfonts.org.uk/assets/images/Newtown.gif).
+The site says its fonts were made from the author's own hand-drawn artwork,
+scanned and cleaned up.
+
+As he asked, the source is acknowledged: OpenCE is based on Newtown by
+Roger White.
@@ -0,0 +1,95 @@
+Copyright 2026 The OpenCE Project Authors, for its changes to Newtown's spacing.
+OpenCE is based on Newtown, by Roger White (1994), which its author released
+into the public domain (Newtown-LICENSE.txt).
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
@@ -0,0 +1,93 @@
+Copyright 2021 The Overpass Project Authors (https://github.com/RedHatOfficial/Overpass)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
@@ -0,0 +1,45 @@
+# Fonts
+
+The fonts the game's text is drawn with, at the display's resolution, in
+place of the bitmap fonts of the maps (`port/linux/src/text_hires.c`).
+`fonts.json` says which font draws each of the maps' font tags.
+
+| File | Draws | From |
+| --- | --- | --- |
+| `Overpass-900.ttf` | `ui\large_ui`, `ui\interstate` | Overpass, weight 900 (Black) |
+| `Overpass-750.ttf` | `ui\small_ui` | Overpass, weight 750 |
+| `OpenCE-Regular.ttf` | the menus' titles, as pictures (`port/assets/titles`) | OpenCE: Newtown, respaced for this project (`tools/title_font.py`) |
+| `Newtown-Regular.ttf` | (OpenCE's source) | Newtown by Roger White, unmodified |
+
+The maps' fonts are Interstate (Tobias Frere-Jones, The Font Bureau), a
+commercial typeface that cannot be shipped. Overpass (Red Hat, Delve
+Withrington) follows the same Highway Gothic road-sign alphabet and is
+under the SIL Open Font License 1.1 (`Overpass-OFL.txt`), without a
+Reserved Font Name. Matched against the maps' glyphs, its weights 900 and 750 overlap
+them as much as Interstate Bold does, at the same letter widths.
+
+The menus' titles are pictures of text in the maps, set in another
+commercial typeface. OpenCE (Open Community Edition) stands in for it:
+Newtown, a typeface in the same style by Roger White (1994), which its author
+released into the public domain (`Newtown-LICENSE.txt` quotes his statement
+and where it is archived), respaced for this project. Only its spacing is
+changed, its outlines are Newtown's: each letter's side spaces and the
+kerning pairs are measured from where the letters sit in the maps' titles.
+OpenCE is under the SIL Open Font License 1.1 (`OpenCE-OFL.txt`), without a
+Reserved Font Name. It is not embedded: `tools/title_assets.py` draws the
+titles with it, and the builds embed those pictures. To measure its spacing
+again and rebuild it:
+
+    python3 tools/title_font.py --measure    # paste the values into tools/title_font.py
+    python3 tools/title_font.py
+    python3 tools/title_assets.py --map assets/maps/ui.map
+
+The Overpass files are static instances of Google Fonts' variable Overpass
+(`ofl/overpass/Overpass[wght].ttf`, google/fonts commit
+9710da1eacb3be272583c3224dcb70f9da6eadbb), made with fontTools:
+
+    python3 -m fontTools.varLib.instancer 'Overpass[wght].ttf' wght=900 -o Overpass-900.ttf
+    python3 -m fontTools.varLib.instancer 'Overpass[wght].ttf' wght=750 -o Overpass-750.ttf
+
+The builds embed the Overpass files (`tools/embed_assets.py`), and the
+release packages carry `Overpass-OFL.txt`, as the license asks.
@@ -0,0 +1,8 @@
+{
+ "comment": "Which font draws each of the maps' font tags (port/linux/src/text_hires.c).",
+ "fonts": [
+  {"tag": "ui\\large_ui", "file": "Overpass-900.ttf"},
+  {"tag": "ui\\interstate", "file": "Overpass-900.ttf"},
+  {"tag": "ui\\small_ui", "file": "Overpass-750.ttf"}
+ ]
+}