VR roadmap: step 3b, the whole body, done on the Quest

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
VR body: the legs walk the way the player moves, the feet on the ground
2026-10-17 17:00:35 +02:00 · 2026-10-10 14:41:45 +02:00 · 2026-10-10 13:07:47 +02:00 · 2026-10-10 12:34:55 +02:00 · 2026-10-10 12:34:07 +02:00 · 2026-10-10 12:25:34 +02:00
1351 changed files with 236769 additions and 4599 deletions
@@ -0,0 +1,4 @@
+# Files that a Linux shell runs directly must keep LF line endings in a
+# Windows checkout (core.autocrlf): a CRLF shebang line does not start.
+*.sh text eol=lf
+port/android/gradlew text eol=lf
@@ -0,0 +1,38 @@
+name: Problem report
+description: Something does not work as it should
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! Please do **not** ask for, link to or attach game files or disc images; such issues are closed and deleted.
+  - type: dropdown
+    id: headset
+    attributes:
+      label: Headset
+      options:
+        - Meta Quest 3
+        - Meta Quest 3S
+        - Steam Frame
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: build
+    attributes:
+      label: Build number
+      description: The release you installed, e.g. "build 180".
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you did, what you expected and what happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: log
+    attributes:
+      label: Log
+      description: |
+        Attach `debug.txt`. Quest: `Android/data/io.github.cesarus85.ringfall/files/debug.txt` (SideQuest's file manager). Steam Frame: `Documents/RingfallMjolnirVR/debug.txt`, and `logcat.txt` and `install.log` beside it.
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: How to install
+    url: https://github.com/Cesarus85/ringfall-mjolnir-vr#install-on-meta-quest-3--3s
+    about: Step-by-step installation for the Quest 3 / 3S and the Steam Frame.
@@ -8,8 +8,8 @@ name: Build
 # - one job per platform builds both configurations, so its set-up (tools,
 #   downloads, caches) is paid once;
 # - compiles go through ccache, whose cache carries over from run to run, so
-#   a commit only recompiles what it changed; downloads (SDL, musl, Gradle)
-#   are cached too;
+#   a commit only recompiles what it changed; downloads (SDL, musl, Gradle,
+#   the Linux build's system root) are cached too;
 # - a newer push to the same branch cancels a run still going;
 # - pushes that only change documentation do not build;
 # - Windows, whose minutes cost twice Linux's, builds only Windows;
@@ -24,6 +24,11 @@ on:
    paths-ignore:
      - "**.md"
  workflow_dispatch:
+    inputs:
+      profile:
+        description: "Also build the profiling flavour (configure.py --profile) on Linux"
+        type: boolean
+        default: false

 concurrency:
  group: build-${{ github.ref }}
@@ -41,7 +46,11 @@ env:
 jobs:
  linux:
    # Arch Linux has what the build needs as packages: clang 22 (for the
-    # profile-guided optimisation in pgo/) and 32-bit SDL 3.
+    # profile-guided optimisation in pgo/), and CMake, pkg-config and
+    # wayland-scanner for the SDL 3 that the portable build brings. The build
+    # links against Debian 11's 32-bit glibc (tools/linux_sysroot.py), not
+    # Arch's, so that it starts on SteamOS and older distributions; Arch's
+    # 32-bit glibc is for the tests.
    runs-on: ubuntu-24.04
    container: archlinux:latest
    timeout-minutes: 40
@@ -50,7 +59,7 @@ jobs:
        run: |
          printf '\n[multilib]\nInclude = /etc/pacman.d/mirrorlist\n' >> /etc/pacman.conf
          pacman -Syu --noconfirm --needed git zstd python python-pytest ninja ccache \
-            clang lld gcc lib32-glibc lib32-gcc-libs lib32-sdl3
+            clang lld gcc lib32-glibc lib32-gcc-libs cmake pkgconf wayland

      - uses: actions/checkout@v4

@@ -60,14 +69,29 @@ jobs:
          key: ccache-linux-${{ github.sha }}
          restore-keys: ccache-linux-

+      # the system root and SDL's source, which the build downloads
+      - uses: actions/cache@v4
+        with:
+          path: build/linux/third_party
+          key: linux-third-party-${{ hashFiles('tools/linux_sysroot.py') }}
+
      - name: Debug
        run: python tools/ci_build.py linux debug

+      # (the profiling build, configure.py --profile, which no other step
+      # compiles: only when a run started by hand asks for it, as it costs a
+      # build of its own)
+      - name: Profile
+        if: github.event_name == 'workflow_dispatch' && inputs.profile
+        run: python tools/ci_build.py linux profile
+
      - name: Release
        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 tools/test_host_watch_hash.py tools/test_touch_menu.py tools/harness tools/test_profile.py
+          python tools/test_light_storage.py

      - name: Compile cache
        run: ccache --show-stats
@@ -110,7 +134,7 @@ jobs:
      - uses: actions/cache@v4
        with:
          path: build/android/third_party
-          key: android-third-party-${{ hashFiles('tools/android_build.py') }}
+          key: android-third-party-${{ hashFiles('tools/android_build.py', 'port/android/patches/**') }}

      - uses: actions/cache@v4
        with:
@@ -145,6 +169,10 @@ jobs:
          HALO_ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
        run: python3 tools/ci_build.py android release

+      # the touch controls' layout and gyroscope maths (the runner's JDK)
+      - name: Test the touch layout
+        run: python3 tools/test_touch_layout.py
+
      - name: Compile cache
        run: ccache --show-stats

@@ -200,6 +228,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

@@ -215,8 +246,22 @@ jobs:
          path: dist/halo-windows-release
          retention-days: 3

+      # the PDBs, for crash reports' backtraces (tools/ci_build.py)
+      - uses: actions/upload-artifact@v4
+        with:
+          name: halo-windows-debug-symbols
+          path: dist/halo-windows-debug-symbols
+          retention-days: 3
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: halo-windows-release-symbols
+          path: dist/halo-windows-release-symbols
+          retention-days: 3
+
  release:
-    # The six builds as a release, tagged build-<run number> and marked latest
+    # The six builds (and the Windows builds' PDBs) as a release, tagged
+    # build-<run number> and marked latest
    # (every file keeps its name from release to release, for the README's
    # latest/download links); then all but the newest five build-* releases
    # go, tags and all. Only for main, and only when every platform built.
@@ -232,6 +277,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-*
@@ -240,13 +292,18 @@ jobs:
      - name: Package
        run: |
          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" .)
+          # (Ringfall: Mjolnir VR publishes its Android builds only, under
+          # its own name: Updater.java looks for them; the desktop ports are
+          # built to keep them building)
+          for config in debug release; do
+            (cd "artifacts/halo-android-$config" &&
+              zip -qr "$GITHUB_WORKSPACE/release/ringfall-mjolnir-vr-android-$config.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"
+          # the APK itself, for sideloading on the Quest (SideQuest, adb)
+          cp artifacts/halo-android-release/app-release.apk release/RingfallMjolnirVR.apk
          ls -l release

      - name: Publish
@@ -258,12 +315,50 @@ jobs:
        run: |
          tag="build-$GITHUB_RUN_NUMBER"
          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 \
-            --title "Build $GITHUB_RUN_NUMBER (${GITHUB_SHA:0:7})" --notes-file notes.md
+          readme="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY"
+          {
+            printf '%s\n\n' "$subject"
+            printf '**Ringfall: Mjolnir VR** is an unofficial VR mod for Halo: Combat Evolved. It needs a disc image of your own, purchased Xbox copy of the game; no game files are included.\n\n'
+            printf '| Headset | Download | How to install |\n| --- | --- | --- |\n'
+            printf '| Meta Quest 3 / 3S | `RingfallMjolnirVR.apk` | [Install on Quest](%s#install-on-meta-quest-3--3s) |\n' "$readme"
+            printf '| Steam Frame | `Install-Ringfall-Mjolnir-VR.desktop` (open it in Desktop Mode) | [Install on Steam Frame](%s#install-on-steam-frame) |\n\n' "$readme"
+            printf 'The other files are for the built-in updater and the Steam Frame installer.\n\n'
+            printf 'Commit: %s\nBuild: %s\n' "$COMMIT_URL" "$RUN_URL"
+          } > notes.md
+          gh release create "$tag" release/* --target "$GITHUB_SHA" --latest \
+            --title "Ringfall: Mjolnir VR, build $GITHUB_RUN_NUMBER (${GITHUB_SHA:0:7})" --notes-file notes.md
          echo "tag=$tag" >> "$GITHUB_OUTPUT"

+      # The Windows builds' executables and PDBs to Sentry, which turns the
+      # crash reports of these builds (port/windows/src/win32_crash.c) into
+      # backtraces with function names and lines. Needs the SENTRY_AUTH_TOKEN
+      # secret: an organization auth token of the Sentry organization, which
+      # names the organization and its region itself. The SENTRY_PROJECT
+      # variable can name the project (its slug), else the id in the DSN of
+      # win32_crash.c; SENTRY_ORG and SENTRY_URL (https://de.sentry.io) are
+      # for a personal token instead. A failed upload does not stop the
+      # release.
+      - name: Upload Windows symbols to Sentry
+        continue-on-error: true
+        env:
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+          SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT || '4512207917744208' }}
+          ORG: ${{ vars.SENTRY_ORG }}
+          URL: ${{ vars.SENTRY_URL }}
+          SENTRY_CLI_VERSION: 2.46.0
+        run: |
+          if [ -z "$SENTRY_AUTH_TOKEN" ]; then
+            echo "::warning::no SENTRY_AUTH_TOKEN secret: crash reports of this build will have no function names"
+            exit 0
+          fi
+          if [ -n "$ORG" ]; then export SENTRY_ORG="$ORG"; fi
+          if [ -n "$URL" ]; then export SENTRY_URL="$URL"; fi
+          curl -fsSL -o sentry-cli "https://github.com/getsentry/sentry-cli/releases/download/$SENTRY_CLI_VERSION/sentry-cli-Linux-x86_64"
+          chmod +x sentry-cli
+          ./sentry-cli debug-files upload --wait \
+            artifacts/halo-windows-release artifacts/halo-windows-release-symbols \
+            artifacts/halo-windows-debug artifacts/halo-windows-debug-symbols
+
      - name: Keep the last five
        run: |
          gh release list --limit 100 --json tagName,createdAt \
@@ -316,7 +411,7 @@ jobs:
            title="Build failed"; color=15548997
          fi
          latest="$SERVER/$REPOSITORY/releases/latest"
-          downloads="[Linux]($latest/download/halo-linux-release.zip) · [Windows]($latest/download/halo-windows-release.zip) · [Android]($latest/download/halo-android-release.zip) ([all builds]($latest))"
+          downloads="[Quest]($latest/download/ringfall-mjolnir-vr-android-release.zip) · [Steam Frame]($latest/download/Install-Ringfall-Mjolnir-VR.desktop) ([all builds]($latest))"
          if [ -n "$RELEASE_TAG" ]; then
            release="[$RELEASE_TAG]($SERVER/$REPOSITORY/releases/tag/$RELEASE_TAG)"
          else
@@ -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
@@ -0,0 +1,209 @@
+# Notes for agents
+
+This repository ports the Halo: Combat Evolved decompilation (Xbox build
+01.01.14.2342, `cachebeta.exe`) to Linux, Windows and Android. The game's C
+sources are the decompilation; the port adds a platform layer that
+implements the Xbox APIs the game calls, and features the Xbox game did not
+have (a new netcode, internet play, the PC version's menus, Custom Edition
+maps, touch controls). The project is published as OpenCE.
+
+Start with [README.md](README.md). The other documents are listed at the
+end.
+
+## Layout
+
+| Path | Contents |
+| --- | --- |
+| `source/` | The game: 466 C files of the decompilation, compiled as they are with few changes (each marked, below) |
+| `port/linux/src/` | The platform layer the three ports share: Direct3D 8 on OpenGL (`d3d8_gl.c`), DirectSound and XInput on SDL3, files, threads, memory, sockets, settings (`port_config.c`), internet play (`p2p*.c`) |
+| `port/linux/game/` | The port's game-side code, compiled as the game's sources are: the distributed netcode (`network_*.c`), co-op, the menus (`menu_tags.c`, `menu_functions.c`), Custom Edition maps (`custom_edition_*.c`, `cache_file_formats.c`), the tag validator (`tag_validate.c`, `tag_schema_*.c`), touch, FOV and more |
+| `port/linux/include/` | The port's headers: the limits (`halo_port_limits.h`, with `HALO_PORT_NETWORK_VERSION`), capacities (`halo_port_capacity.h`), the prefix header, `halo_linux_source_fixups.h` (port functions the game's sources call) |
+| `port/include/xdk/` | Stand-ins for the Xbox SDK's headers (declarations only) |
+| `port/windows/` | The Windows build's own files (`win32_*.c`, headers) |
+| `port/android/` | The Android app: the guest runtime, the host library (`host/`), the Java app (`app/`), host imports (`host_imports.list`) |
+| `port/assets/` | What the builds embed or ship: high-res HUD (`hud/`), fonts, titles, menus (`menus/`), icons, network brokers |
+| `port/third_party/` | Vendored libraries, each with a README naming its upstream, version and checksum |
+| `port/tools/` | Stand-alone tools (`cache_file_report.c`) |
+| `tools/` | Build scripts (`linux_build.py`, `windows_build.py`, `android_build.py`, `ci_build.py`), generators (`ce_menus.py`, `port_settings.py`, `hud_assets.py`, `title_assets.py`, `embed_assets.py`, `xdk_headers.py`) and tests |
+| `docs/` | Longer design notes (`custom_edition_caches.md`) |
+| `pgo/` | Profile-guided optimisation profiles |
+| `assets/` | Game data for local runs (gitignored: `maps/`, `custom_maps/`) |
+| `.github/workflows/` | CI: builds every platform on each push, publishes releases from `main` |
+
+## Building
+
+```sh
+python configure.py            # debug build; add --release, --portable, --profile, --pgo=off, --lto=off
+ninja linux                    # build/linux/halo
+ninja android                  # the Android guest image and native libraries
+ninja android_apk              # the APK (Gradle)
+ninja windows                  # on Windows only
+python tools/ci_build.py linux release   # what CI builds
+```
+
+- `configure.py` writes `build.ninja`; `configure_args` at its top records
+  the options it was run with. Restore them after trying other options.
+- The Linux and Windows builds are 32-bit x86 with clang, in MSVC's ABI
+  (`-fms-extensions -fshort-wchar -malign-double -fcommon`), C89 (`gnu89`):
+  declarations come before statements.
+- Every native build compiles without fused multiply-add and with the
+  vendored musl maths (`halo_math.h`), so that every machine of a network
+  game computes the same results. Do not call the system's maths functions.
+- Android: the game is an ILP32 AArch64 guest (`arm64_32`) in a 64-bit app.
+  Guest code can call only the host imports declared in
+  `port/android/host_imports.list` and `port/android/guest/runtime/guest_host.h`,
+  and only the SDL functions `guest_sdl.c` bridges. Run `ninja android`
+  after changing anything it compiles: `port/linux/src`, `port/linux/game`,
+  `port/android`, `source/`, the build scripts.
+
+### Defines
+
+| Define | Set by | Meaning |
+| --- | --- | --- |
+| `HALO_ANDROID` | Android | The app: its display, input, files and lifecycle |
+| `HALO_GLES` | Android | The OpenGL ES renderer |
+| `HALO_ARM64_GUEST` | Android | The guest's ABI (ILP32 AArch64) |
+| `HALO_WINDOWS` | Windows (`halo_windows_prefix.h`) | The Windows build |
+| `HALO_RELEASE` | `--release` | No assertions checked |
+| `HALO_PROFILE` | `--profile` | The profiling build; a normal build must be unchanged by it |
+
+`HALO_LINUX` and `HALO_CUSTOM_EDITION` are **not** defined by any build:
+code guarded by them compiles to nothing. Custom Edition support is a
+setting (`game.custom_edition`), checked at run time with
+`custom_edition_cache_tags_loaded()`.
+
+## Testing
+
+```sh
+python -m pytest -q tools/harness tools/test_touch_menu.py   # the engine's functions in a fake world
+python -m pytest -q tools/test_linux_port.py                # the build, the maps' checks (needs assets/maps)
+python -m pytest -q tools/test_cache_file_formats.py tools/test_bmp_files.py tools/test_profile.py
+python tools/test_touch_layout.py                           # the Android touch layout (JDK 17+)
+python tools/test_light_storage.py
+python tools/test_death_timing.py
+```
+
+`tools/harness/README.md` explains how to add an asset-free test: the code
+under test is taken from the sources, not copied.
+
+Running the game without a person at it:
+
+- `debug.network_test` (`HALO_NETWORK_TEST=host:<map>` or `join`) hosts or
+  joins a game without the menus and logs each player's state every second;
+  several copies play on one machine on different loopback addresses
+  (`HALO_NET_ADDRESS`, `HALO_NET_BROADCAST`). `NETCODE.md` describes the
+  test settings.
+- `debug.exit_after`, `debug.hidden_window`, `debug.null_renderer`,
+  `debug.menu_open` (start on one menu screen), `debug.telnet_console`.
+- Use a virtual display (Xvfb, with `SDL_VIDEO_DRIVER=x11`) for windowed
+  runs, never the desktop of the person you work for, and stop only the
+  processes you started.
+
+## Rules of the project
+
+### The game's sources
+
+- Change `source/` as little as possible, and mark each change from the
+  original with a comment that starts `port:`. Write like the surrounding
+  code: its naming, its comment density, and the project's plain,
+  descriptive comment style.
+- A port function the game's sources call is declared in
+  `halo_linux_source_fixups.h` or included with a note naming its file
+  (`#include "view_fov.h" /* port: port/linux/game/view_fov.c */`).
+- Notes such as `BUG (original, preserved for exact matching)` mark the
+  original's bugs. Fixing one is allowed; say so in a `port:` comment.
+
+### The Xbox SDK
+
+`port/include/xdk` was written without the SDK's headers, from the January
+build's debug information and public documentation. Never read the SDK's
+headers or anything derived from them, never copy from them, and do not
+read `xbox/include`. To add a name, follow `port/include/xdk/README.md`.
+
+### Networking
+
+- Raise `HALO_PORT_NETWORK_VERSION` (`port/linux/include/halo_port_limits.h`)
+  with any change to what the machines send each other, or to anything they
+  must agree on, and say why in the commit. Machines of different versions
+  do not play together.
+- Only the host decides; clients predict their own players. Read
+  `port/linux/NETCODE.md` before changing the netcode.
+- Anything another machine sends is untrusted: check sizes, indices and
+  rates, as the existing handlers do. `debug.network_corrupt` tests this.
+
+### Menus
+
+- The menus must match Halo Custom Edition's. Their XML (`port/assets/menus/ce/`)
+  is generated by `tools/ce_menus.py` from the PC version's tags; the
+  settings screens come from `tools/port_settings.py`. Do not edit the XML
+  by hand: change the generator and run it (the command is in
+  `port/assets/menus/README.md`, "Writing them again"), then check that
+  `git status` shows only the screens meant to change.
+- Functions the menus call but the port has not wired are listed in
+  `port/assets/menus/UNWIRED.md`.
+
+### Art and credit
+
+- Replacement HUD, title and menu art is made of hand-drawn redraws.
+- Prefer an existing redraw (the ui-svg-handmade set), then a new redraw. A
+  Custom Edition picture that cannot reasonably be redrawn (a 3D render, a
+  screenshot, a logo) may be used only if it is listed in
+  `port/assets/menus/NON_HANDDRAWN.md`.
+- `AUTHORS.md` credits art only.
+- Fonts: Overpass and OpenCE (Newtown, respaced) only; see
+  `port/assets/fonts/README.md`. Never ship the maps' commercial typefaces.
+
+### Custom Edition maps
+
+Custom Edition maps live in the data root's `custom_maps` folder with
+`bitmaps.map`, `sounds.map` and `loc.map`; their level names are
+`custom_maps\<name>`. OpenSauce features are not supported and must not be
+added: a map that needs them is refused, and one that only carries
+OpenSauce's header runs as stock Custom Edition runs it. Map files are
+untrusted input: read them through bounds-checked readers. See
+`docs/custom_edition_caches.md`.
+
+### Settings
+
+A setting is an entry in `port/linux/src/port_config.c`, with a default, an
+environment variable and a comment that `config.toml` gets. Document it in
+the settings table of `port/linux/README.md` (and the Android README for an
+Android-only one). A departure from the stock game's look or behaviour
+should be a setting, off or stock by default, unless the project decides
+otherwise.
+
+### Third-party code and licences
+
+The repository is CC0. Vendored code goes in `port/third_party/<name>`,
+copied unchanged, with a README naming the upstream, the version or commit,
+the checksum and what uses it. GPL code (OpenSauce, Reclaimer) may be read
+as documentation of file formats, never copied.
+
+### Commits and pull requests
+
+- Commit subjects are plain sentences saying what changed; the body says
+  why and what was checked.
+- A pull request is merged with a merge commit (`Merge pull request #N from
+  <owner>/<branch>`), and follow-up changes go in separate commits whose
+  subject ends with `(#N)`.
+- A commit taken from a fork keeps its author and is made with
+  `git cherry-pick -x`.
+
+## Documents
+
+| Document | About |
+| --- | --- |
+| [README.md](README.md) | Downloads, game data, building, build options, profiling builds |
+| [port/linux/README.md](port/linux/README.md) | The Linux build, controls, menus, every setting, updates, frame rate, field of view, system link, internet play, voice chat, the server browser, security, map checks, how the port operates, the game source changes |
+| [port/linux/NETCODE.md](port/linux/NETCODE.md) | The distributed netcode, network versions, joining a game in progress, transport, testing |
+| [port/windows/README.md](port/windows/README.md) | The Windows build, its headers, inline functions, crash reports |
+| [port/android/README.md](port/android/README.md) | The Android build, the guest and host, touch controls, Android settings, finding problems |
+| [port/include/xdk/README.md](port/include/xdk/README.md) | How the SDK declarations were written and are checked |
+| [docs/custom_edition_caches.md](docs/custom_edition_caches.md) | Loading and converting Custom Edition maps, and the evidence for each layout |
+| [port/assets/menus/README.md](port/assets/menus/README.md) | The menu files' format and how to write them again |
+| [port/assets/menus/NON_HANDDRAWN.md](port/assets/menus/NON_HANDDRAWN.md) | Menu pictures that are not redraws |
+| [port/assets/menus/UNWIRED.md](port/assets/menus/UNWIRED.md) | Menu functions that do nothing yet |
+| [port/assets/fonts/README.md](port/assets/fonts/README.md) | The fonts and their licences |
+| [tools/harness/README.md](tools/harness/README.md) | Asset-free regression tests |
+| `port/third_party/*/README.md` | Each vendored library |
+| [AUTHORS.md](AUTHORS.md) | Art credits |
@@ -0,0 +1,14 @@
+# Authors
+
+## Art
+
+- **The game's icon** (the Android app's launcher icon, `halo.exe`'s icon
+  and the desktop windows' icon): by ORION (`port/assets/icon`).
+
+## Third-party art
+
+- **Voice chat's speaker icons** (who talks, and who is muted, in the lobby,
+  on the scoreboard and in the game): `volume-2` and `volume-x` from
+  [Lucide](https://lucide.dev) 1.53.0, copyright (c) 2026 Lucide Icons and
+  Contributors, under the ISC licence
+  (`port/assets/icons/lucide/LICENSE`).
@@ -1,140 +1,198 @@
-# Halo: Combat Evolved for Linux, Windows and Android
+<p align="center">
+  <img src="port/android/steam_frame_grid/library.png" width="640" alt="Ringfall: Mjolnir VR">
+</p>

-[![Join our Discord](https://invidget.switchblade.xyz/9gqcHyr5km)](https://discord.gg/9gqcHyr5km)
+# Ringfall: Mjolnir VR

-This project is a port of the Halo: Combat Evolved decompilation to Linux,
-Windows and Android. The decompilation is of the Xbox build 2342
-(`cachebeta.exe`, SHA-256
-`4cc87b45f721270392a96f1674ed2b5cd4a7bb4355faeab4531d1cf1884d9520`).
+**A VR mod for Halo: Combat Evolved** (the original Xbox game) on the
+**Meta Quest 3 / 3S** and the **Steam Frame**. Play the campaign and
+multiplayer in full 6DoF virtual reality, with your hands in the game.

-<img width="1289" height="995" alt="The game on Linux" src="https://github.com/user-attachments/assets/0d3ad50f-f8b8-46cf-aef8-e3661da2a7d7" />
+Ringfall: Mjolnir VR runs on your headset by itself, without a PC. It
+brings no game files: it uses a disc image of **your own, purchased copy**
+of the game.

-The port starts from the decompilation of [bnunu/halo-1](https://github.com/bnunu/halo-1).
-That project is a fork of [punpckhdq/halo](https://github.com/punpckhdq/halo).
+> **Unofficial fan project.** Ringfall: Mjolnir VR is a free,
+> non-commercial fan project. It is not affiliated with, endorsed,
+> sponsored or approved by Microsoft, Xbox Game Studios, Halo Studios or
+> Bungie. See [Legal](#legal).

-## Download
+## Contents

-GitHub Actions builds the game for each commit. These links download the
-builds of the latest release:
+- [What you get](#what-you-get)
+- [What you can play](#what-you-can-play)
+- [What you need](#what-you-need)
+- [Install on Meta Quest 3 / 3S](#install-on-meta-quest-3--3s)
+- [Install on Steam Frame](#install-on-steam-frame)
+- [Playing](#playing)
+- [Problems and questions](#problems-and-questions)
+- [Credits](#credits)
+- [Legal](#legal)

-| 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) |
+## What you get

-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
-problems.
+- **Full VR**: stereo 6DoF at your headset's refresh rate (72 to 120 Hz);
+  the HUD, menus, scope and crosshair float as layers of their own.
+- **Your hands in the game**: the weapon sits in your hand and fires
+  where you point it; arms and fingers follow your controllers;
+  two-handed weapons, melee by swinging, grenades thrown with your hand,
+  crouching and leaning with your body.
+- **Vehicles**: steer the Warthog by turning its wheel with both hands;
+  turrets with handles.
+- **Comfort**: snap or smooth turning in fine steps, comfort vignettes,
+  left-handed mode, buttons remapped freely, graphics presets, refresh
+  rate and resolution, all in the in-game VR options (**Y**).
+- **The PC version's menus**, clicked with a laser pointer, and an
+  on-screen keyboard for names, codes and passwords.

-The game updates itself. At start-up it looks for a newer release, and asks
-if you want to install it. Refer to "Updates" in
-[port/linux/README.md](port/linux/README.md#updates).
+## What you can play

-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)
-page keeps the last five releases. If the latest build has a problem, get
-an older build from that page.
+- **The whole campaign**: all ten missions, on every difficulty, saved as
+  you go.
+- **Co-op campaign** with friends, online or on your local network, with
+  settings for friendly fire and extra enemies per player.
+- **LAN multiplayer** (system link) with everyone on your network.
+- **Online multiplayer**, no server of your own needed: host a game and
+  share its join code, find public games in the server browser, or protect
+  a lobby with a password. Up to 128 players.
+- **Bots** to fill a game, on foot, in vehicles and at turrets; they make
+  room when a person joins.
+- **All 13 multiplayer maps** and the Xbox game's game types: Slayer,
+  Capture the Flag, King of the Hill, Oddball and Race.
+- **Cross-play**: VR players on the Quest and the Steam Frame, together with
+  players of the PC and phone builds of
+  [OpenCE](https://github.com/OpenCommunityEdition/OpenCE).

-## Game data
+## What you need

-The port does not include the game data. Download an Xbox disc image
-(`.xiso` or `.iso`) of Halo: Combat Evolved. All versions of the game
-operate. The maps of the European (PAL) version were made for a slower
-console. The port changes them to play as the North American (NTSC) maps do,
-so players of the two versions can play together.
+- A **Meta Quest 3 / 3S** or a **Steam Frame**.
+- A **disc image** (`.iso` or `.xiso`) of **Halo: Combat Evolved for the
+  original Xbox**, made from **a disc you own**. Any region and version
+  works.

-1. Start the game.
-2. At the first start, the game asks for the disc image. Select it.
-3. The game extracts the `maps/` folder. Then the game starts.
+This project does not include, link to or help find game files. Please
+do not ask for or share disc images in issues or discussions; such posts
+are deleted.

-On Linux and Windows, the game puts `maps/` next to the executable. On
-Android, copy the disc image to the phone first. The app puts `maps/` in its
-data folder. Refer to [port/android/README.md](port/android/README.md).
+## Install on Meta Quest 3 / 3S

-## Platforms
+You install the game once with a computer (Windows, macOS or Linux); after
+that it updates itself.

-Each platform has its own instructions:
+1. **Turn on Developer Mode** for your Quest, once: in the Meta Horizon
+   app on your phone, open your headset's settings, then *Developer
+   Mode* (Meta asks you to create a free developer account first).
+2. **Install [SideQuest](https://sidequestvr.com/setup-howto)** (the
+   "Advanced Installer") on your computer and connect the Quest with a
+   USB cable. In the headset, allow USB debugging for this computer.
+3. **Download `RingfallMjolnirVR.apk`** from the
+   [latest release](../../releases/latest) and drag it onto the SideQuest
+   window. It installs the game.
+4. **Copy your disc image** to the Quest's `Download` folder: in
+   SideQuest, open the file manager (the folder icon), go to `Download`
+   and drag the `.iso` file in.
+5. **In the headset**, open your *Library*, choose *Unknown Sources* and
+   start **Ringfall: Mjolnir VR**. Select **Choose disc image** and pick
+   your file in `Download`. The game copies what it needs (about 1.8 GB,
+   a minute or two) and starts.

-| Platform | Instructions |
-| --- | --- |
-| Linux (32-bit x86 executable, OpenGL 4.5, SDL3) | [port/linux/README.md](port/linux/README.md) |
-| Windows (32-bit x86 executable, OpenGL 4.5, SDL3) | [port/windows/README.md](port/windows/README.md) |
-| Android (arm64 app, OpenGL ES 3, SDL3) | [port/android/README.md](port/android/README.md) |
+You can delete the disc image from `Download` afterwards. When a new
+version comes out, the game asks you at start whether to update.

-The Linux README also gives the controls, the settings and the multiplayer
-functions. These are almost the same on all platforms.
+## Install on Steam Frame

-## Multiplayer
+No computer and no keyboard needed.

-The game can play system link games on a local network and on the internet:
+1. **Switch to Desktop Mode**: press the Steam button, then *Power* >
+   *Switch to Desktop*.
+2. **Put your disc image** in the `Downloads` folder (for example from a
+   USB stick or memory card with the file manager, Dolphin).
+3. **Download `Install-Ringfall-Mjolnir-VR.desktop`** from the
+   [latest release](../../releases/latest) with the web browser.
+4. **Open it**: in Dolphin, open `Downloads` and double-click the file.
+   If you are asked whether to run it, choose to continue.
+5. **Answer the dialogs.** The installer finds your disc image, copies
+   what the game needs, adds **Ringfall: Mjolnir VR** to your Steam
+   library and offers to switch back to Gaming Mode.
+6. Start **Ringfall: Mjolnir VR** from your library (under *Non-Steam*).

- A system link game can have up to 128 players on up to 128 machines.
- Linux, Windows and Android machines can play in the same game.
- An invite link lets a machine join a game on the internet. No server of
-  this project is necessary.
- The netcode is new. Each machine moves its own player at once,
-  and the host makes the decisions for the game. Refer to
-  [port/linux/NETCODE.md](port/linux/NETCODE.md).
+To update, open the same file in Desktop Mode again; your settings,
+saves and game data stay. More about the Steam Frame:
+[port/android/STEAM_FRAME.md](port/android/STEAM_FRAME.md).

-## Build the game
+## Playing

-You do not need the Xbox SDK. The port supplies the SDK declarations that
-the game uses. Refer to [port/include/xdk](port/include/xdk/README.md).
+- **Y** opens the VR options in the main and pause menus: turning,
+  comfort, weapon hand, buttons, graphics, refresh rate and resolution.
+  *Quit the game* is on its last page.
+- In the menus, point with a controller and pull the trigger to click.
+- The controller layout is on the VR options' *Controller buttons* page.

-To build the game:
+## Problems and questions

-1. Install Python and [ninja](https://ninja-build.org/).
-2. Install the tools for your platform. Refer to the README for the
-   platform.
-3. In the root folder of the repository, enter `python configure.py`.
-4. Enter `ninja` with the target for the platform:
+Please open an [issue](../../issues) and include:

-| Target | Result |
-| --- | --- |
-| `ninja linux` | `build/linux/halo` |
-| `ninja windows` (on Windows) | `build/windows/halo.exe` and `SDL3.dll` |
-| `ninja android_apk` | `port/android/app/build/outputs/apk/debug/app-debug.apk` |
+- your headset and the build number of the release you installed;
+- what you did and what happened;
+- the game's log, `debug.txt`:
+  - Quest: `Android/data/io.github.cesarus85.ringfall/files/debug.txt`
+    (SideQuest's file manager);
+  - Steam Frame: `Documents/RingfallMjolnirVR/debug.txt` (and
+    `logcat.txt` and `install.log` beside it).

-If you enter `ninja` without a target, ninja builds the game for the
-computer that you use.
+What is done and what comes next: [port/android/VR_ROADMAP.md](port/android/VR_ROADMAP.md).

-`tools/ci_build.py` makes the same builds as GitHub Actions. For example,
-enter `python tools/ci_build.py linux release`.
+**Network use.** The game connects to the internet only for what you
+use: the update check (GitHub), online games (to other players
+directly), and join codes and lobby lists through public MQTT brokers
+(listed in [brokers.txt](port/assets/network/brokers.txt)). There is no
+telemetry.

-### Build options
+## Credits

-Give these options to `configure.py`:
+Ringfall: Mjolnir VR stands on the work of others:

-| Option | Result |
-| --- | --- |
-| (none) | A debug build. A failed assertion stops the game. |
-| `--release` | A release build. The game does not examine assertions, as in the retail game. |
-| `--portable` | The Linux and Windows builds operate on all x86-64 processors. Use this option for builds that you give to other persons. |
-| `--lto=thin`, `--lto=off` | Less link-time optimization. The link is faster. |
-| `--pgo=off` | No profile-guided optimization. |
-| `--pgo=train` | Records a new optimization profile. Refer to "Optimization profiles". |
+- **[OpenCE](https://github.com/OpenCommunityEdition/OpenCE)** (Open
+  Community Edition): the port of the decompiled game to Linux, Windows
+  and Android, with its renderer, netcode, PC menus and multiplayer, that
+  this project builds on and follows.
+- **The decompilation**: [bnunu/halo-1](https://github.com/bnunu/halo-1),
+  a fork of [punpckhdq/halo](https://github.com/punpckhdq/halo).
+- **[HaloCE-Quest-VR](https://github.com/moistman42069/HaloCE-Quest-VR)**
+  by moistman42069 (CC0): the arm IK, the forearm's twist and the
+  fingers' poses are taken from it (`port/linux/game/vr_arms.c`); the
+  left-handed mode and the graphics presets follow its ideas.
+- **[HaloCE-VR](https://github.com/astromaddie/HaloCE-VR)** by astromaddie
+  (CC0): the Steam Frame work, whose findings (such as quieting Mesa's
+  trace markers) are used here.
+- **[extract-xiso](https://github.com/XboxDev/extract-xiso)**: the disc
+  image readers follow its format handling.
+- The libraries and fonts in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

-Without `--portable`, the Linux and Windows builds use all the instructions
-of the processor that builds them (`-march=native`). Such a build does not
-always start on a different computer.
+Thank you all.

-### Optimization profiles
+## Building it

-The builds use profiles of the game to optimize the code:
+`python3 configure.py --release`, then `ninja android_apk` (Android SDK
+and NDK needed). See [port/android/README.md](port/android/README.md) for
+the details and [docs/OPENCE_README.md](docs/OPENCE_README.md) for the
+port it is built on.

- `pgo/halo_linux.profdata` for Linux and Android.
- `pgo/halo_windows.profdata` for Windows.
+## Legal

-The profiles need clang 22 or later. With an older clang, the builds do not
-use the profiles.
+Ringfall: Mjolnir VR is an unofficial, free, non-commercial fan project.
+It is not affiliated with, endorsed, sponsored or approved by Microsoft
+Corporation, Xbox Game Studios, Halo Studios or Bungie. Halo, Halo: Combat
+Evolved and Xbox are trademarks of Microsoft Corporation; they are named
+here only to say which game this mod works with. Meta Quest is a trademark
+of Meta Platforms, Inc.; Steam and Steam Frame are trademarks of Valve
+Corporation.

-To record a new profile:
+No game data, art, music or other content of the game is included or
+distributed. You need your own, legally purchased copy of the game. If
+you enjoy this mod, please support the creators of the original by buying
+their games.

-1. Delete the profile.
-2. Enter `python configure.py --pgo=train`.
-3. Enter `ninja linux` or `ninja windows`.
-
-The build then plays the main menu and the first minute of each campaign
-level. This procedure continues for approximately 15 minutes. The game
-data must be in `assets/`.
+This project's own code is released under [CC0 1.0](LICENSE.md), as the
+decompilation it builds on. Third-party code and fonts keep their own
+licenses: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
@@ -0,0 +1,46 @@
+# Third-party notices
+
+Ringfall: Mjolnir VR's own code is released under [CC0 1.0](LICENSE.md).
+It includes or builds on the following, under their own licenses; each
+license's full text is in the file named.
+
+## Code
+
+| Component | Used for | License | Text |
+| --- | --- | --- | --- |
+| [OpenCE](https://github.com/OpenCommunityEdition/OpenCE) and the decompilation ([bnunu/halo-1](https://github.com/bnunu/halo-1), [punpckhdq/halo](https://github.com/punpckhdq/halo)) | the game's code, the port | CC0 1.0 | [LICENSE.md](LICENSE.md) |
+| [HaloCE-Quest-VR](https://github.com/moistman42069/HaloCE-Quest-VR) | the arm IK, forearm twist and finger poses (`port/linux/game/vr_arms.c`) | CC0 1.0 | (its repository) |
+| [HaloCE-VR](https://github.com/astromaddie/HaloCE-VR) | Steam Frame findings | CC0 1.0 | (its repository) |
+| [SDL 3](https://libsdl.org) | windows, input, sound | zlib | (in SDL's source, `LICENSE.txt`) |
+| [Khronos OpenXR loader](https://github.com/KhronosGroup/OpenXR-SDK) | VR runtime access | Apache 2.0 | (in the loader's package) |
+| [musl](https://musl.libc.org) | the C library of the game's code on Android, its maths | MIT | [port/third_party/musl-math](port/third_party/musl-math/README.md) |
+| [Expat](https://libexpat.github.io) | the PC menus' definitions | MIT | [port/third_party/expat/COPYING](port/third_party/expat/COPYING) |
+| [Mbed TLS](https://www.trustedfirmware.org/projects/mbed-tls/) | HTTPS for the desktop builds' updater (not in the Android app) | Apache 2.0 | [port/third_party/mbedtls/LICENSE](port/third_party/mbedtls/LICENSE) |
+| [miniupnpc](https://miniupnp.tuxfamily.org) | router port forwarding for online games | BSD 3-Clause | [port/third_party/miniupnpc/LICENSE](port/third_party/miniupnpc/LICENSE) |
+| [KCP](https://github.com/skywind3000/kcp) | reliable transport for online games | MIT | [port/third_party/kcp/LICENSE](port/third_party/kcp/LICENSE) |
+| [Monocypher](https://monocypher.org) | signing public games' listings (Ed25519); online play's other cryptography is the port's own | CC0 1.0 or BSD 2-Clause | [port/third_party/monocypher/LICENCE.md](port/third_party/monocypher/LICENCE.md) |
+| [tomlc17](https://github.com/cktan/tomlc17) | reading `config.toml` | MIT | [port/third_party/tomlc17/LICENSE](port/third_party/tomlc17/LICENSE) |
+| [stb](https://github.com/nothings/stb) | drawing the game's text sharply (stb_truetype) | MIT or public domain | [port/third_party/stb/LICENSE](port/third_party/stb/LICENSE) |
+| [SMAA](https://www.iryoku.com/smaa/) | anti-aliasing (flat screens; off in VR) | MIT | [port/third_party/smaa/LICENSE](port/third_party/smaa/LICENSE) |
+| [extract-xiso](https://github.com/XboxDev/extract-xiso) | reading disc images (followed by `XisoExtractor.java`, `steam_frame_xiso.py`, `xiso.c`) | BSD-style (in@fishtank.com) | [port/third_party/extract-xiso/LICENSE.TXT](port/third_party/extract-xiso/LICENSE.TXT) |
+
+The disc image readers include this acknowledgement, as extract-xiso's
+license asks: *This product includes software developed by in
+&lt;in@fishtank.com&gt;.*
+
+## Fonts
+
+| Font | Used for | License | Text |
+| --- | --- | --- | --- |
+| Overpass (Red Hat, Delve Withrington) | the game's text, the library pictures | SIL Open Font License 1.1 | [port/assets/fonts/Overpass-OFL.txt](port/assets/fonts/Overpass-OFL.txt) |
+| OpenCE (after Newtown) | the menus' titles | SIL Open Font License 1.1 | [port/assets/fonts/OpenCE-OFL.txt](port/assets/fonts/OpenCE-OFL.txt) |
+| Newtown (Roger White) | OpenCE's source | public domain | [port/assets/fonts/Newtown-LICENSE.txt](port/assets/fonts/Newtown-LICENSE.txt) |
+
+See [port/assets/fonts/README.md](port/assets/fonts/README.md) for where
+each font is used.
+
+## Not included
+
+No file of Halo: Combat Evolved (maps, sounds, art, music, fonts or
+executables) is part of this repository or its releases. The game reads
+them from the player's own disc image.
@@ -12,7 +12,7 @@ from types import SimpleNamespace

 from tools import ninja_syntax
 from tools.android_build import android_configure_inputs, generate_android_build
-from tools.linux_build import generate_linux_build, linux_configure_inputs
+from tools.linux_build import check_profile_options, generate_linux_build, linux_configure_inputs
 from tools.windows_build import generate_windows_build, windows_configure_inputs

 # arguments
@@ -33,6 +33,12 @@ parser.add_argument(
    action="store_true",
    help="release builds (Linux, Windows, Android): assertions are not checked",
 )
+parser.add_argument(
+    "--profile",
+    action="store_true",
+    help="profiling builds (Linux, Windows, Android): CPU scopes recorded on a "
+    "console command or launch setting (README, \"Profiling builds\"); not with --pgo=train",
+)
 parser.add_argument(
    "--lto",
    choices=["full", "thin", "off"],
@@ -44,7 +50,11 @@ parser.add_argument(
    "--portable",
    action="store_true",
    help="x86 builds (Linux, Windows): code for any x86-64 processor (SSE2) rather than for this "
-    "machine's (-march=native, the default); use it for builds that run on other computers",
+    "machine's (-march=native, the default); use it for builds that run on other computers. On Linux it also "
+    "builds against Debian 11's glibc 2.31 rather than this machine's, and brings its own SDL 3 (libSDL3.so.0, "
+    "beside the executable), so that it starts on SteamOS and older distributions: the first build downloads "
+    "the Debian packages and SDL's source (build/linux/third_party, tools/linux_sysroot.py), and needs CMake, "
+    "pkgconf and wayland-scanner, not the 32-bit SDL 3",
 )
 parser.add_argument(
    "--pgo",
@@ -74,6 +84,10 @@ parser.add_argument(
    help="clang with the arm64_32 target for the Android guest (default: clang)",
 )
 args = parser.parse_args()
+try:
+    check_profile_options(args.profile, args.pgo)
+except ValueError as error:
+    parser.error(str(error))

 # the settings the builds read
 sln = SimpleNamespace(
@@ -81,6 +95,7 @@ sln = SimpleNamespace(
    linux_cc=args.linux_cc,
    compiler_launcher=args.compiler_launcher,
    port_release=args.release,
+    port_profile=args.profile,
    port_lto=args.lto,
    port_portable=args.portable,
    port_pgo=args.pgo,
@@ -0,0 +1,183 @@
+> This is the README of [OpenCE](https://github.com/OpenCommunityEdition/OpenCE),
+> the port Ringfall: Mjolnir VR is built on, kept for its build and
+> development notes. Its download links are OpenCE's. For the VR mod, see
+> the [main README](../README.md).
+
+# Halo: Combat Evolved for Linux, Windows and Android
+
+[![Join our Discord](https://invidget.switchblade.xyz/9gqcHyr5km)](https://discord.gg/9gqcHyr5km)
+
+This project is a port of the Halo: Combat Evolved decompilation to Linux,
+Windows and Android. The decompilation is of the Xbox build 2342
+(`cachebeta.exe`, SHA-256
+`4cc87b45f721270392a96f1674ed2b5cd4a7bb4355faeab4531d1cf1884d9520`).
+
+<img width="1289" height="995" alt="The game on Linux" src="https://github.com/user-attachments/assets/0d3ad50f-f8b8-46cf-aef8-e3661da2a7d7" />
+
+The port starts from the decompilation of [bnunu/halo-1](https://github.com/bnunu/halo-1).
+That project is a fork of [punpckhdq/halo](https://github.com/punpckhdq/halo).
+
+## Download
+
+GitHub Actions builds the game for each commit. These links download the
+builds of the latest release:
+
+| Platform | Release | Debug |
+| --- | --- | --- |
+| 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
+problems.
+
+The game updates itself. At start-up it looks for a newer release, and asks
+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/OpenCommunityEdition/OpenCE/releases)
+page keeps the last five releases. If the latest build has a problem, get
+an older build from that page.
+
+## Game data
+
+The port does not include the game data. It needs an Xbox disc image
+(`.xiso` or `.iso`) made from your own copy of Halo: Combat Evolved. All versions of the game
+operate. The maps of the European (PAL) version were made for a slower
+console. The port changes them to play as the North American (NTSC) maps do,
+so players of the two versions can play together.
+
+1. Start the game.
+2. At the first start, the game asks for the disc image. Select it.
+3. The game extracts the `maps/` folder. Then the game starts.
+
+On Linux and Windows, the game puts `maps/` next to the executable. On
+Android, copy the disc image to the phone first. The app puts `maps/` in its
+data folder. Refer to [port/android/README.md](../port/android/README.md).
+
+## Platforms
+
+Each platform has its own instructions:
+
+| Platform | Instructions |
+| --- | --- |
+| Linux (32-bit x86 executable, OpenGL 4.5, SDL3) | [port/linux/README.md](../port/linux/README.md) |
+| Windows (32-bit x86 executable, OpenGL 4.5, SDL3) | [port/windows/README.md](../port/windows/README.md) |
+| Android (arm64 app, OpenGL ES 3, SDL3) | [port/android/README.md](../port/android/README.md) |
+
+The Linux README also gives the controls, the settings and the multiplayer
+functions. These are almost the same on all platforms.
+
+## Multiplayer
+
+The game can play system link games on a local network and on the internet:
+
+- A system link game can have up to 128 players on up to 128 machines.
+- Linux, Windows and Android machines can play in the same game.
+- An invite link lets a machine join a game on the internet. No server of
+  this project is necessary.
+- The netcode is new. Each machine moves its own player at once,
+  and the host makes the decisions for the game. Refer to
+  [port/linux/NETCODE.md](../port/linux/NETCODE.md).
+
+## Build the game
+
+You do not need the Xbox SDK. The port supplies the SDK declarations that
+the game uses. Refer to [port/include/xdk](../port/include/xdk/README.md).
+
+To build the game:
+
+1. Install Python and [ninja](https://ninja-build.org/).
+2. Install the tools for your platform. Refer to the README for the
+   platform.
+3. In the root folder of the repository, enter `python configure.py`.
+4. Enter `ninja` with the target for the platform:
+
+| Target | Result |
+| --- | --- |
+| `ninja linux` | `build/linux/halo` |
+| `ninja windows` (on Windows) | `build/windows/halo.exe` and `SDL3.dll` |
+| `ninja android_apk` | `port/android/app/build/outputs/apk/debug/app-debug.apk` |
+
+If you enter `ninja` without a target, ninja builds the game for the
+computer that you use.
+
+`tools/ci_build.py` makes the same builds as GitHub Actions. For example,
+enter `python tools/ci_build.py linux release`.
+
+### Build options
+
+Give these options to `configure.py`:
+
+| Option | Result |
+| --- | --- |
+| (none) | A debug build. A failed assertion stops the game. |
+| `--release` | A release build. The game does not examine assertions, as in the retail game. |
+| `--portable` | The Linux and Windows builds operate on all x86-64 processors. The Linux build also operates on older distributions and on SteamOS: refer to "Portable build" in [port/linux/README.md](../port/linux/README.md#portable-build). Use this option for builds that you give to other persons. |
+| `--lto=thin`, `--lto=off` | Less link-time optimization. The link is faster. |
+| `--pgo=off` | No profile-guided optimization. |
+| `--pgo=train` | Records a new optimization profile. Refer to "Optimization profiles". |
+| `--profile` | A profiling build. It records CPU times. Refer to "Profiling builds". |
+
+Without `--portable`, the Linux and Windows builds use all the instructions
+of the processor that builds them (`-march=native`). Such a build does not
+always start on a different computer.
+
+### Optimization profiles
+
+The builds use profiles of the game to optimize the code:
+
+- `pgo/halo_linux.profdata` for Linux and Android.
+- `pgo/halo_windows.profdata` for Windows.
+
+The profiles need clang 22 or later. With an older clang, the builds do not
+use the profiles.
+
+To record a new profile:
+
+1. Delete the profile.
+2. Enter `python configure.py --pgo=train`.
+3. Enter `ninja linux` or `ninja windows`.
+
+The build then plays the main menu and the first minute of each campaign
+level. This procedure continues for approximately 15 minutes. The game
+data must be in `assets/`.
+
+### Profiling builds
+
+A profiling build records where the game spends its time.
+
+1. Enter `python configure.py --profile`, then build as usual.
+2. Start a recording. Enter `profile_record` in the console (or the telnet
+   console), or set `debug.profile_record = true` in `config.toml`. To
+   record each game of a session, also set
+   `debug.profile_record_when = "game"`.
+3. Stop the recording. Enter `profile_stop`, load another map, or quit.
+
+The game writes numbered `.part<n>.json` files under `profiles/` in its data root
+and logs their paths. Parts are retained after the recording stops. Logs go to
+standard error; a Windows release build without standard error writes them to
+`halo.log` next to `halo.exe`.
+
+`tools/net_report.py` is a helper for developers. Enter
+`python tools/net_report.py <recording.part1.json>` to read a recording
+as tables. The command also writes `<recording>.summary.txt`, a short text
+file.
+
+| Command | Result |
+| --- | --- |
+| `profile_record [seconds]` | Starts a recording. With a number of seconds, the recording stops after that time. |
+| `profile_stop` | Stops the recording. |
+
+`debug.profile_memory` sets the memory of a recording in MB (default 256,
+from 4 to 1024). A recording has no length limit:
+the game writes a part each time the memory is full. Refer to "Settings" in
+[port/linux/README.md](../port/linux/README.md).
+
+On Android, the files are in `/sdcard/Android/data/com.halo.decomp/files/profiles/`.
+Enter `adb pull` to copy the recording parts to a computer.
+
+A profiling build plays with normal builds. It does not use
+`--pgo=train`.
@@ -0,0 +1,625 @@
+# Halo Custom Edition maps
+
+The native builds (Linux, Windows, Android) load and run Halo Custom Edition
+caches (`.map`, cache version 609), with the Custom Edition resource maps
+`bitmaps.map`, `sounds.map` and `loc.map`. A cache that needs OpenSauce
+(its OpenSauce header asks for memory upgrades, mod data files or the like)
+is refused, and `.yelo` files are never looked for; a `.map` that only
+carries OpenSauce's header and its `project_yellow` tags (SPV3's
+backwards-compatible releases) is run as stock Custom Edition runs it,
+neither read. The loader and the conversions come from DamnationCE
+(xshxdex98/DamnationCE), whose documentation this file grew from; in this
+build a Custom Edition map's tags are also checked by the tag validator, as
+the Xbox maps' are, before anything reads them
+(`port/linux/game/tag_validate.c`, [Checks](#checks)).
+
+## Running a map
+
+Custom Edition maps run when the `game.custom_edition` setting is on, as it
+is by default (`custom_edition = true` under `[game]` in `config.toml`, or
+`HALO_CUSTOM_EDITION`). Put the maps and Custom Edition's `bitmaps.map`,
+`sounds.map` and `loc.map` in the data root's `custom_maps` folder, beside
+its `maps` folder, which holds the game's own maps only; or set
+`paths.custom_edition` to a Halo Custom Edition install, whose `maps` folder
+(the Xbox drive `h:\`) is looked in after `custom_maps`.
+
+A Custom Edition map's level name is `custom_maps\<name>`
+(`custom_edition_cache.h`, `CUSTOM_EDITION_LEVEL_NAME_PREFIX`), which none
+of the game's own levels has: only such a name is loaded from the Custom
+Edition folders, and never from `maps`. So a map named as one of the game's
+own levels (CMT's `a30.map`, Custom Edition's `bloodgulch.map`) is played as
+itself, apart from the level of its name, in the menus, the loader and
+network games, and is never taken for one of the campaign's levels (saved
+games, progress, the next level). The game engine keeps 63 characters of a
+level name, so a map whose file name is longer than 51 is not listed.
+
+### In the menus
+
+The map lists (New Game's, and the Map screen of Create Game's INTERNET and
+LAN and of split screen) have four kinds in their first row's chooser:
+SINGLEPLAYER (the campaign's levels), MULTIPLAYER (the Xbox's maps), and
+CUSTOM SINGLEPLAYER and CUSTOM MULTIPLAYER, the Custom Edition maps of the
+custom maps folders by the scenario type their files give (solo or
+multiplayer). A map is played as its kind says
+(`port/linux/game/menu_functions.c`):
+
+- **New Game**: a CUSTOM SINGLEPLAYER map is played as the campaign's
+  levels are, at the difficulty chosen next (alone, or with split screen
+  co-op's two players); a CUSTOM MULTIPLAYER map is walked around alone, as
+  MULTIPLAYER's are.
+- **The Map screen**: a CUSTOM SINGLEPLAYER map lists the difficulties and
+  is hosted as a network co-op game (Server Setup, then the lobby), as the
+  campaign's levels are; a CUSTOM MULTIPLAYER map goes on to the gametypes,
+  as MULTIPLAYER's do. Split screen hosts only the multiplayer kinds.
+
+The Xbox menus' multiplayer level list offers the Custom Edition multiplayer
+maps after the thirteen Xbox levels. The pregame lobby shows a Custom
+Edition map by its name and picture, multiplayer or campaign, and the game
+lists by its name (`port/linux/game/custom_edition_maps.c`). The folders are
+looked in once, and again each time a map list opens, which then shows maps
+added since. A map is listed under its file's name, `the_bay_of_pigs.map` as
+"The Bay Of Pigs". Two optional files beside the map give it what the Xbox
+levels have:
+
+- `<name>.bmp`, its picture: an uncompressed 24-bit or 32-bit Windows
+  bitmap, up to 8192 pixels a side; the middle of it is shown with the
+  shape of the level pictures, 140 by 114 (`port/linux/game/bmp_files.c`,
+  which reads it as untrusted input).
+- `<name>.txt`, its description: plain text, its lines shown as written.
+  Without one, the map is described as "Halo Custom Edition map".
+
+A machine joining a network game on a map it has not (a Custom Edition map
+not in its `custom_maps`, or one of the game's own not in `maps`) leaves it
+with an error that names the map and the folder to copy it into, rather
+than the damaged disc error precaching a missing map gives
+(`cache_files_map_present`, called as the host's settings arrive): also when
+the map cannot run there (Custom Edition maps turned off, the file not a
+Custom Edition cache, or `bitmaps.map`, `sounds.map` and `loc.map` missing),
+when its copy of a Custom Edition map is another version than the host's
+(the host sends its file's header checksum as the game record's map
+version, which the Xbox left 0: `cache_files_map_version`; a host that sends
+0 is not checked), and when the host names a Custom Edition map as other
+versions of this port do (`levels\test\<name>\<name>`) and the file is in
+`custom_maps`. The
+error's text is wrapped to its dialog, in the menus' smaller font when it
+would not fit; `debug.txt` has the details.
+
+A Custom Edition campaign map has no next level: winning it ends the game
+as the campaign's last level does (alone) or plays it again (network
+co-op), and it is not the campaign's saved game.
+
+### From the console
+
+`map_name` takes the level name: `custom_maps\<name>` for a Custom Edition
+map (`custom_maps\hugeass` plays `custom_maps\hugeass.map`). A multiplayer
+scenario needs a game variant, or no starting location qualifies and no
+player spawns:
+
+```
+game_variant slayer
+map_name custom_maps\hugeass
+```
+
+## What the native builds do
+
+- **With `game.custom_edition` on**, the platform reserves the address
+  window Custom Edition tag data is linked to, `0x40440000`-`0x41B40000`
+  (`port/linux/src/xbox_memory.c`, at start-up; 23 MB of address space,
+  backed as it is touched), and a Custom Edition map is loaded into it,
+  converted as below, checked, and run. It is read in place, never copied
+  to the cache partition: every read the game makes of it (structure BSPs,
+  bitmap pixels, sound samples) is served from the map, `bitmaps.map`,
+  `sounds.map` or the sounds decoded at load, according to where its offset
+  falls in their combined offset space (`custom_edition_cache_read`). A map
+  that fails any check is logged in `debug.txt` and not loaded: the game
+  goes back to its menus.
+- **With it off**, a Custom Edition cache is named and refused, instead of
+  being rejected as "an old version" of this build's caches; so is one put
+  in `maps`, which is told to go in `custom_maps`.
+- **Xbox caches** take the path they took before.
+
+The desktop builds' Xbox memory window is 512 MB (Android's 128 MB), in
+which the texture cache is 256 MB: Custom Edition maps draw more texture
+than the Xbox's 22 MB cache holds, and their geometry is made into
+Direct3D buffers in the same memory (`port/linux/include/halo_port_capacity.h`).
+
+## Loading and conversion
+
+### The loader (`cache_file_formats.c`)
+
+`port/linux/game/cache_file_formats.c` (`cache_file_formats.h`) holds the
+format code: standalone C with fixed-width types and no game dependencies,
+compiled into the native builds (as every `port/linux/game` unit is) and
+into the report tool. Map files are untrusted input: every field is read
+little-endian from a bounds-checked buffer, never through a structure laid
+over the file, and every offset, count and size is checked before use, with
+overflow-safe arithmetic. `port/tools/cache_file_report.c` reports what can
+be done with each file:
+
+```sh
+clang --target=i686-pc-windows-msvc -fuse-ld=lld -Iport/linux/game \
+    port/linux/game/cache_file_formats.c port/tools/cache_file_report.c -o cache_file_report.exe
+cache_file_report [--maps DIRECTORY] [--dump-tags FILE] FILE...
+```
+
+Resource maps are looked for next to the cache (or in `--maps`):
+`bitmaps.map`, `sounds.map` and `loc.map`. `--dump-tags` writes the converted
+tags to a file, as they would sit at `0x40440000`.
+
+Loading, step by step (`custom_edition_cache_load`):
+
+1. The header: signatures, version 609, terminated strings, file length (0,
+   as Invader leaves it, for the whole file) within the file and the size
+   limit (`0x30000000`: Halo PC's was `0x18000000`, and Invader builds
+   larger maps, which Chimera runs), no compression, tag data within the
+   file and the tag cache (23 MB). A cache with OpenSauce's header (its
+   `yelo` signature at offset `0x70`, which Custom Edition leaves as
+   padding) that sets any of its flags (memory upgrades, mod data files and
+   the rest) is refused; one that sets none is a Custom Edition cache.
+2. The tag data is read to the start of the tag cache, which stands for
+   `0x40440000`.
+3. The tag index (`tags` signature), every tag instance (its handle must
+   match its position, its name must lie in the tag data and be terminated,
+   its address must lie in the tag data; only structure BSPs may have none;
+   only bitmaps, sounds, fonts, unicode string lists and HUD message text may
+   be held by resource maps; OpenSauce's `project_yellow` and
+   `project_yellow_globals`, which nothing reads, are left as they are), the
+   model data range, and the scenario tag.
+4. Every structure BSP: its tag, its range in the file, its place in the tag
+   cache (above the tag data, within the tag cache), its header (`sbsp`
+   signature, no Xbox vertex buffers, its structure pointer inside it), and
+   its lightmaps and their materials: every block within the BSP and aligned,
+   every material's uncompressed environment vertices (56 bytes) and
+   lightmap vertices (20 bytes) within the BSP and of the size their counts
+   give, lightmap vertices exactly when the lightmap has a bitmap, and every
+   normal, binormal, tangent and incident radiosity within ±1.005 (the game's
+   vertex compressor asserts on anything further out).
+5. The header checksum is computed as OpenSauce computes it, before anything
+   changes the tag data; a mismatch is reported, not refused.
+6. The tags held by resource maps are read into the tag cache after the tag
+   data, below the lowest structure BSP, and their pointers relocated. A
+   sound's header in the map lacks its sample rate, encoding, compression
+   and longest permutation length; they are taken from the header's copy in
+   `sounds.map` ([Evidence](#observed-not-stated-by-the-sources-established-on-the-sample-maps)).
+7. Every bitmap, sound, font, unicode string list, HUD message text, model
+   (`mod2`) and transparent chicago shader (`schi`, `scex`) is walked through
+   its blocks: every block and data pointer must lie within the loaded tags,
+   every bitmap's pixels and sound's samples within their file, and every
+   model part's strip and vertices within the model data, of the kinds Custom
+   Edition writes (a precompiled strip, uncompressed 68-byte vertices), with
+   at most 65535 vertices and at most 22 local nodes.
+
+Then `custom_edition_cache_convert` changes what only needs its bytes
+changed:
+
+- **Shader types.** Custom Edition inserted *transparent chicago extended*
+  as shader type 7, so its water, glass, meter and plasma shaders are types
+  8 to 11 where this build has 7 to 10 (and would draw a Custom Edition glass
+  shader as meter, and so on, unnoticed). Every shader gets this build's
+  number for its group; a type field saying otherwise (as map protection
+  leaves them) is counted and given the group's.
+- **Transparent chicago extended shaders** (`scex`) become transparent
+  chicago shaders (`schi`): the two layouts agree up to the maps, of which
+  `scex` has two sets, for four and for two texture stages; the four-stage
+  maps are kept (this build draws four stages), or the two-stage ones when
+  there are no others, and the extra flags move to where `schi` has them.
+- **Bitmaps and sound permutations** get the state of ones not yet drawn or
+  played, and name their own tags: `bitmaps.map` and `sounds.map` hold the
+  tag handles of whatever map they were built with.
+- **Sounds this build cannot decode** (Custom Edition's Ogg Vorbis) are made
+  unplayable, by emptying their pitch ranges, which the game skips.
+- **Animation overlays naming animations that do not exist** are made to
+  name none, which the game skips. Maps built with the editing kit can have
+  them; Custom Edition reads past the graph's animations there, and this
+  build's debug builds stop on it.
+- **HUD elements drawn from double-resolution bitmaps.** Halo PC added a
+  third scaling flag to HUD placements, *use high resolution scale*
+  (OpenSauce `hud_definitions.hpp`), and draws a flagged element at half the
+  size of its bitmap. Custom Edition's HUD bitmaps are made for that: in
+  `bloodgulch.map` every flagged element draws a bitmap exactly twice the
+  size of the one its Xbox counterpart draws (256×64 for 128×32, 512×512 for
+  256×256), with the same scale, and every unflagged one a bitmap of the same
+  size ([Evidence](#observed-not-stated-by-the-sources-established-on-the-sample-maps)).
+  This build ignores the flag, so it drew them twice too large; the
+  placements of the unit, weapon and grenade HUD interfaces and the HUD
+  globals' messages that have it get half their scale, and lose the flag (32
+  in `bloodgulch.map`). Halo PC reads the flag only on statics, meters and
+  numbers (Chimera's `hud_bitmap_scale.cpp`): crosshair and overlay items
+  keep their scale. A number's scale is not its
+  digits', so a flagged number keeps the flag and `hud_draw_numbers` draws
+  its digits at half their size, spaced as the digits tag says. A bitmap may ask the
+  same of every element that draws it, with Halo PC's bitmap flags *half hud
+  scale* and *force hud use highres scale* (Invader's `bitmap.json`): an
+  element drawing such a bitmap (a static or meter, its bitmap after its
+  placement; a crosshair's or overlay's items, their crosshair's or
+  overlay's) gets half its scale too. None of the 18 Custom Edition maps on
+  hand, nor `bitmaps.map`, sets either.
+- **Maps made around Halo PC's own behaviour.** Chimera fixes Halo PC to draw
+  as the Xbox does, and keeps a list of the maps made around Halo PC's way
+  instead, by map name (in lower case) and tag data checksum, with the
+  behaviours each relies on (`map_hacks_config.json`, by SnowyMouse; here
+  `port/linux/game/custom_edition_behaviours.inc`, generated from it). This
+  build draws as the Xbox does, so for a listed map it follows these where it
+  can, and logs each: HUD multitexture overlays' blend functions in Halo PC's
+  order (`gearbox_multitexture_blend_modes`: Halo PC picks its shader by the
+  Xbox's value from shaders in alphabetical order), overlays not drawn
+  (`block_multitexture_overlays`), the HUD digits' metrics halved and every
+  number's digits drawn at half size (`hud_number_scale`), bitmaps' HUD scale
+  flags cleared (`disable_bitmap_hud_scale_flags`), and model shaders'
+  detail after reflection flag flipped (`invert_detail_after_reflection`).
+  Not yet: Halo PC's fixed-function meters (`gearbox_meters`), its
+  transparent chicago multiply, bump attenuation and environment shader
+  types, the old widescreen HUD and embedded Lua.
+- **The score hint.** String 100 of `ui\multiplayer_game_text` is Halo PC's
+  `Hold "%s" for score`, which Halo PC fills in with its score key; this
+  build copies it as it is (`game_engine.c`, the press-back-for-score
+  message), so `"%s"` becomes `BACK`, the button this build reads for the
+  score, in the same four characters.
+
+### In the game (`custom_edition_cache.c`, `custom_edition_geometry.c`, `custom_edition_bitmaps.c`)
+
+- **Models.** Every `mod2` part is given this build's part layout (the first
+  0x68 bytes of the 0x84-byte Custom Edition part are the same fields; the
+  parts are repacked in place), its vertices are compressed from the map's
+  model data by the game's own `rasterizer_geometry_compress_vertices`, its
+  node indices made the model's when its model's parts have local nodes, and
+  its strip copied unchanged; the game's own `rasterizer_vertex_buffer_new`
+  and `rasterizer_triangle_buffer_new` make its buffers, and the tags become
+  `mode` tags. Before any of that, every index a part holds is checked
+  against what it names (shaders, nodes, parts, vertices). This build's
+  renderer skins at most 43 nodes at once, so a model of more is drawn a
+  part's own nodes at a time: a model of more whose parts have no local
+  nodes is given them, each part the nodes its vertices name, and is refused
+  only when a part's vertices name more than a part holds.
+- **Structure BSPs.** When the game loads a BSP, every material's vertices
+  are compressed the same way (environment and lightmap vertices), and the
+  material gets buffers and the compressed vertices the game reads for
+  visibility, collision and lights (`scenario_structure_bsp_load` in
+  `cache_files.c` calls `custom_edition_structure_bsp_load`).
+- **Bitmaps.** Every bitmap must pass the game's own `bitmap_verify` and be
+  of a kind the texture cache and the swizzling code handle (a format with a
+  hardware texture, a compressed flag that agrees with the format,
+  power-of-two sizes unless linear, square cube maps, all its pixels
+  present). Halo PC draws a 2D bitmap of any size, so an uncompressed one
+  whose sides are not powers of two is made linear as the map loads, and
+  drawn from its first level (birdcage-plus's 3840 by 64 needler plasma).
+  Its pixels are laid out for Halo PC, levels as the tag stores them,
+  unswizzled; as they arrive, the game's own
+  `rasterizer_xbox_bitmap_rebuild_hardware_format` lays them out as an Xbox
+  cache would (swizzled, cube maps face by face, padded).
+- **Chicago extra layers.** January's transparent chicago shader draws its
+  extra layers in a loop that never advances
+  (`rasterizer_xbox_transparent_geometry.c`, marked as a preserved bug). No
+  Xbox map has such layers, so January never hung on it, but Custom
+  Edition's editing kit can make them: the native builds advance the loop.
+- **Channel orders.** Halo PC keeps two kinds of texture in other channels
+  than this build reads them from (`enum custom_edition_channel_order`,
+  [Evidence](#observed-not-stated-by-the-sources-established-on-the-sample-maps)):
+  a model shader's *multipurpose map*, whose auxiliary (detail) mask,
+  self-illumination, specular and color change masks Halo PC keeps in red,
+  green, blue and alpha, where this build's model shaders read specular from
+  red, self-illumination from green, color change from blue and the
+  auxiliary mask from alpha; and a *HUD meter*, whose shape Halo PC keeps in
+  color and fill order in alpha, where this build's meter shader
+  (`rasterizer_xbox_dynavobgeom.c`) compares the color with the meter's value
+  and discards what has no alpha. Reordering the pixels would mean
+  decompressing them, which the texture cache has no room for, so the game
+  finds the bitmaps drawn as multipurpose maps (by model shaders) and as
+  meters (by unit and weapon HUD interfaces) when the map loads, and tells
+  the renderer where each bitmap's pixels arrive and in which order their
+  channels are; the renderer samples them with each channel taken from where
+  Halo PC keeps it (`port/linux/src/xbox_textures.c`, a texture swizzle,
+  which leaves them compressed). A bitmap also drawn another way (a
+  multipurpose map that is also a base map, say) keeps its channels, since
+  the renderer has one order for each texture, and is logged: 3 in
+  `bloodgulch.map`, all multipurpose maps.
+- **Reads.** The renderer write-protects the memory it has made textures of
+  and learns of changes from the faults writes take; the kernel fails a read
+  into such memory instead. Every read of the map is therefore made into a
+  64 KB staging buffer and copied, as the platform's file layer does.
+- **Texture memory.** A frame of `Elite_Alpha_Siege.map` draws more than the
+  22 MB of textures the Xbox texture cache holds, and textures that did not
+  fit were drawn as the default one. The desktop builds' texture cache is
+  256 MB, in a 512 MB memory window (`halo_port_capacity.h`), for every map;
+  Android's is the Xbox's.
+- **Scripts.** A compiled script names each function it calls, and each
+  engine global it uses, by its index in the engine's tables, and Halo PC's
+  tables have entries this build's do not, in among the ones both have: from
+  some point on, an index names another entry here
+  ([Evidence](#observed-not-stated-by-the-sources-established-on-the-sample-maps)).
+  `hugeass.map`'s day and night script would call `playback` instead of
+  `switch_bsp`. A compiled script also keeps every name, in its string data,
+  so every call and every engine global is found again by name with the
+  game's own `hs_find_function_by_name` and `hs_find_global_by_name`
+  (`custom_edition_scripts.c`); one this build does not have does nothing
+  and is logged by name (Limits, below). The value types are numbered
+  alike in both builds.
+- **Multiplayer vehicle placement.** This build places a multiplayer game's
+  vehicles by type: only the first three of the globals' multiplayer
+  vehicles are created, and of those the ones the variant's vehicle set
+  names (`game_engine_remap_vehicle`; the built-in variants name the first).
+  Custom Edition maps are made for retail Halo's rules: a vehicle placement's
+  multiplayer spawn flags name the game types it is placed in by default,
+  and a script may create any vehicle. `hugeass.map` depends on that (above).
+  For a Custom Edition map in slayer, capture the flag, king of the hill or
+  oddball, the native builds place the vehicles whose spawn flags name the
+  game type by default and let any vehicle be created
+  (`custom_edition_objects.c`, called from `object_types_place_all` and
+  `game_engine_remap_vehicle`); a variant without
+  vehicles still has none, and race, which has no spawn flag, keeps this
+  build's rule.
+- **Multiplayer vehicles.** `game_engine_predict_resources` takes the three
+  multiplayer vehicles Xbox globals always have; a Custom Edition map's
+  globals can list fewer, and oddball stopped on such a map. With fewer than
+  three, the native builds predict none (`game_engine.c`).
+
+## Checks
+
+The loader (`cache_file_formats.c`) checks the container: the header, the
+tag index, every structure BSP, every resource-held tag and its relocated
+pointers, every bitmap pixel and sound sample range, every model part's
+geometry in the model data. Then, once the loader and the conversion of
+bytes have made the tags this build's layout, the tag validator checks
+every tag as it checks an Xbox map's (`tag_validate_custom_edition_tags`,
+called by `custom_edition_cache_tags_load`): every block and data within
+the loaded tags and overlapping no other's, counts cut to the game's
+capacities, indices, enums and tag references corrected, runtime values
+reset, then the graph checks (collision BSPs, node trees, scripts' syntax).
+A map whose pointers cannot be trusted is refused; what can be corrected is,
+and logged. What differs from an Xbox map:
+
+- the tag header has no vertex or index buffers, and the tag cache is the
+  Custom Edition one (23 MB);
+- bitmap pixels and sound samples are in several files: their offsets must
+  lie in the map, the sounds decoded at load, `bitmaps.map` or `sounds.map`;
+- models are gbxmodels (`mod2`), whose parts keep their geometry in the
+  map's model data and a table of local nodes, which are checked against
+  the model's (`tag_schema_custom_edition_groups`, in `tag_schema_models.c`);
+  the game takes them as models;
+- a structure BSP's material vertices are uncompressed, and are checked
+  against its uncompressed vertex data.
+
+Only after the validator has passed the tags are the scripts given this
+build's function and global indices, the bitmaps checked for the texture
+cache, and the models and each structure BSP (checked as it loads, as an
+Xbox map's) given compressed vertices and buffers. The script function
+allowlist (`hs.c`) applies to Custom Edition maps as to every map.
+
+`build/linux/map_validate` runs the loader, the conversion of bytes and the
+validator on maps outside the game, with the resource maps beside each map
+or in `--maps`; `--fuzz` changes words of a map's file at random.
+
+## Tested
+
+### Automated tests
+
+- `python -m pytest tools/test_cache_file_formats.py` (130 tests; needs
+  clang): synthetic Custom Edition caches and resource maps, caches that
+  need OpenSauce refused and those that only carry its data loaded, every
+  check of the loader and the conversion, and seeded random corruptions,
+  through `port/tools/cache_file_report.c`. With `HALO_CUSTOM_EDITION_MAPS`
+  naming a folder of maps, four more check real maps: against DamnationCE's
+  recorded results (which are of its copies of the stock maps), and that any
+  `.yelo` map among them is either refused or a Custom Edition cache.
+- `python -m pytest tools/test_bmp_files.py` (41 tests): the map pictures'
+  reader.
+- `tools/test_linux_port.py`: with `HALO_CUSTOM_EDITION_MAPS` (or the
+  gitignored `assets/custom_edition`), every map is loaded and checked and
+  none refused, and three are fuzzed (100 runs each); the retail Xbox maps
+  still need no correction.
+
+### Maps
+
+Two folders were checked with `map_validate`: the 20 stock Custom Edition
+maps (the halopc-restored r220 copies) and 19 community maps (`area53`,
+`bigass`, `deltaruins`, `Elite_Alpha_Siege`, `extinction`, `Fission_Point`,
+`Floodgulch5.1`, `hugeass`, `immure`, `tactics`, `the_bay_of_pigs`,
+`the_rise_of_asis`, `WW_battlefield` and copies of stock levels). None is
+refused. The stock maps need one correction each, a character of
+`loc.map`'s gamespy font 5 pixels narrower than nothing; the community maps
+some more, their own data's mistakes (an enum past its values, a region
+index past its block, a particle state of a sequence with no sprites).
+Fuzzing, 200 runs of each of those 39 maps (7,800 runs): no crash, no hang,
+and every map let through clean when checked again.
+
+Run in the game (Linux release build, 40 to 50 seconds each, slayer):
+`hugeass`, `bigass`, `extinction`, `deltaruins`, `Elite_Alpha_Siege`,
+`the_rise_of_asis`, `area53`, `tactics`, `Floodgulch5.1`, `immure`,
+`WW_battlefield`, `the_bay_of_pigs` and `Fission_Point` load, are checked,
+converted and played to the end of the run without a crash; `hugeass`'s
+hangar, HUD and first-person weapon were seen drawn.
+
+Two campaign maps were checked with `map_validate`: CMT's `a30.map` (2006,
+"Halo"; 13 corrections) and CMT SPV3's backwards-compatible `a50.map` (2012,
+The Truth and Reconciliation, with OpenSauce's header setting no flags and
+its two `project_yellow` tags; 43 corrections); `a30` was also run. From the
+menus (on a virtual display): New Game's CUSTOM SINGLEPLAYER `a30` played as
+a campaign level at the difficulty chosen; the Map screen's (LAN) listed its
+difficulties, set up co-op in Server Setup and showed it in the lobby as
+co-op. With `debug.network_test`, two machines on loopback played
+`custom_maps\a30` as network co-op and `custom_maps\hugeass` as slayer; a
+joining machine without the map, without the resource maps, or with a maps
+folder missing the host's Xbox map was shown each error and left the game.
+
+### Not tested
+
+- **Playing**: nobody played the maps through.
+- **Android** builds, and was not run.
+
+## Evidence
+
+### Sources
+
+- **OpenSauce** (GPL-3.0, Kornner Studios): the `OpenSauce-master.zip`
+  archive of the upstream repository (SHA-256
+  `f1097c9cf5975a208506c78c3af47d6b893f998a9f47dddf89c9bbcc1f4b7c73`; newest
+  entry dated 2016-01-15; `yelo_version.hpp` names OpenSauce 4.0.0).
+- **Reclaimer** (GPL-3.0, Gravemind2401): the `Reclaimer-master.zip` archive
+  (SHA-256 `72fd5270abbdf662ff07a54e9cce80a6158e479c51ecfdcd979f7f9fbd6c2d03`;
+  newest entry dated 2026-09-20).
+- **The Xbox maps of retail build 01.10.12.2276** (`bloodgulch.map`,
+  decompressed): not the 01.01.14.2342 build this repository reconstructs,
+  but their model parts have its 0x68-byte layout and their shader types its
+  numbering, which makes them a check on what the conversion produces.
+
+OpenSauce and Reclaimer are GPL-3.0 and this repository is CC0: no code from
+either was copied. They were read as documentation of the file formats, and
+every layout used was then checked against the sample maps.
+
+### Documented facts (source, checked against the sample maps)
+
+| Fact | Source |
+| --- | --- |
+| Cache header layout, version 609, `head`/`foot` signatures | OpenSauce `blamlib/Halo1/cache/cache_files_structures.hpp` (`s_cache_header`) |
+| Tag index (0x28 bytes, instances at 0x28, model data as file offsets) and tag instance (0x20 bytes, resource-map flag at 0x18) | same file (`s_cache_tag_header`, `s_cache_tag_instance`) |
+| OpenSauce's header at 0x70 begins with the `yelo` signature, where Custom Edition's header has padding, and has its flags (memory upgrades, mod data files, protected, game state upgrades, compression parameters) at 0x76 | OpenSauce `YeloLib/Halo1/cache/cache_files_structures_yelo.hpp` (`s_cache_header_yelo`) |
+| Tag cache at `0x40440000`, 23 MB; file size limits | OpenSauce `cache_constants.hpp`, `saved_game_constants.hpp` |
+| Resource map header and entries | OpenSauce `data_file_structures.hpp` |
+| Groups held by resource maps: bitmaps, sounds, fonts, unicode string lists, HUD message text | OpenSauce `blamlib/Halo1/cache/cache_files.cpp` (`cache_file_data_load`) |
+| Structure BSP reference (0x20), header (0x18), structure, lightmap and material layouts | OpenSauce `scenario_definitions.hpp`, `structure_bsp_definitions.hpp`; this build's `structure_bsp_definitions.h` agrees |
+| Bitmap, sequence, sprite, bitmap data layouts; pixels in `bitmaps.map` flag | OpenSauce `bitmaps/bitmap_group.hpp` |
+| Sound definition, pitch range, permutation layouts; samples-in-`sounds.map` flag | OpenSauce `sound/sound_definitions.hpp` |
+| Gbxmodel layout: the part (0x84 bytes) is this build's 0x68-byte part followed by a local node count and a 22-entry node table | OpenSauce `models/model_definitions.hpp` (`gbxmodel_geometry_part`) |
+| Where a part's strip and vertices lie in the model data (triangle count, strip offset, vertex count and offset in the buffer fields; 68-byte vertices) | Reclaimer `Blam/Halo1/GbxmodelTag.cs` (`ReadPCMeshes`) |
+| Shader types: *transparent chicago extended* inserted at 7, before water, glass, meter and plasma; its two map sets | OpenSauce `shaders/shader_definitions.hpp` |
+| Script syntax nodes: 19001 in the stock engine | OpenSauce `hs_constants.hpp` |
+| HUD message text layout | OpenSauce `interface/hud_messaging_definitions.hpp` |
+| Font (156 bytes) and unicode string list layouts | BlamLib `Blam/Halo1/Tags/Definitions/Misc.cs`, `Resources.cs` |
+| Bitmap tags in `bitmaps.map` by index, pixels by absolute offset | Reclaimer `Blam/Halo1/CacheFile.cs`, `BitmapTag.cs`, `BitmapsAddressTranslator.cs` |
+| The header checksum: CRC-32 of the structure BSPs (packed from 0x800), the model data and the tag data, not inverted | OpenSauce `cache_files_yelo.cpp` (`CalculateChecksumFromMemoryMap`), `memory_interface_base.cpp` (`CRC`); reproduces the stored checksum of 23 of the 24 sample caches |
+
+### Observed (not stated by the sources; established on the sample maps)
+
+| Fact | Evidence |
+| --- | --- |
+| Structure BSPs load at the top of the tag cache (`address + size` = `0x41B40000`) | all 24 caches (those with OpenSauce's memory upgrades at the top of its larger tag cache) |
+| Bitmaps, fonts, unicode string lists and HUD text held by resource maps: the tag's address field is the entry index, the entry's name is the tag's path, the entry is the whole tag with addresses counting from its start | 9,550 bitmaps, 68 fonts, 2,248 string lists, 23 HUD texts across the sample |
+| Sounds held by `sounds.map`: the map keeps the 0xA4-byte header, whose pitch range block has a count and no address; the entry named by the tag path holds the header again, then the pitch ranges and permutations, whose addresses count from the first pitch range | 7,397 sounds, 21,870 sample ranges |
+| The map's copy of a resource-held sound's header has its compression and longest permutation length zero, and its encoding and sample rate zero too; the entry's copy has them as the Xbox has them | in `bloodgulch.map` and `beavercreek_halo3.yelo`, the two copies of all 527 resource-held sounds differ only in those four fields, in pointers, and in the map's own promotion sound reference; for the 315 sounds the Xbox `bloodgulch.map` shares, the entry's sample rate, encoding and the runtime fields after the longest permutation length equal the Xbox's; its compression does except for the 38 that Custom Edition has as Ogg Vorbis, and its longest permutation length for 273 (the others differ by a few milliseconds or more, among them the Ogg Vorbis ones); its pitch ranges' runtime fields all do |
+| Sound permutations and resource-held bitmaps name tags of another map (the one the resource map was built with) | 632 of 676 bitmaps of `bloodgulch.map`; every resource-held permutation differs from the Xbox's own sound handle |
+| Model parts: the strip and vertex data are in the model data, never in the part's blocks; the triangle buffer is a precompiled strip and the vertices uncompressed; the part flag 2 is set on exactly the parts that have a node table | all 24 maps (10,934 parts) |
+| Converting a part's vertices with the game's compressor reproduces the Xbox's | for the 335 parts of the 60 models the Custom Edition and the Xbox `bloodgulch.map` share: identical strips; positions equal to within float rounding; texture coordinates and node weights exactly what the compressor makes of the Custom Edition values (clamped to ±1, as the Xbox also has them: `plant_broadleaf_short` has coordinates up to 3.0 in both); node indices the Custom Edition ones times 3, except that the Xbox writes an unweighted second node as -1 where the compressor writes the node Custom Edition names; normals within 0.002 |
+| Every node index of a vertex names a node of its part's table (in models whose parts have local nodes) or of its model, every table entry a node of the model, and every vector is within ±1.0001 | all 24 maps |
+| Structure BSP materials: environment vertices uncompressed (type 0), with lightmap vertices (as many as the environment ones) exactly in lightmaps that have a bitmap, and no compressed vertices | all 24 maps (the lightmap vertex type field is 0 or 2 regardless) |
+| Custom Edition shader type values are 7 to 11 for `scex`, `swat`, `sgla`, `smet`, `spla`; the Xbox's are 8, 9, 10 for `sgla`, `smet`, `spla` | every shader of the 24 maps, and of the Xbox `bloodgulch.map` |
+| Chicago shaders with extra layers: none in the stock maps or the Xbox `bloodgulch.map`; 2 in `beavercreek_halo3.yelo`, 2 in `celer_exile_odst_v2.yelo`, 4 in `extinctionrevanepic2.map`, 1 in `fy_killzone.yelo` | every `schi` and `scex` of the sample |
+| Compressed color plates are left out of caches: size kept, address 0 | every bitmap in `bitmaps.map` |
+| Font style references in `loc.map` are all `NONE` | all 3 fonts |
+| Sound compression value 3 is Ogg Vorbis, value 1 is Xbox ADPCM | in `sounds.map`, all 106 value-3 permutations start with `OggS`; all 1,365 value-1 permutations are whole 36-byte blocks |
+| `bitmaps.map` bitmaps are not swizzled, and cube maps hold each level's six faces together | all 1,467; 38 of 40 cube maps match that order when checked against their next level (one is uniform, one does not match) |
+| Multipurpose maps: Custom Edition's red, green, blue and alpha hold what the Xbox's alpha, green, red and blue do | the multipurpose maps the Custom Edition and the Xbox `bloodgulch.map` share, decoded and compared channel by channel (the cyborg's, the warthog's, the boulders') |
+| HUD meters: Custom Edition's alpha holds the Xbox's color (the fill order), and its color the Xbox's alpha (the shape) | `hud_ammo_meters`: Custom Edition's 512×512 A8R8G8B8 averaged down to the Xbox's 256×256 A8Y8 differs from the Xbox's luminance by 6.6 on average in alpha and 23 in color, and from its alpha by 12.3 in color and 23.4 in alpha; `hud_unit_meters` has its sprites rearranged, and shows the same swap when viewed. January's meter shader reads the fill order from color and discards texels without alpha |
+| HUD elements flagged *use high resolution scale* draw bitmaps twice the Xbox's size; others the same size | every unit and weapon HUD placement of `bloodgulch.map` whose tag the Xbox map also has (the motion sensor's foreground, unflagged, uses a 128×128 bitmap in both) |
+| Vehicle placements: the byte at 0x58 is the multiplayer team and the word at 0x5A the multiplayer spawn flags, default bits 0 to 3 (slayer, capture the flag, king of the hill, oddball) and allowed bits 8 to 11 | `hugeass.map`'s 78 vehicle placements: the byte is 1 on exactly the blue team's; the word is 0x0303 on warthogs, tachikomas and pelicans, 0x0F0F on ghosts, 0x0404 on 16 unnamed jets, 0x0808 on the night jet and 0 on vehicles its scripts create; OpenSauce leaves these bytes unnamed |
+| Script function and engine global tables: Halo PC's have entries this build's lacks, so a compiled index names another entry from some point on; value types are numbered alike | the compiled scripts of the sample, each call's function index against the name its first child keeps, and each engine global's index against its name: `timberland.map` 23 calls shifted (`player_effect_start` by 29), `ui.map` 11 (`camera_set` by 1), `hugeass.map` 3 calls and 1 global (`rider_ejection`, 158 against 147), `extinctionrevanepic2.map` 9 calls, and 4 of a function this build lacks; no other stock map has scripts; each call's value type is the type of its function here (1,485 of 1,485 in `hugeass.map`), or one the call site casts to |
+| Bitmaps the Xbox keeps in monochrome formats and Custom Edition as 32-bit color at the same size keep their channels (A8Y8 as A8R8G8B8 with red the luminance and alpha the alpha) | 24 of the 26 such bitmaps of `bloodgulch.map` decode to exactly the Xbox's values; the other 2 have other content |
+
+### Assumptions (not verified)
+
+- **Placement of resource-held tags.** They are placed after the tag data,
+  aligned to 4 bytes, as OpenSauce's unimplemented loader outlines
+  (`s_cache_file_data_load_state`); how Custom Edition itself places them is
+  not known, and nothing found depends on it.
+- **Which chicago extended maps.** The four-stage maps are kept, as the
+  renderer draws four stages; that Custom Edition's two-stage maps are a
+  fallback for older hardware is an inference (BlamLib's exporter makes the
+  same choice).
+- **Centroid nodes of local-node parts** are taken to be the model's nodes:
+  they are within the model's node count in every map, and they are only
+  used to sort transparent parts.
+- **Editing-kit pointers are cleared.** The definition pointers of relocated
+  blocks and data are set to 0: they refer to nothing in the game process.
+- **Name comparison** is exact (case-sensitive), which matched every sample
+  sound.
+
+## Limits and remaining work
+
+- **What the validator corrects is lost.** A community map's data that the
+  validator corrects (an index past its block, an enum past its values) is
+  what the game then runs; Halo PC read past such data unchecked.
+- **Ogg Vorbis sounds** are decoded when the map loads (stb_vorbis, public
+  domain) and encoded again as Xbox ADPCM in memory
+  (`port/linux/game/custom_edition_sounds.c`); one that cannot be decoded is
+  silenced, and still logs when played.
+- **Models of 44 nodes or more** are drawn a part's nodes at a time, given
+  local nodes when they have none; one whose part's vertices name more
+  nodes than a part holds is refused.
+- **Linear bitmaps whose rows are not a multiple of 64 bytes**, and
+  textures larger than 4096 pixels a side, are not drawn.
+- **Halo PC's HUD meters' minimum alpha** (where the Xbox's meters have an
+  overlays block) is dropped, and **its weapon functions "primary firing on"
+  and "secondary firing on"** are the Xbox's primary and secondary firing.
+- **Button prompts on replaced icon sheets** show what the map's icon bitmap
+  has where the Xbox's buttons are.
+- **Channel orders are per texture**: multipurpose maps and meters also drawn
+  another way keep Halo PC's channels.
+- **Scripts that use what this build does not have**: a call of a function
+  this build lacks, or a read of an engine global it lacks, does nothing
+  (a constant of its type's harmless value, logged by name:
+  `custom_edition_scripts.c`); only one that gives a script's index refuses
+  the map. Maps that need OpenSauce's runtime features are refused; a map
+  that only carries its tags (`project_yellow`) runs without them, as on
+  stock Custom Edition.
+- **Halo PC behaviours** some maps were made around (Chimera's map list,
+  `custom_edition_behaviours.inc`) are followed where this build can, and
+  each is logged.
+- **The conversions are one-way and in memory**: nothing is written to the
+  map files.
+
+### How far Custom Edition tags are from the Xbox tags
+
+`tools/custom_edition_tag_footprints.py` compares the tags a Custom Edition
+cache and the Xbox cache of the same level both keep (same group, same name),
+without any tag definitions. A tag's *footprint* is the distance from its
+address to the next tag's (its structure and the block data after it); its
+*structure size* is estimated as the distance to the lowest address in the
+footprint that the footprint points at (its first child block). Equal
+footprints, level after level, suggest a group's layout is unchanged; they do
+not prove it.
+
+The Xbox caches available are the retail ones, build 01.10.12.2276, not the
+01.01.14.2342 build this repository reconstructs: they stand in for it, and
+differences between the two Xbox builds are not measured. Run on the 14
+levels both sets have (13 multiplayer levels and `ui`):
+
+```
+python tools/custom_edition_tag_footprints.py --blocks assets/custom_edition "<Xbox 2276>/maps"
+```
+
+- **48 groups have the same footprint for every shared tag in every level**:
+  `Soul actv ant! bipd colo cont deca eqip flag fog font foot grhi hmt hud#
+  hudg itmc jpt! lens lifi ligh lsnd mach metr mgs2 mply part pctl phys pphy
+  scen schi senv sgla sky smet snde soso spla ssce str# swat trak udlg unhi
+  vcky vehi wind`. The shader groups among them have the same layout, but
+  not the same type values (above).
+- **Groups whose footprints differ, but whose structures match**: UI widgets
+  (`DeLa`, 464 of 657 footprints equal, 423 of 423 structures), animations
+  (`antr`, 213/239), collision models (`coll`, 331/345), effects (`effe`,
+  4140/4166), projectiles (`proj`, 197/210), weapon HUDs (`wphi`, 196/222),
+  weapons (`weap`, 39/182, structures 182/182), globals (`matg`, 1/14,
+  structures 14/14) and scenarios (`scnr`, 0/14, structures 13/14), plus, in
+  `ui` only, bitmaps, sounds and string lists. These differ in their block
+  data. The flamethrower's tags account for every `effe`, `proj` and `wphi`
+  difference and all but one `coll` difference; 11 of the 14 weapons (every
+  player weapon and both vehicle guns) differ in every level.
+- **What differs in those blocks** (`--blocks`: the top-level blocks of each
+  differing tag, found without definitions and compared): almost always
+  the number of elements, or whether a block has any, which is content:
+  weapons 143 count and 26 presence differences, UI widgets 158 and 63,
+  scenarios 36 and 13, projectiles 13, weapon HUDs 78 presence, collision
+  models 26 count. Every weapon difference checked in Blood
+  Gulch lies in a predicted-resources list (8-byte elements, weapon
+  offset `0x4E4`; OpenSauce `weapon_definitions.hpp`), or, for the
+  flamethrower, also in its attachments; the globals differ in their
+  cheat powerups (16 against 14). The rest (flamethrower effects 26,
+  globals 13, animations 39, one collision model, and 3 in `ui`) keep their element counts but
+  span a different amount of data up to the next block, which this method
+  cannot split into element size and nested content: for the globals, the
+  block in question (`player_info`, 0xF4-byte elements without blocks of
+  their own) spans more than its elements, so other data sits in the span.
+  No difference found has to be a layout change, and the two maps run did
+  not show one.
+- **Groups only Custom Edition has**: `mod2` (models), `scex` (a transparent
+  shader type), `devc` and `tagc`, in all 14 levels; **only the Xbox has**:
+  `mode` (models) and `sotr` (a transparent shader type), besides the groups
+  Custom Edition keeps in resource maps.
@@ -1,16 +1,22 @@
 # Android

+The app of Ringfall: Mjolnir VR (application id `io.github.cesarus85.ringfall`;
+its Java classes keep the decompilation's package, `com.halo.decomp`).
 `ninja android` builds the game for 64-bit ARM Android (arm64-v8a).
 `ninja android_apk` makes an app from it:
 `port/android/app/build/outputs/apk/debug/app-debug.apk`.

 The game shows its graphics with OpenGL ES 3. It plays sound through SDL3
 (AAudio). It accepts input from game controllers, for example a PlayStation
-5 DualSense on Bluetooth. The app needs Android 9 (API 28) or later. It
-operates on 64-bit-only devices, for example the Pixel 9 Pro XL.
+5 DualSense on Bluetooth, and from the touchscreen (refer to "Controls").
+The app needs Android 9 (API 28) or later. It operates on 64-bit-only
+devices, for example the Pixel 9 Pro XL.

 The Android build uses the platform layer of the Linux build
 (`port/linux/src`). Refer to [port/linux/README.md](../linux/README.md).
+Physical mice use the same control bindings. During play, F12 toggles mouse
+capture; captured mode hides Android's pointer and uses relative movement for
+continuous aiming, while releasing capture restores normal pointer behavior.

 ## Requirements

@@ -28,6 +34,36 @@ ninja) and these items:
  1.2.5 and SDL 3.4.16 to `build/android/third_party`. Gradle downloads the
  Android Gradle Plugin.

+On Windows, build in WSL2 (Ubuntu 24.04). The Android build does not run
+on Windows itself. Enter
+`wsl -d Ubuntu -- bash tools/wsl_setup_android.sh` one time: it installs
+the tools and the Android SDK and NDK in WSL (apt asks for your
+password). Then enter
+`wsl -d Ubuntu -- bash tools/wsl_build_android.sh` for each build. The
+script copies the repository into WSL (`~/halo-build/src`) with LF line
+endings (a Windows checkout has CRLF line endings, which the build's text
+tools do not accept), builds there, and puts the APK in
+`dist/android/app-debug.apk`. Only the changed files are copied, so the
+next build is incremental. Install the APK with the adb of Windows.
+
+A build that you make yourself has a different signature from the builds
+of GitHub Actions. Android installs it only after you remove the app, and
+removing the app deletes its data folder (`maps/`, `save/` and
+`config.toml`). Thus a change between the builds of GitHub Actions and your
+own builds loses the saved games, unless you copy them first (below).
+Your own builds all have the same signature (the debug key of WSL,
+`~/.android`), so they install over each other and keep the data
+(`adb install -r`).
+
+To keep the saved games before you remove the app, enter
+`adb pull /sdcard/Android/data/io.github.cesarus85.ringfall/files/save/u` (the profiles).
+After the new install, before the first start of the app, enter
+`adb push u /sdcard/Android/data/io.github.cesarus85.ringfall/files/save/u`. The app reads
+and overwrites what adb pushes. adb cannot add files to `save/u` or `save/z` once the app made them, or
+change files that the app wrote, so push before the first start. adb cannot read
+some files that the app writes (the `blam.lst` files of `save/z`), so `adb pull`
+of the whole `save` folder stops there.
+
 ## Build and install the app

 1. Go to the root folder of the repository.
@@ -41,8 +77,8 @@ ninja) and these items:
 ## Game data

 The game needs the `maps/` folder from an Xbox disc image (`.xiso` or
-`.iso`) of any version of the game. The app extracts `maps/` from the disc
-image. The app keeps the data in `/sdcard/Android/data/com.halo.decomp/files`.
+`.iso`) made from your own copy of the game, any version. The app extracts `maps/` from the disc
+image. The app keeps the data in `/sdcard/Android/data/io.github.cesarus85.ringfall/files`.

 To install the data with the app:

@@ -57,16 +93,18 @@ To install the data with the app:
 To install the data from a computer:

 1. Start the app one time. The app makes its folders.
-2. Enter `adb push <folder>/. /sdcard/Android/data/com.halo.decomp/files/`.
+2. Enter `adb push <folder>/. /sdcard/Android/data/io.github.cesarus85.ringfall/files/`.

-| Item | Location in `/sdcard/Android/data/com.halo.decomp/files` |
+| Item | Location in `/sdcard/Android/data/io.github.cesarus85.ringfall/files` |
 | --- | --- |
 | Saved games (`z:\` and `u:\`) | `save` |
 | Log | `debug.txt` |
 | Settings | `config.toml` |

 To make a copy of the saved games, enter
-`adb pull /sdcard/Android/data/com.halo.decomp/files/save`.
+`adb pull /sdcard/Android/data/io.github.cesarus85.ringfall/files/save/u` (the profiles).
+An `adb pull` of the whole `save` folder stops at the `blam.lst` files of
+`save/z`, which adb cannot read.

 ## Controls

@@ -92,17 +130,91 @@ with the positions on the Xbox controller:
 | Create | back | |

 The controller gets the rumble. The back gesture of Android is the B
-button. A Bluetooth or USB keyboard operates as on Linux. The screen does
-not accept touch input.
+button. A Bluetooth or USB keyboard operates as on Linux.
+
+The touchscreen operates the menus: tap an item to select it (on a
+setting with values, tap its left or right half), tap a button of the key
+at the bottom of a screen (for example "B = Back") to push it, and drag to
+scroll a list (down or right steps back, up or left steps forward). A drag
+stops at the first and the last item, and it does not change a setting's
+value. Touches that start in the edge-gesture zones of Android do not tap
+or scroll at the sides, and do not scroll at the top and bottom, because the
+first swipe from an edge in full screen only shows the system bars.
+
+A tap during a cinematic that can be skipped skips it, as A does. On the
+on-screen keyboard, tap a key to press it, "B =BACK" to cancel and
+"A =ENTER" to accept the name.
+
+### Touch controls
+
+In a game, the app shows touch controls over the picture. They are a
+controller for player 1. With the default buttons of the profile:
+
+| Control | Function in the game |
+| --- | --- |
+| stick (lower left) | move |
+| swipe on the screen away from the buttons | look |
+| Fire | right trigger |
+| Grenade | left trigger |
+| A / Jump, B / Melee, X / Reload, Y / Weapon | A, B, X, Y |
+| Crouch, Zoom | left and right stick clicks |
+| Light, Gren. type | white, black |
+| Pause, Back | start, back |
+| Up, Down, Left, Right | D-pad |
+
+The names on the buttons follow the profile's "Button layout" (Settings >
+Gamepads): with "Swap triggers", the right trigger's button says "Grenade".
+The stick moves the player with every "Stick layout", southpaw too.
+
+A finger that holds a button can also swipe to look, so you can fire and
+aim with one thumb. The controls are a finger wide (48 dp) or larger, but
+on a small screen of high density they stay apart rather than reach that
+size. A short tap reaches the game even when it is shorter than one frame.
+Swipes that start in the edge-gesture zones of Android do not turn the
+view. The swipe aims as the controller's stick does, not as a mouse: the
+aim slows over a target and follows a moving one, as with a controller,
+and it follows the profile's "invert look" (the gyroscope turns the view
+as the phone turns, never inverted). The setting `input.touch_aim_assist`
+turns the aim assist off. "Look sensitivity" sets how far a swipe turns;
+the mouse settings do not apply.
+
+The touch controls show only in a game. In the menus and during
+cinematics they hide, and the touchscreen operates the menus as described
+above. They also hide when a controller is connected, for example the
+built-in controller of a handheld. A device without a touchscreen (a TV)
+never shows them. The setting `input.touch_controls` changes this (refer
+to "Settings").
+
+The buttons at the top of the screen:
+
+- "Hide" removes the controls (and stops the gyroscope aiming and the
+  vibration) until you push "Touch"; the app remembers it.
+- "Options" opens these items:
+  - "General": the phone's vibration (on by default; it follows the
+    vibration setting of the game's profile), aiming with the gyroscope
+    (off by default), a floating move stick (off by default: the stick goes
+    where your thumb lands in the lower left of the screen), the opacity of
+    the controls, "Hide or add buttons" (hide a button, add a copy of a
+    button) and "Edit buttons size".
+  - "Edit buttons layout": drag the controls to new positions, then push
+    "Save". "Export" and "Import" write and read a layout file with the
+    file picker of the system.
+  - "Look sensitivity".
+
+"Hide" and "Options" act when the finger lifts on them: a swipe that
+starts on them turns the view instead.
+
+The app keeps the layout in its own preferences, not in `config.toml`.
+Removing the app's data or the app removes the layout.

 ## Settings

 The settings are in `config.toml` in the data folder of the app. To change
 them:

-1. Enter `adb pull /sdcard/Android/data/com.halo.decomp/files/config.toml`.
+1. Enter `adb pull /sdcard/Android/data/io.github.cesarus85.ringfall/files/config.toml`.
 2. Change the file.
-3. Enter `adb push config.toml /sdcard/Android/data/com.halo.decomp/files/`.
+3. Enter `adb push config.toml /sdcard/Android/data/io.github.cesarus85.ringfall/files/`.

 At the first start, the game writes the file with the default values. To
 get the default values again, delete the file.
@@ -113,8 +225,11 @@ These settings are only for Android:

 | Setting | Function |
 | --- | --- |
+| `input.touch_aim_assist` | `true` (the default): the touch controls' swipe aiming gets the aim assist of a controller (the aim slows over a target and follows a moving one). `false`: none, as with a mouse; the bullets' own autoaim stays. |
+| `input.touch_controls` | The touch controls in a game. `"auto"` (the default): shown on a touchscreen while no controller is connected. `"on"`: also shown with a controller. `"off"`: never shown. A device without a touchscreen never shows them. The menus take taps in any case. |
 | `display.screen_width` | The number of columns of the 480-line picture. `0` (the default): the shape of the display (1068 on a 20:9 phone). `640`: the 4:3 shape of the Xbox. |
 | `debug.sample_seconds` | Refer to "Find problems". |
+| `debug.memory_watch` | `true` (the default): the app notices the game's writes to textures and vertices by page protection. `false`: it compares page contents once a frame instead, which is slower. Refer to "Limits". |

 ## Internet play

@@ -148,16 +263,24 @@ select "Yes":

 1. The app downloads the new version.
 2. The package installer of Android opens. At the first update, Android asks
-   you to let Halo install apps. Allow it.
+   you to let the game install apps. Allow it.
 3. Select "Update". Android replaces the app.
 4. Select "Open" to start the new version.

 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/ringfall-release.jks
+    password=<the keystore's password>
+    keyAlias=ringfall
+
+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/`.
+folder: first make a copy of `maps/` and `save/u`.

 ## Widescreen

@@ -168,7 +291,10 @@ 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).
+
+All the ports draw this way.

 ## VR

@@ -181,7 +307,7 @@ instead.

 Controls in play (in the menus the buttons are the Xbox's by position):

-| Controller | Halo |
+| Controller | Game |
 | --- | --- |
 | right trigger / left trigger | fire / throw grenade |
 | right grip / left grip | melee / switch weapon |
@@ -229,7 +355,7 @@ through a shader that decodes to linear, and the stored bytes are the
 game's. Camera shake is off in VR.

 A file named `xr_test` in the data folder
-(`adb shell touch /sdcard/Android/data/com.halo.decomp/files/xr_test`)
+(`adb shell touch /sdcard/Android/data/io.github.cesarus85.ringfall/files/xr_test`)
 starts a self-test instead of the game, which needs no game data: each eye
 in its own colour (red while the right trigger is held), a checkerboard
 screen in the room (its top-left square red), and the controllers' buttons
@@ -239,12 +365,6 @@ Not done yet: aiming with the controller and the weapon in the hand, the
 HUD's parts on the controllers, zoom through the scope, a first-person view
 in vehicles, and a separate depth for the HUD's reticle.

-## How it works
-
-The changes are in `#ifdef HALO_ANDROID` in `rasterizer_xbox.c`, `render.c`,
-`ui_widget.c`, `cinematics.c`, `main.c` and
-`rasterizer_xbox_screen_effect.c`.
-
 ## How the port operates

 ### ILP32 code
@@ -321,7 +441,11 @@ functions of OpenGL ES 3.2 if they are available:
  changes the indices.
 - On OpenGL ES 3.1 and later, the visibility tests (lens flares) count
  samples with an atomic counter, as the NV2A did. OpenGL ES 3.0 tells only
-  if a sample is visible.
+  if a sample is visible. The GPU copies the counters at the end of each
+  frame, and the CPU reads the copy two frames later, when the frame's fence
+  has passed: a result is the latest count the GPU has finished, as with
+  the query buffer of desktop OpenGL. A read of the counters themselves
+  waits for the GPU, which halved the frame rate on Turnip (Zink).

 ### Calling conventions

@@ -344,9 +468,17 @@ floating-point contraction, as on x86.

 ### Game source changes

+The port's code tells three things apart, each its own macro, which the
+Android build defines all of (`tools/android_build.py`):
+
+- `HALO_ARM64_GUEST`: the guest's ABI (ILP32 AArch64 code in a 64-bit
+  process);
+- `HALO_GLES`: the OpenGL ES renderer;
+- `HALO_ANDROID`: the app (its display, input, files and lifecycle).
+
 The x86 inline assembly is replaced by C (refer to
 [port/linux/README.md](../linux/README.md#game-source-changes)).
-These changes are in `#ifdef HALO_ANDROID`:
+These changes are in `#ifdef HALO_ARM64_GUEST`:

 - Seven `#pragma bss_seg(".bss")` lines are removed. The Darwin target does
  not accept them.
@@ -373,6 +505,8 @@ assembly of the port is necessary:
  at this interval. This finds hangs on devices without root access.
 - Set `gl_debug = true` in `[debug]` of `config.toml`. The log then shows
  the OpenGL ES errors.
+- The log says which write tracking the app uses: "page protection"
+  (devices) or "page hashes" (the emulator, or `debug.memory_watch = false`).

 ## Limits

@@ -380,6 +514,16 @@ assembly of the port is necessary:
 - The device must let the app reserve the fixed guest addresses, from
  `0x80000000` to approximately `0x89000000`. If the addresses are not
  available, the app shows a message.
- The game does not accept touch input. Use a controller or a keyboard.
+- Touch operates the menus and skips cinematics. In the game, the touch
+  controls appear when no controller is connected; their size follows the
+  height of the screen (larger on a tablet than on a phone), never smaller
+  than a finger.
 - Kernels with 16 KB pages (a developer option of Android 15) do not
  operate. The Xbox memory uses 4 KB pages.
+- The x86 Android emulator runs the app through its ARM translation. The
+  translation cannot deliver the page faults that the renderer uses to
+  notice changed textures and vertices. On the emulator the app compares
+  page contents once a frame instead ("write tracking: page hashes" in the
+  log). This is slower, and a write shows one frame later, so moving
+  geometry can glitch briefly. `debug.memory_watch = false` does the same
+  on a device.
@@ -0,0 +1,177 @@
+# 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 your own disc image of Halo: Combat Evolved for the original Xbox (`.iso` or
+   `.xiso`, any version) in Downloads (or Documents, the Desktop, a memory
+   card).
+2. Download `Install-Ringfall-Mjolnir-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 "Ringfall: Mjolnir VR" to the Steam library
+   and switches back to Gaming Mode. Start it 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 `ringfall-mjolnir-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/RingfallMjolnirVR`: the launcher (`ringfall-mjolnir-vr.sh`)
+  and the release APK (`RingfallMjolnirVR.apk`); the folder of the builds
+  before the name, `~/Documents/HaloCE`, renamed to it, and their "Halo VR"
+  shortcut replaced;
+- 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, unless it is there: added by Steam itself
+  (`steam://addnonsteamgame`, as SteamOS's "Add to Steam" does) from
+  `Ringfall Mjolnir VR.desktop` beside the game, then the library pictures
+  under the id Steam gave it. Steam is not closed: on the Frame, Desktop
+  Mode runs inside Gaming Mode's session, and closing Steam ends it (and the
+  installer with it). An old "Halo VR" shortcut is left for the player to
+  remove (Steam would write it back);
+- what it did in `install.log` beside the game.
+
+`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 io.github.cesarus85.ringfall/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/RingfallMjolnirVR` |
+| 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 ("Ringfall: Mjolnir VR", a non-Steam game)
+runs `~/Documents/RingfallMjolnirVR/ringfall-mjolnir-vr.sh` (`port/android/steam_frame_launch.sh`),
+which starts the game as Steam starts an Android title of its own:
+`lepton waitforexitandrun -- ~/Documents/RingfallMjolnirVR/RingfallMjolnirVR.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 the game" (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/RingfallMjolnirVR` 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/RingfallMjolnirVR/maps
+    adb -s <frame-ip>:5555 push assets/maps/. /home/steamos/Documents/RingfallMjolnirVR/maps/
+    adb -s <frame-ip>:5555 shell chmod -R 777 /home/steamos/Documents/RingfallMjolnirVR
+
+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,440 @@
+# VR roadmap
+
+What Ringfall: Mjolnir VR (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/RingfallMjolnirVR` |
+| 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 25, 2026-10-10): 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. Second part **done** (in `main` 2026-10-06; Quest 3 good): buttons remapped, finer turning and vignette choices; the flashlight by tapping the head taken out (did not work) |
+| 3b | The whole body: torso from head and hands, legs and feet following in the room; full / arms only / hands only | **done** (in `main` 2026-10-10; Quest 3 good): `vr.body` "full" ("Full body" in the VR options; "arms" still the default), legs walking the way the player moves, feet on the ground. Also in: voice chat's push to talk on the free hand's grip. Steam Frame: its cost still to measure |
+| 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 **done** (in `main` 2026-10-06): the app's import (tried on the Quest 3: all 24 maps; on the Frame kept in `~/Documents/RingfallMjolnirVR`), a Steam Frame installer from Desktop Mode (`STEAM_FRAME.md`; tried on the Frame: the old folder renamed, the shortcut added by Steam), a release signing key (CI and local builds the same). Sprint by arm swing still open |
+| R | Release as **Ringfall: Mjolnir VR** (no "Halo" in the product's name): app name, id `io.github.cesarus85.ringfall`, icon and library pictures (`tools/ringfall_art.py`), Frame folder and installer, release assets, README; the repository renamed | **done** (in `main` 2026-10-06; Quest 3 and Steam Frame good) |
+
+## 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); four since the second part (below). 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 2, second part (done)
+
+In `main` 2026-10-06; tried on the Quest 3 (with the rename): good. The flashlight by tapping the head (after HaloCE-Quest-VR)
+did not work in the headset and was taken out again; the button stays.
+The VR
+options (Y) have four pages: PLAY ("Weapon hand", "Mirrored controls",
+laser, crosshair, motion tracker, body, fingers, the Warthog's wheel),
+COMFORT (turning, the vignettes), BUTTONS (the actions' buttons,
+"Reset buttons to defaults", the controller buttons page) and MORE (graphics, refresh rate, resolution, Quit).
+
+Buttons remapped (BUTTONS page; `vr.c` `controls_remapped`):
+- Jump, the flashlight (held: switch grenades), action/reload, switch
+  weapon, crouch, zoom and melee each go on one of seven buttons: A, B,
+  X, Y, the move stick's click, the turning stick's, the weapon hand's
+  grip. Moving an action to a button swaps it with the action there, so
+  none is ever left without one.
+- The triggers, the free hand's grip, the menu button, the Steam Frame's
+  bumpers, D-pad and View button keep theirs; the menus keep the buttons
+  as they are.
+- Applied after the left-handed mirroring, on the gamepad's sides: the
+  same on the Touch and the Frame controllers, and a left-handed player's
+  buttons are the mirror image of the right-handed ones (on the Frame,
+  mirrored, the left D-pad's). The defaults are the old layout, the
+  host's bindings and the ABI unchanged.
+- The melee's aim and jab follow its button; the grips on a Warthog's
+  wheel press nothing, whatever the grip does.
+- The controller buttons page shows each action where its button is.
+
+Comfort (COMFORT page): snap turns 10 to 45 degrees by 5, 60, 75, 90;
+smooth turning 30 to 150 degrees a second by 15, then to 300 by 30; the
+vehicle vignette Off, 15 to 100%; the on-foot vignette (off by default)
+while the stick turns smoothly, or also while the move stick moves, as
+far as the sticks are pushed, with its own strength. The old values are
+among the steps; defaults unchanged.
+
+Transparent geometry: room for 2048 groups a window (the Xbox's 384,
+below).
+
+| Setting | Values |
+| --- | --- |
+| `vr.button_jump` | `"a"` (default), `"b"`, `"x"`, `"y"`, `"move_stick"`, `"turn_stick"`, `"grip"`: as right-handed, mirrored with `vr.mirror_controls` |
+| `vr.button_light` | the flashlight, held switch grenades; `"b"` (default) |
+| `vr.button_action` | action, reload; `"x"` (default) |
+| `vr.button_weapon` | switch weapon; `"y"` (default) |
+| `vr.button_crouch` | `"move_stick"` (default) |
+| `vr.button_zoom` | `"turn_stick"` (default) |
+| `vr.button_melee` | `"grip"` (default) |
+| `vr.foot_vignette` | `"off"` (default), `"turning"` (smooth turns), `"moving"` (and moving) |
+| `vr.foot_vignette_strength` | 0.15 to 1, `0.7` (default) |
+| `debug.vr_options` | `false` (default); `true` shows the VR options off the headset (the emulator) |
+
+Checked in the emulator (`debug.vr_options`): the four pages without
+overlaps, each row's values, swaps and reset, the controller buttons page
+right- and left-handed after swaps, the settings kept over a restart, a
+15-bot game as before.
+
+To try in the headset (Quest 3 and Steam Frame):
+1. Defaults: every button as before (jump, light/held grenades, action,
+   switch weapon, crouch, zoom, melee by grip and by swing), right- and
+   left-handed, mirrored and not; the menus' A and B.
+2. BUTTONS: swap jump and melee (jump on the grip, melee on A): both work,
+   the melee jabs and aims where the head looks; light on a stick click
+   (tap: light, hold: grenades); the controller buttons page says so.
+   At the Warthog's wheel with jump on the grip: no jump while holding
+   the wheel. Reset: all back.
+3. The same left-handed with mirrored controls (on the Frame the left
+   D-pad), and with `Mirrored controls: Off`.
+4. COMFORT: snap 10 and 90, smooth 30 and 300; vehicle vignette 15% and
+   100%; on-foot vignette "Smooth turns" (nothing with snap turns),
+   "Moving, turning", strength 15% and 100%; no vignette in a vehicle
+   from the on-foot one, none in the menus.
+5. A game of 30 and more players: effects, glass and water stay; the log
+   (`adb logcat -s halo`) says `rasterizer: N transparent geometry groups
+   in a window` once a window passes 384; frame time as before.
+
+## 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.
+
+## Step 3b (done)
+
+On `feature/vr-voice-and-body`, not yet tried in the headset. The neck
+pivot, the planted feet with their steps and the leg's clamped reach follow
+HaloCE-Quest-VR (CC0), its full body, rebuilt in
+`port/linux/game/vr_body.c` on this port's skeleton (`vr_arms.c`).
+
+- `vr.body = "full"` (VR options, Body: "Full body") draws the player's own
+  biped under the first-person arms and weapon: its torso, hips and legs, in
+  the map's own model and colours. "arms" stays the default until the
+  headsets have tried it.
+- Drawn among the world's objects, so it sorts against the world by depth;
+  the first-person weapon and arms, drawn before the world into the
+  stencil, stay over it, as before. In both eyes (multiview on the Quest,
+  each eye on SteamVR), posed once a frame for every eye and the scope.
+- The torso: the torso's heading (the head's beyond 15 degrees, drawn
+  towards the hands, the stick's turns at once), upright from the hips to a
+  neck 14 cm behind and 20 cm below the eyes as the head turns about it
+  (looking down, the eyes go forward and the chest stays behind them). The
+  aiming's twist and bend of the third-person torso are taken out.
+- The hips: down with the physical crouch (and back a little, the torso
+  leaning forward), a third of the way with a lean (the spine tilts the
+  rest). The body's model has its neck higher than the eyes' pivot: it is
+  moved down to it, so the shoulders stay below the eyes, crouched by the
+  button too.
+- The legs: the game's own animation (walking, running, jumping, crouched
+  by the button). Moving, the hips and legs stay as the game faces them, so
+  its own choice of animation (forward, back, aside, as for any player,
+  by the way it moves against the way it faces) runs along the way the
+  player moves, and the spine turns the torso; standing, the hips turn to
+  the torso's heading (eased, 0.12 s). Walking off, the feet ease from
+  where they stood into the walk (0.2 s); stopping, they stay where the
+  walk left them and step into place. Standing still, the feet stay
+  planted and step, one at a time (0.22 s, 6 cm lifted), when the body has
+  turned 35 degrees from them or their place moved 18 cm; the knees bend by
+  IK to them as the hips go down. Moved 80 cm at once (a teleporter), they
+  are put down there.
+- The ground: put down, each foot rests on the ground under it (a slope, a
+  stair), its height above the ground as the animation has it, tilted with
+  the slope (no steeper than 45 degrees), up to 45 cm from the ground under
+  the body; a foot's ground below it lowers the hips as far. Rays straight
+  down, read only, cast only as the feet are put down (three: under the
+  body and each foot) and as one steps (one), none while walking, where
+  the animation's feet are kept; eased (0.08 s) in and out. Nothing found
+  (a ledge): level.
+- Hidden: the head and neck (shrunk onto the neck's root: no head or
+  collar seen from inside), the third-person arms (shrunk onto their
+  shoulders), the third-person weapon and all the biped carries.
+- The first-person arms hang from the body's shoulders: beside its neck,
+  as wide as its shoulder joints within 14 to 24 cm (the aiming's shrug
+  left out). Left-handed, the shoulders go into the mirror with the arms
+  (the room's left one is the model's right): the body itself is the
+  room's, not mirrored.
+- Seats: a passenger in an open vehicle (the Warthog's back) sits as the
+  seat's animation has it, the head and arms shrunk alike; at a wheel or a
+  gun the body is drawn whole as before (its hands on them, no
+  first-person weapon); in a closed seat (Ghost, Banshee, tank) none.
+- Not drawn when dead, in cutscenes, in third person, in a mirror's view;
+  camouflage as the game has it.
+- Only drawn, on this machine: the game's own pose, hit boxes, markers and
+  network messages are unchanged.
+- Cost: `vr.log_performance` adds `body ... ms a frame in ... poses` to the
+  `first person:` line. In the emulator 0.006 to 0.025 ms a pose standing
+  (as busy as the emulator was), up to 0.1 ms averaged while turning with
+  the feet's rays (at most a few a second); the drawing is one more biped
+  model (as one more player close by).
+
+| Setting | Values |
+| --- | --- |
+| `vr.body` | `"full"` (the whole body), `"arms"` (default), `"hands"`, `"off"` |
+| `debug.vr_body` | `"off"` (default); off the headset (the emulator) the body posed from the flat camera: `"eye"`, `"down"` (looking down 60 degrees, 90 degrees wide), `"front"`, `"side"`, `"back"` (the camera 2.6 m away); after a colon the head's motion: `"cycle"` (turning, crouching, leaning, 5 s each), `"still"`, `"turn"`, `"crouch"`, `"lean"`, `"raw"` (the game's pose, only shrunk). Logs its pose once a second |
+
+Checked in the emulator (`debug.vr_body`): the cyborg's 19 nodes (bip01
+pelvis, spine, spine1, neck, head, clavicles, arms, thighs, calves, feet);
+the body standing, crouched physically and by the button, leaning,
+turning with the feet stepping; looking down, the shoulders below the eyes
+and no head or collar; two-minute bot games on Blood Gulch with it on and
+off, deaths and respawns, nothing in the log. Then the legs by the way of
+moving (strafing, backwards, diagonally with the touch stick: the game's
+sideways and backwards walk) and the feet on the ground: on the ramp of a
+Blood Gulch base, the upper foot 15 cm up, the lower 10 cm down, both on
+it; stairs not reached in the emulator (Prisoner's spawn was level). Three
+rays when the feet are put down, one a step, none walking. Screenshots in
+`build/body-shots/` (local).
+
+Push to talk is built on the same branch: voice chat's talking on the free
+hand's grip, while it holds neither the weapon's foregrip nor the Warthog's
+wheel (`audio.voice_chat`, VR options PLAY page "Voice chat": push to talk
+(grip), open mic, off).
+
+To try in the headset (Quest 3 and Steam Frame), with `vr.body = "full"`
+(VR options, Body: Full body) and `vr.log_performance = true`:
+1. Standing, looking down: torso, hips, legs and feet, the shoulders below
+   the eyes, no head, collar or helmet in view, the chest not in the way;
+   the arms from the shoulders, lined up with the body, the weapon as
+   before.
+2. Turning the head alone: the body stays within about 15 degrees, then
+   follows; turning further, the feet step after it, one at a time, and
+   settle. Snap and smooth turns: the body turns, the feet step.
+3. Physical crouch: the knees bend, the feet stay; kneeling deep, nothing
+   of the body in the eyes. Leaning forward and aside: the torso tilts, the
+   feet stay. Crouch button: the game's crouch, shoulders below the eyes.
+4. Walking, running, jumping by the stick: the legs walk with the game's
+   animation, no sliding when starting or stopping. Strafing left and
+   right, walking backwards and diagonally, also with the head turned away
+   from the way of walking: the legs step the way the body moves (sideways,
+   backwards), the torso facing as the head and hands have it; stopping,
+   the hips turn back under the torso and the feet step into place.
+4a. Ground: standing still on a slope (Blood Gulch's hills and the bases'
+   ramps), across it and along it: both feet on the ground, tilted with
+   it, the lower knee straighter, the hips down with the lower foot; on
+   stairs (Prisoner, Chill Out, Damnation), one foot a step higher than
+   the other, turning in place there: each step lands on its stair. At a
+   ledge, one foot over it: level, nothing odd.
+5. Left-handed (`vr.handedness = left`, mirrored or not): the arms from
+   the body's shoulders, the weapon in the left hand, the body as
+   right-handed.
+6. Vehicles: Warthog driver and gunner as before (body with its hands on
+   the wheel or gun); Warthog passenger: seated legs and torso, the
+   first-person arms from its shoulders; Ghost, Banshee, Scorpion: no body.
+7. Dying and respawning, a teleporter, a cutscene (campaign), the menus
+   and pause menu, the scope, camouflage, a game with 15 bots: nothing
+   broken, no body where it should not be.
+8. Body "Arms and hands", "Hands only", "Weapon only": as before.
+9. Performance: `first person: ... body ... ms` in `adb logcat -s halo`;
+   the Quest holds 90 Hz in a bot game; the Steam Frame's working time
+   against "arms" (about 12 ms of 13.9 before).
+10. Push to talk (Voice chat: push to talk), in a network game with
+    another player: holding the free grip away from the weapon talks;
+    nothing while the free hand holds the foregrip or the Warthog's wheel;
+    "Open mic" talks without the grip; "Off" sends nothing (others still
+    heard).
+
+## 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 overflowed in
+  games of 30 and more players (the last submitted, glass, water,
+  particles, contrails, vanished). Raised to 2048 (320 KB) on
+  `feature/vr-comfort`, to check in a large game (step 2, second part,
+  test 6); upstream still has 384.
+
+## 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,16 +13,30 @@ 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") ?: "ringfall"
+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", "ringfall")
+}

 android {
    namespace "com.halo.decomp"
    compileSdk 35

    defaultConfig {
-        applicationId "com.halo.decomp"
+        // (the app's own id; the Java classes keep the decompilation's package)
+        applicationId "io.github.cesarus85.ringfall"
        minSdk 28
        targetSdk 35
        versionCode Math.max(1, buildNumber)
@@ -60,9 +74,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
            }
        }
    }
@@ -19,9 +19,15 @@
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
+    <!-- voice chat's microphone (asked for only when voice chat first talks) -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <!-- installing a new version of the game (Updater) -->
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

+    <!-- enableOnBackInvokedCallback: the back button and the back gesture
+         stay KEYCODE_BACK, which SDL passes to the game as B; with
+         predictive back (the default once an app targets Android 16) the
+         system would take them and the game would never see them -->
    <application
        android:label="@string/app_name"
        android:icon="@mipmap/ic_launcher"
@@ -29,7 +35,8 @@
        android:isGame="true"
        android:appCategory="game"
        android:theme="@android:style/Theme.DeviceDefault.NoActionBar.Fullscreen"
-        android:hardwareAccelerated="true">
+        android:hardwareAccelerated="true"
+        android:enableOnBackInvokedCallback="false">

        <!-- a game, for the system (isGame and appCategory above; the game
             modes' configuration) and for launchers that look for this -->
@@ -93,7 +100,7 @@
        <!-- the downloaded new version, for the package installer (Updater) -->
        <provider
            android:name=".UpdateProvider"
-            android:authorities="com.halo.decomp.update"
+            android:authorities="${applicationId}.update"
            android:exported="false"
            android:grantUriPermissions="true" />

@@ -0,0 +1,71 @@
+package com.halo.decomp;
+
+/**
+ * Gyroscope aiming (TouchControls): integrates the sensor's angular velocity,
+ * turned into the display's coordinates for its rotation, into radians of
+ * view turn between samples.
+ */
+final class GyroscopeAim {
+    /** below this (radians a second) a reading is the sensor's noise at rest, which must not drift the view */
+    private static final float NOISE = 0.01f;
+    /** a gap longer than this (seconds) starts over rather than turn at once */
+    private static final float LONGEST_GAP = 0.1f;
+
+    private long previousTime;
+    private int previousRotation = -1;
+    private float previousX;
+    private float previousY;
+
+    void reset() {
+        previousTime = 0;
+        previousRotation = -1;
+    }
+
+    /**
+     * takes one sample (its time in nanoseconds, the angular velocity about
+     * the device's x and y axes, the display's rotation 0..3) and puts the turn
+     * since the last into delta {yaw, pitch}; false while there is none
+     */
+    boolean sample(long time, float x, float y, int rotation, float[] delta) {
+        delta[0] = 0;
+        delta[1] = 0;
+        if (!Float.isFinite(x) || !Float.isFinite(y) || rotation < 0 || rotation > 3) {
+            reset();
+            return false;
+        }
+        float screenX = x;
+        float screenY = y;
+        switch (rotation) {
+            case 1:
+                screenX = y;
+                screenY = -x;
+                break;
+            case 2:
+                screenX = -x;
+                screenY = -y;
+                break;
+            case 3:
+                screenX = -y;
+                screenY = x;
+                break;
+            default:
+                break;
+        }
+        if (Math.abs(screenX) < NOISE)
+            screenX = 0;
+        if (Math.abs(screenY) < NOISE)
+            screenY = 0;
+        float seconds = (time - previousTime) * 1e-9f;
+        boolean valid = previousTime != 0 && rotation == previousRotation && seconds > 0 && seconds <= LONGEST_GAP;
+        if (valid) {
+            // the trapezoid rule over the two samples
+            delta[0] = -(screenY + previousY) * 0.5f * seconds;
+            delta[1] = -(screenX + previousX) * 0.5f * seconds;
+        }
+        previousTime = time;
+        previousRotation = rotation;
+        previousX = screenX;
+        previousY = screenY;
+        return valid && (delta[0] != 0 || delta[1] != 0);
+    }
+}
@@ -1,10 +1,25 @@
 package com.halo.decomp;

+import android.app.AlertDialog;
 import android.content.Context;
+import android.content.Intent;
+import android.graphics.Insets;
+import android.net.Uri;
 import android.net.wifi.WifiManager;
+import android.os.Build;
 import android.os.Bundle;
 import android.view.Display;
+import android.view.View;
+import android.view.ViewGroup;
+import android.view.WindowInsets;
 import android.view.WindowManager;
+import android.widget.Toast;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.nio.charset.StandardCharsets;

 import org.libsdl.app.SDLActivity;

@@ -15,6 +30,16 @@ import org.libsdl.app.SDLActivity;
 public class HaloActivity extends SDLActivity {
    /** lets system link's broadcasts in over Wi-Fi while the game runs */
    private WifiManager.MulticastLock multicastLock;
+    /**
+     * the latest system gesture insets {left, top, right, bottom}, in pixels;
+     * written on the UI thread, read by the game's thread: replaced as a
+     * whole, never changed in place
+     */
+    private volatile int[] gestureInsets = new int[] { 0, 0, 0, 0 };
+    /** the on-screen touch controls, over SDL's surface */
+    private TouchControls touchControls;
+    private static final int EXPORT_LAYOUT = 401, IMPORT_LAYOUT = 402;
+    private String pendingLayoutExport;

    @Override
    protected String[] getLibraries() {
@@ -24,21 +49,208 @@ public class HaloActivity extends SDLActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
+        if (savedInstanceState != null)
+            pendingLayoutExport = savedInstanceState.getString("pending-layout-export");
+        if (mLayout != null) {
+            touchControls = new TouchControls(this);
+            mLayout.addView(touchControls, new ViewGroup.LayoutParams(
+                    ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
+        }
        getWindow().addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
        preferHighestRefreshRate();
+        trackGestureInsets();
        acquireMulticastLock();
        // a new version looked for while the game starts
        Updater.start(this);
    }

+    /** the system's file picker, for the touch layout; no storage permission */
+    public void chooseLayoutFile(boolean export, String configuration) {
+        String message = export
+            ? "Choose the folder and the name of the touch layout file."
+            : "Choose a touch layout file. It replaces your buttons, the look sensitivity and the General settings.";
+        new AlertDialog.Builder(this)
+            .setTitle(export ? "Export the layout" : "Import a layout")
+            .setMessage(message)
+            .setNegativeButton("Cancel", null)
+            .setPositiveButton(export ? "Choose the place" : "Choose the file", (dialog, which) -> {
+                Intent intent = new Intent(export ? Intent.ACTION_CREATE_DOCUMENT : Intent.ACTION_OPEN_DOCUMENT);
+                intent.addCategory(Intent.CATEGORY_OPENABLE);
+                intent.setType(export ? "text/plain" : "*/*");
+                if (export) {
+                    pendingLayoutExport = configuration;
+                    intent.putExtra(Intent.EXTRA_TITLE, "halo-touch-layout.halolayout");
+                }
+                try {
+                    startActivityForResult(intent, export ? EXPORT_LAYOUT : IMPORT_LAYOUT);
+                } catch (android.content.ActivityNotFoundException e) {
+                    pendingLayoutExport = null;
+                    Toast.makeText(this, "This device has no file picker.", Toast.LENGTH_LONG).show();
+                }
+            })
+            .show();
+    }
+
+    @Override
+    protected void onSaveInstanceState(Bundle state) {
+        super.onSaveInstanceState(state);
+        state.putString("pending-layout-export", pendingLayoutExport);
+    }
+
+    @Override
+    protected void onActivityResult(int request, int result, Intent data) {
+        if (request != EXPORT_LAYOUT && request != IMPORT_LAYOUT) {
+            super.onActivityResult(request, result, data);
+            return;
+        }
+        String exported = pendingLayoutExport;
+        pendingLayoutExport = null;
+        if (result != RESULT_OK || data == null || data.getData() == null)
+            return;
+        Uri document = data.getData();
+        // (the file is read and written away from the UI thread)
+        new Thread(() -> {
+            try {
+                if (request == EXPORT_LAYOUT)
+                    writeLayoutFile(document, exported);
+                else
+                    readLayoutFile(document);
+            } catch (Exception e) {
+                runOnUiThread(() -> layoutFileError(e));
+            }
+        }, "halo-touch-layout-file").start();
+    }
+
+    private void writeLayoutFile(Uri document, String configuration) throws IOException {
+        if (configuration == null)
+            throw new IOException("the layout to export is gone");
+        try (OutputStream output = getContentResolver().openOutputStream(document, "wt")) {
+            if (output == null)
+                throw new IOException("the file cannot be opened");
+            output.write(configuration.getBytes(StandardCharsets.UTF_8));
+        }
+        runOnUiThread(() -> Toast.makeText(this, "The layout is exported.", Toast.LENGTH_SHORT).show());
+    }
+
+    private void readLayoutFile(Uri document) throws IOException {
+        ByteArrayOutputStream contents = new ByteArrayOutputStream();
+        try (InputStream input = getContentResolver().openInputStream(document)) {
+            if (input == null)
+                throw new IOException("the file cannot be opened");
+            byte[] buffer = new byte[4096];
+            int size;
+            while ((size = input.read(buffer)) != -1) {
+                if (contents.size() + size > 65536)
+                    throw new IOException("the file is too large");
+                contents.write(buffer, 0, size);
+            }
+        }
+        String configuration = new String(contents.toByteArray(), StandardCharsets.UTF_8);
+        // checked here, then applied to the overlay at once
+        TouchLayout.importConfiguration(configuration);
+        runOnUiThread(() -> {
+            if (isFinishing() || isDestroyed() || touchControls == null)
+                return;
+            try {
+                touchControls.importLayout(configuration);
+                Toast.makeText(this, "The layout is imported and saved.", Toast.LENGTH_SHORT).show();
+            } catch (IllegalArgumentException e) {
+                layoutFileError(e);
+            }
+        });
+    }
+
+    private void layoutFileError(Exception error) {
+        if (isFinishing() || isDestroyed())
+            return;
+        new AlertDialog.Builder(this)
+            .setTitle("Touch layout file")
+            .setMessage("The operation did not complete: " + error.getMessage())
+            .setPositiveButton("OK", null)
+            .show();
+    }
+
+    @Override
+    protected void onResume() {
+        super.onResume();
+        if (touchControls != null && getWindow().getDecorView().hasWindowFocus())
+            touchControls.startDeviceInput();
+    }
+
+    @Override
+    protected void onPause() {
+        if (touchControls != null)
+            touchControls.stopDeviceInput();
+        super.onPause();
+    }
+
+    @Override
+    public void onWindowFocusChanged(boolean hasFocus) {
+        if (touchControls != null) {
+            if (hasFocus)
+                touchControls.startDeviceInput();
+            else
+                touchControls.stopDeviceInput();
+        }
+        super.onWindowFocusChanged(hasFocus);
+    }
+
    @Override
    protected void onDestroy() {
+        if (touchControls != null)
+            touchControls.stopDeviceInput();
        if (multicastLock != null && multicastLock.isHeld())
            multicastLock.release();
        multicastLock = null;
        super.onDestroy();
    }

+    /**
+     * keeps gestureInsets current; Android sends the insets again when the
+     * activity rotates (after the game's native code has started on a phone
+     * launched from portrait), so a single read at startup would keep the
+     * portrait values; the listener hands the insets on so SDL's own
+     * handling still sees them
+     */
+    private void trackGestureInsets() {
+        getWindow().getDecorView().setOnApplyWindowInsetsListener(new View.OnApplyWindowInsetsListener() {
+            @Override
+            public WindowInsets onApplyWindowInsets(View view, WindowInsets insets) {
+                gestureInsets = readGestureInsets(insets);
+                return view.onApplyWindowInsets(insets);
+            }
+        });
+    }
+
+    @SuppressWarnings("deprecation") // getSystemGestureInsets is the only call on Android 10
+    private static int[] readGestureInsets(WindowInsets insets) {
+        Insets gesture;
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R)
+            gesture = insets.getInsets(WindowInsets.Type.systemGestures());
+        else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q)
+            gesture = insets.getSystemGestureInsets();
+        else
+            return new int[] { 0, 0, 0, 0 };
+        return new int[] { gesture.left, gesture.top, gesture.right, gesture.bottom };
+    }
+
+    /**
+     * the edges of the screen where Android keeps its gestures; in sticky
+     * full screen the first swipe from an edge only shows the system bars,
+     * and Android hands that swipe to the game as an ordinary finger, so
+     * the game (port/linux/src/touch_input.c) must ignore touches that
+     * begin there; returns a copy of {left, top, right, bottom} in pixels:
+     * all 0 before Android 10 (which has no insets) and until the first
+     * insets arrive. The game's native code calls this through JNI by name
+     * and signature (host_main.c GetMethodID(...,
+     * "getSystemGestureInsetsPixels", "()[I")), at every finger down, so
+     * it must not be renamed, retyped or removed as unused
+     */
+    public int[] getSystemGestureInsetsPixels() {
+        return gestureInsets.clone();
+    }
+
    /**
     * Many phones drop the Wi-Fi's broadcast and multicast datagrams to
     * save power unless an app holds this: without it they would not see
@@ -27,7 +27,7 @@ import java.nio.channels.FileChannel;
 * Starts the game once its data is in place.
 *
 * The game reads the Xbox game data (the folder holding maps/) from the
- * app's external files directory, /sdcard/Android/data/com.halo.decomp/files.
+ * app's external files directory, /sdcard/Android/data/<application id>/files.
 * If it is missing, this screen lets the player pick an Xbox disc image of
 * the game (.xiso or .iso, any version) with the system file picker, and
 * copies its maps folder there (XisoExtractor), as the desktop games do; or
@@ -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/RingfallMjolnirVR";

    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)
@@ -135,15 +147,15 @@ public class LauncherActivity extends Activity {
        layout.setBackgroundColor(Color.rgb(12, 16, 20));

        TextView title = new TextView(this);
-        title.setText("Halo needs its game data");
+        title.setText("Ringfall: Mjolnir VR needs game data");
        title.setTextColor(Color.WHITE);
        title.setTextSize(TypedValue.COMPLEX_UNIT_SP, 24);
        title.setGravity(Gravity.CENTER);
        layout.addView(title);

        TextView message = new TextView(this);
-        message.setText("Choose an Xbox disc image of Halo: Combat Evolved (an .iso or .xiso file, any "
-            + "version) on this device. Its maps folder is copied into the app's storage (about 1.8 GB), "
+        message.setText("Choose your own disc image of Halo: Combat Evolved for the original Xbox (an .iso or "
+            + ".xiso file, any version) on this device. Its maps folder is copied into the app's storage (about 1.8 GB), "
            + "and you can delete the image afterwards.\n\n"
            + "You can also copy a maps folder from a computer:\n"
            + "adb push <folder with maps>/. " + (dataRoot != null ? dataRoot.getAbsolutePath() : "") + "/");
@@ -0,0 +1,335 @@
+package com.halo.decomp;
+
+import java.io.IOException;
+import java.io.StringReader;
+import java.io.StringWriter;
+import java.util.ArrayList;
+import java.util.Properties;
+
+/**
+ * The touch controls' layout (TouchControls): each control's kind, place,
+ * size and whether it shows, with the settings that go with them, in the
+ * overlay's logical units. Places are kept for the display the layout is
+ * on and saved on a 960 x 540 grid, so a layout moves between displays of
+ * other shapes. A layout file is Java properties text (version 3; 1 and 2
+ * are still read).
+ */
+final class TouchLayout {
+    /** the kinds of control: a button of TouchControls's list, by index */
+    static final int LEFT = 16;
+    static final int FIRE_LEFT = 17;
+    static final int BASE_COUNT = 18;
+    static final int MAX_CONTROLS = 64;
+    static final float MIN_SIZE = 0.5f;
+    static final float MAX_SIZE = 2f;
+    static final float MIN_OPACITY = 0.2f;
+    static final float MAX_OPACITY = 1f;
+    static final float MIN_SENSITIVITY = 0.25f;
+    static final float MAX_SENSITIVITY = 4f;
+    /**
+     * the largest minimum radius: a finger's width is capped here on a small,
+     * dense display, where the D-pad's buttons (69 apart) would overlap
+     */
+    static final float MAX_MINIMUM_RADIUS = 34;
+
+    /** the saved grid */
+    private static final float GRID_WIDTH = 960;
+    private static final float GRID_HEIGHT = 540;
+    private static final int VERSION = 3;
+    private static final int MAX_FILE_LENGTH = 65536;
+
+    /** each kind's default place on the grid, and its radius */
+    private static final float[][] DEFAULTS = {
+        {856, 447}, {913, 377}, {794, 377}, {850, 312}, {915, 239}, {802, 239},
+        {236, 449}, {691, 449}, {360, 490}, {438, 490}, {570, 36}, {390, 36},
+        {100, 237}, {100, 335}, {51, 286}, {149, 286}, {115, 440}, {255, 239}
+    };
+    private static final float[] RADII = {
+        36, 32, 34, 32, 39, 35, 32, 32, 27, 29, 28, 28, 25, 25, 25, 25, 64, 39
+    };
+
+    private static final class Control {
+        final int type;
+        float x;
+        float y;
+        boolean shown = true;
+        float size = 1f;
+
+        Control(int type, float x, float y) {
+            this.type = type;
+            this.x = x;
+            this.y = y;
+        }
+    }
+
+    /** a layout and the sensitivity saved with it */
+    static final class Configuration {
+        final TouchLayout layout;
+        final float sensitivity;
+
+        Configuration(TouchLayout layout, float sensitivity) {
+            this.layout = layout;
+            this.sensitivity = sensitivity;
+        }
+    }
+
+    private final ArrayList<Control> controls = new ArrayList<>();
+    private float width = GRID_WIDTH;
+    private float height = GRID_HEIGHT;
+    /** the smallest radius a control is drawn and touched at, in logical units */
+    private float minimumRadius;
+
+    boolean rumbleEnabled = true;
+    boolean gyroscopeEnabled = false;
+    /** how solid the controls are drawn, MIN_OPACITY..MAX_OPACITY */
+    float opacity = 1f;
+    /** the move stick goes where the thumb lands in the lower left, not at its place */
+    boolean floatingStick = false;
+
+    TouchLayout() {
+        resetDefaults();
+    }
+
+    /** places the layout on a display of this size, in logical units */
+    void bounds(float width, float height) {
+        if (!Float.isFinite(width) || !Float.isFinite(height) || width <= 0 || height <= 0)
+            throw new IllegalArgumentException("Invalid display dimensions");
+        for (Control control : controls) {
+            control.x *= width / this.width;
+            control.y *= height / this.height;
+        }
+        this.width = width;
+        this.height = height;
+        keepAllInside();
+    }
+
+    /**
+     * the smallest radius, in logical units, at which a control is drawn and
+     * touched (a finger's width, whatever the display's density), at most
+     * MAX_MINIMUM_RADIUS
+     */
+    void setMinimumRadius(float radius) {
+        minimumRadius = Float.isFinite(radius) && radius > 0 ? Math.min(radius, MAX_MINIMUM_RADIUS) : 0;
+        keepAllInside();
+    }
+
+    int size() {
+        return controls.size();
+    }
+
+    int type(int control) {
+        return controls.get(control).type;
+    }
+
+    float x(int control) {
+        return controls.get(control).x;
+    }
+
+    float y(int control) {
+        return controls.get(control).y;
+    }
+
+    float savedX(int control) {
+        return x(control) * GRID_WIDTH / width;
+    }
+
+    float savedY(int control) {
+        return y(control) * GRID_HEIGHT / height;
+    }
+
+    float radius(int control) {
+        return Math.max(RADII[type(control)] * sizeScale(control), minimumRadius);
+    }
+
+    float sizeScale(int control) {
+        return controls.get(control).size;
+    }
+
+    void setSize(int control, float size) {
+        if (!Float.isFinite(size) || size < MIN_SIZE || size > MAX_SIZE)
+            throw new IllegalArgumentException("Button size must be between 50% and 200%");
+        controls.get(control).size = size;
+        move(control, x(control), y(control));
+    }
+
+    boolean shown(int control) {
+        return controls.get(control).shown;
+    }
+
+    void setShown(int control, boolean shown) {
+        controls.get(control).shown = shown;
+    }
+
+    void setOpacity(float opacity) {
+        if (!validOpacity(opacity))
+            throw new IllegalArgumentException("Opacity must be between 20% and 100%");
+        this.opacity = opacity;
+    }
+
+    /** the default controls, at their default places, sizes and visibility */
+    void resetDefaults() {
+        controls.clear();
+        for (int i = 0; i < DEFAULTS.length; i++)
+            controls.add(new Control(i, DEFAULTS[i][0] * width / GRID_WIDTH, DEFAULTS[i][1] * height / GRID_HEIGHT));
+        keepAllInside();
+    }
+
+    /** adds a copy of a control beside it; -1 if there may be no more (or it is the stick) */
+    int duplicate(int source) {
+        if (size() >= MAX_CONTROLS || type(source) == LEFT)
+            return -1;
+        float offset = radius(source) * 2 + 12;
+        Control added = new Control(type(source), x(source) + offset, y(source));
+        added.size = sizeScale(source);
+        controls.add(added);
+        int index = size() - 1;
+        // where there is no room to the right, the copy goes to the left
+        if (added.x > width - radius(index))
+            added.x = x(source) - offset;
+        move(index, added.x, added.y);
+        return index;
+    }
+
+    /** shows a hidden control of this kind, or else adds a copy; -1 if neither can be */
+    int add(int type) {
+        if (type < 0 || type >= BASE_COUNT)
+            return -1;
+        for (int i = 0; i < size(); i++) {
+            if (type(i) == type && !shown(i)) {
+                setShown(i, true);
+                return i;
+            }
+        }
+        return duplicate(type);
+    }
+
+    /** moves a control, keeping all of it on the display */
+    void move(int control, float x, float y) {
+        if (!Float.isFinite(x) || !Float.isFinite(y))
+            return;
+        float radius = radius(control);
+        controls.get(control).x = Math.max(radius, Math.min(width - radius, x));
+        controls.get(control).y = Math.max(radius, Math.min(height - radius, y));
+    }
+
+    /** puts a control at a saved place on the grid, if it is a valid one */
+    void restore(int control, float x, float y) {
+        if (Float.isFinite(x) && Float.isFinite(y) && x >= 0 && x <= GRID_WIDTH && y >= 0 && y <= GRID_HEIGHT) {
+            controls.get(control).x = x;
+            controls.get(control).y = y;
+        }
+    }
+
+    private void keepAllInside() {
+        for (int i = 0; i < size(); i++)
+            move(i, x(i), y(i));
+    }
+
+    /** the layout as a layout file's text, with the look sensitivity */
+    String exportConfiguration(float sensitivity) {
+        if (!validSensitivity(sensitivity))
+            throw new IllegalArgumentException("Invalid sensitivity");
+        Properties values = new Properties();
+        values.setProperty("format", "halo-touch-layout");
+        values.setProperty("version", Integer.toString(VERSION));
+        values.setProperty("rumble", Boolean.toString(rumbleEnabled));
+        values.setProperty("gyroscope", Boolean.toString(gyroscopeEnabled));
+        values.setProperty("opacity", Float.toString(opacity));
+        values.setProperty("floating-stick", Boolean.toString(floatingStick));
+        values.setProperty("count", Integer.toString(size()));
+        values.setProperty("sensitivity", Float.toString(sensitivity));
+        for (int i = 0; i < size(); i++) {
+            String key = "control." + i + ".";
+            values.setProperty(key + "type", Integer.toString(type(i)));
+            values.setProperty(key + "x", Float.toString(savedX(i)));
+            values.setProperty(key + "y", Float.toString(savedY(i)));
+            values.setProperty(key + "visible", Boolean.toString(shown(i)));
+            values.setProperty(key + "size", Float.toString(sizeScale(i)));
+        }
+        StringWriter text = new StringWriter();
+        try {
+            values.store(text, "Halo Android touch layout");
+        } catch (IOException e) {
+            throw new IllegalStateException(e);
+        }
+        return text.toString();
+    }
+
+    /** reads a layout file's text; throws IllegalArgumentException for anything not valid */
+    static Configuration importConfiguration(String text) {
+        if (text == null || text.length() > MAX_FILE_LENGTH)
+            throw new IllegalArgumentException("Invalid layout file");
+        Properties values = new Properties();
+        try {
+            values.load(new StringReader(text));
+            int version = readVersion(values);
+            int count = Integer.parseInt(values.getProperty("count"));
+            float sensitivity = Float.parseFloat(values.getProperty("sensitivity"));
+            if (count < BASE_COUNT || count > MAX_CONTROLS || !validSensitivity(sensitivity))
+                throw new IllegalArgumentException("Invalid layout settings");
+            TouchLayout layout = new TouchLayout();
+            layout.controls.clear();
+            if (version >= 2) {
+                layout.rumbleEnabled = readBoolean(values, "rumble");
+                layout.gyroscopeEnabled = readBoolean(values, "gyroscope");
+            }
+            if (version >= 3) {
+                float opacity = Float.parseFloat(values.getProperty("opacity"));
+                if (!validOpacity(opacity))
+                    throw new IllegalArgumentException("Invalid opacity");
+                layout.opacity = opacity;
+                layout.floatingStick = readBoolean(values, "floating-stick");
+            }
+            for (int i = 0; i < count; i++)
+                layout.controls.add(readControl(values, i, version));
+            return new Configuration(layout, sensitivity);
+        } catch (IOException | NullPointerException e) {
+            throw new IllegalArgumentException("Incomplete layout file", e);
+        }
+    }
+
+    private static int readVersion(Properties values) {
+        if (!"halo-touch-layout".equals(values.getProperty("format")))
+            throw new IllegalArgumentException("Unsupported layout file");
+        String version = values.getProperty("version");
+        for (int known = 1; known <= VERSION; known++) {
+            if (Integer.toString(known).equals(version))
+                return known;
+        }
+        throw new IllegalArgumentException("Unsupported layout file");
+    }
+
+    private static Control readControl(Properties values, int index, int version) {
+        String key = "control." + index + ".";
+        int type = Integer.parseInt(values.getProperty(key + "type"));
+        float x = Float.parseFloat(values.getProperty(key + "x"));
+        float y = Float.parseFloat(values.getProperty(key + "y"));
+        String shown = values.getProperty(key + "visible");
+        float size = version >= 2 ? Float.parseFloat(values.getProperty(key + "size")) : 1f;
+        boolean validType = type >= 0 && type < BASE_COUNT && (index >= BASE_COUNT ? type != LEFT : type == index);
+        boolean validPlace = Float.isFinite(x) && Float.isFinite(y) && x >= 0 && x <= GRID_WIDTH
+            && y >= 0 && y <= GRID_HEIGHT;
+        boolean validSize = Float.isFinite(size) && size >= MIN_SIZE && size <= MAX_SIZE;
+        if (!validType || !validPlace || !validSize || !("true".equals(shown) || "false".equals(shown)))
+            throw new IllegalArgumentException("Invalid control in layout file");
+        Control control = new Control(type, x, y);
+        control.shown = Boolean.parseBoolean(shown);
+        control.size = size;
+        return control;
+    }
+
+    private static boolean readBoolean(Properties values, String key) {
+        String value = values.getProperty(key);
+        if (!("true".equals(value) || "false".equals(value)))
+            throw new IllegalArgumentException("Invalid " + key + " option");
+        return Boolean.parseBoolean(value);
+    }
+
+    static boolean validSensitivity(float value) {
+        return Float.isFinite(value) && value >= MIN_SENSITIVITY && value <= MAX_SENSITIVITY;
+    }
+
+    static boolean validOpacity(float value) {
+        return Float.isFinite(value) && value >= MIN_OPACITY && value <= MAX_OPACITY;
+    }
+}
@@ -13,13 +13,13 @@ import java.io.FileNotFoundException;

 /**
 * Hands Android's package installer the downloaded new version of the app
- * (Updater), read-only, the one file content://com.halo.decomp.update/halo.apk.
+ * (Updater), read-only, the one file content://<application id>.update/update.apk.
 * (The app has no AndroidX, whose FileProvider does the same.)
 */
 public class UpdateProvider extends ContentProvider {
-    static final String AUTHORITY = "com.halo.decomp.update";
+    static final String AUTHORITY = BuildConfig.APPLICATION_ID + ".update";
    static final String DIRECTORY = "update";
-    static final String APK = "halo.apk";
+    static final String APK = "update.apk";

    private File apk() {
        return new File(new File(getContext().getCacheDir(), DIRECTORY), APK);
@@ -49,9 +49,12 @@ import java.util.zip.ZipInputStream;
 final class Updater {
    /* the VR port's own releases: the original's, made without VR, must
       never replace it (they share the package name) */
-    private static final String REPOSITORY = "Cesarus85/halo-ce-vr";
+    private static final String APP_NAME = "Ringfall: Mjolnir VR";
+    private static final String REPOSITORY = "Cesarus85/ringfall-mjolnir-vr";
    private static final String USER_AGENT = "halo-ce-universal-updater";
    private static final int TIMEOUT_MILLISECONDS = 20000;
+    /** the most a download (a release's zip, about 35 MB) or the app in it may be */
+    private static final long MAXIMUM_UPDATE_SIZE = 256L * 1024 * 1024;

    private Updater() {
    }
@@ -202,8 +205,8 @@ final class Updater {
        if (activity.isFinishing())
            return;
        new AlertDialog.Builder(activity)
-            .setTitle("Halo: new version")
-            .setMessage("A new version of Halo was detected (build " + latest + "; this is build "
+            .setTitle(APP_NAME + ": new version")
+            .setMessage("A new version of " + APP_NAME + " was detected (build " + latest + "; this is build "
                + BuildConfig.HALO_BUILD_NUMBER + ").\n\nDo you want to update? The game will close and start "
                + "the new version.")
            .setCancelable(false)
@@ -215,7 +218,7 @@ final class Updater {

    private static void confirmNever(Activity activity) {
        new AlertDialog.Builder(activity)
-            .setTitle("Halo: new version")
+            .setTitle(APP_NAME + ": new version")
            .setMessage("Stop asking about new versions?\n\nTo ask again, set auto = true in the [update] section "
                + "of config.toml.")
            .setCancelable(false)
@@ -232,7 +235,7 @@ final class Updater {
    /* ---------- updating */

    private static void update(Activity activity, int latest) {
-        String asset = "halo-android-" + (BuildConfig.DEBUG ? "debug" : "release") + ".zip";
+        String asset = "ringfall-mjolnir-vr-android-" + (BuildConfig.DEBUG ? "debug" : "release") + ".zip";
        File directory = new File(activity.getCacheDir(), UpdateProvider.DIRECTORY);
        LinearLayout layout = new LinearLayout(activity);
        TextView status = new TextView(activity);
@@ -247,7 +250,7 @@ final class Updater {
        layout.addView(status);
        layout.addView(bar);
        AlertDialog progress = new AlertDialog.Builder(activity)
-            .setTitle("Halo: new version")
+            .setTitle(APP_NAME + ": new version")
            .setView(layout)
            .setCancelable(false)
            .show();
@@ -275,7 +278,7 @@ final class Updater {
                activity.runOnUiThread(() -> {
                    progress.dismiss();
                    new AlertDialog.Builder(activity)
-                        .setTitle("Halo: new version")
+                        .setTitle(APP_NAME + ": new version")
                        .setMessage("The update failed:\n\n" + e.getMessage())
                        .setPositiveButton("OK", null)
                        .show();
@@ -304,8 +307,10 @@ final class Updater {
                int count;

                while ((count = in.read(buffer)) > 0) {
-                    out.write(buffer, 0, count);
                    received += count;
+                    if (received > MAXIMUM_UPDATE_SIZE)
+                        throw new IOException("the download is larger than expected");
+                    out.write(buffer, 0, count);
                    if (received - reported >= 256 * 1024 || received == total) {
                        progress.report(received, total);
                        reported = received;
@@ -329,10 +334,15 @@ final class Updater {
                    continue;
                try (OutputStream out = new FileOutputStream(apk)) {
                    byte[] buffer = new byte[65536];
+                    long written = 0;
                    int count;

-                    while ((count = in.read(buffer)) > 0)
+                    while ((count = in.read(buffer)) > 0) {
+                        written += count;
+                        if (written > MAXIMUM_UPDATE_SIZE)
+                            throw new IOException("the app in the download is larger than expected");
                        out.write(buffer, 0, count);
+                    }
                }
                return;
            }
@@ -135,6 +135,20 @@ final class XisoExtractor {
        return true;
    }

+    /** whether a name is one to write in the maps folder: no path, no "." or
+     * "..", and only printable ASCII that every file system takes as a plain
+     * name (a disc's maps folder holds .map files and loading.tga) */
+    static boolean isPlainName(String name) {
+        if (name.isEmpty() || name.equals(".") || name.equals(".."))
+            return false;
+        for (int index = 0; index < name.length(); index++) {
+            char c = name.charAt(index);
+            if (c < 0x20 || c > 0x7E || "/\\:*?\"<>|".indexOf(c) >= 0)
+                return false;
+        }
+        return true;
+    }
+
    /** the partition's volume descriptor: the root directory's sector and size */
    private long[] findVolume() throws IOException {
        for (long offset : PARTITION_OFFSETS) {
@@ -190,8 +204,9 @@ final class XisoExtractor {
            for (int index = 0; index < nameLength; index++)
                bytes[index] = table.get(at + ENTRY_HEADER_SIZE + index);
            String name = new String(bytes, StandardCharsets.ISO_8859_1);
-            /* (as extract-xiso refuses them: no name may leave the folder) */
-            if (!name.equals(".") && !name.equals("..") && name.indexOf('/') < 0 && name.indexOf('\\') < 0)
+            /* (as extract-xiso refuses them: no name may leave the folder, and
+            none but a plain file name is written) */
+            if (isPlainName(name))
                out.add(new Entry(name, table.getInt(at + 4) & 0xFFFFFFFFL, table.getInt(at + 8) & 0xFFFFFFFFL));
        }
        if (right != 0)
@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <string name="app_name">Halo</string>
+    <string name="app_name">Ringfall: Mjolnir VR</string>
 </resources>
@@ -46,6 +46,8 @@ unsigned int host_memory_watch_generation(unsigned int address, unsigned int siz
 unsigned int host_memory_watch_serial(void);
 void host_memory_watch_prepare_write(unsigned int address, unsigned int size);
 void host_memory_watch_forget(unsigned int address, unsigned int size);
+/* memory_watch_begin_frame (port/linux/src/platform.h) */
+void host_memory_watch_begin_frame(void);

 /* ---------- SDL (guest/runtime/guest_sdl.c)

@@ -68,6 +70,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);
@@ -77,11 +82,16 @@ int host_sdl_gamepad_axis(unsigned int gamepad, int axis);
 int host_sdl_gamepad_button(unsigned int gamepad, int button);
 int host_sdl_gamepad_type(unsigned int gamepad);
 int host_sdl_rumble_gamepad(unsigned int gamepad, unsigned int low, unsigned int high, unsigned int milliseconds);
+void host_sdl_close_gamepad(unsigned int gamepad);
 /* callback: void (*)(void *userdata, unsigned int stream, int additional, int total),
 called on the audio thread */
 unsigned int host_sdl_open_audio_stream(unsigned int device, const void *spec, unsigned int callback, unsigned int userdata);
 int host_sdl_put_audio_stream_data(unsigned int stream, const void *data, int length);
 int host_sdl_resume_audio_stream_device(unsigned int stream);
+/* (voice chat's microphone, a stream without a callback) */
+int host_sdl_get_audio_stream_data(unsigned int stream, void *data, int length);
+int host_sdl_get_audio_stream_available(unsigned int stream);
+void host_sdl_destroy_audio_stream(unsigned int stream);

 /* ---------- OpenGL ES */

@@ -89,8 +99,9 @@ int host_sdl_resume_audio_stream_device(unsigned int stream);
 void host_gl_get_string(unsigned int name, int index, char *buffer, unsigned int size);
 /* nonzero if the context supports the named extension */
 int host_gl_has_extension(const char *name);
-/* a 32-bit word of a GL buffer object, waiting for the GPU */
-unsigned int host_gl_read_buffer_word(unsigned int buffer, unsigned int offset);
+/* copies size bytes at offset of a GL buffer object into data, waiting for
+the GPU's writes to it */
+void host_gl_read_buffer(unsigned int buffer, unsigned int offset, unsigned int size, void *data);
 /* unsynchronized write into the buffer bound to target */
 void host_gl_buffer_write(unsigned int target, unsigned int offset, unsigned int size, const void *data);
 /* persistent, coherent storage for the buffer bound to target (0: the driver
@@ -116,7 +127,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,10 +143,35 @@ 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 */

 /* the storage directories the port uses, copied into buffer */
 void host_android_path(int which, char *buffer, unsigned int size);

+/* the edges where Android keeps its gestures, as left, top, right, bottom
+in pixels of the current orientation, into insets[4]; all 0 when unknown */
+void host_gesture_insets(int *insets);
+
+/* ---------- the on-screen touch controls (host_touch.c) */
+
+/* the overlay's controller: the SDL axes (left x, y, right x, y, left
+trigger, right trigger) and the SDL button bits, into state[7] */
+void host_touch_read(int *state);
+/* the overlay's view swipe, then its gyroscope turn, since the last read,
+into delta[4] */
+void host_touch_look_read(float *delta);
+/* port 0's motors, for the phone's vibration */
+void host_touch_rumble(unsigned int low, unsigned int high);
+/* tells the overlay when to show: touch_input.c's _touch_scene_* */
+void host_touch_scene(int scene);
+/* the game control on each of the 16 controller buttons (touch_game.c),
+for the overlay's labels */
+void host_touch_bindings(const int *controls);
+
 #endif
@@ -39,3 +39,8 @@ void memory_watch_forget(void *address, unsigned long size)
 {
 	host_memory_watch_forget((unsigned int)address, size);
 }
+
+void memory_watch_begin_frame(void)
+{
+	host_memory_watch_begin_frame();
+}
@@ -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();
@@ -203,6 +216,11 @@ bool SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low, Uint16 high, Uint32 mil
 	return host_sdl_rumble_gamepad((unsigned int)gamepad, low, high, milliseconds) != 0;
 }

+void SDL_CloseGamepad(SDL_Gamepad *gamepad)
+{
+	host_sdl_close_gamepad((unsigned int)gamepad);
+}
+
 /* ---------- audio */

 SDL_AudioStream *SDL_OpenAudioDeviceStream(SDL_AudioDeviceID device, const SDL_AudioSpec *spec,
@@ -221,3 +239,18 @@ bool SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream)
 {
 	return host_sdl_resume_audio_stream_device((unsigned int)stream) != 0;
 }
+
+int SDL_GetAudioStreamData(SDL_AudioStream *stream, void *data, int length)
+{
+	return host_sdl_get_audio_stream_data((unsigned int)stream, data, length);
+}
+
+int SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
+{
+	return host_sdl_get_audio_stream_available((unsigned int)stream);
+}
+
+void SDL_DestroyAudioStream(SDL_AudioStream *stream)
+{
+	host_sdl_destroy_audio_stream((unsigned int)stream);
+}
@@ -25,6 +25,7 @@ extern void (*__guest_init_end[])(void);
 void __guest_start(const struct halo_guest_boot *boot);
 void __guest_thread_start(unsigned int thread);
 unsigned int __guest_thread_attach(void);
+void __guest_thread_detach(void);
 void __guest_thread_initialize_main(void);

 extern char **__environ;
@@ -41,6 +42,7 @@ const struct halo_guest_header __guest_header =
 	(uint32_t)__guest_start,
 	(uint32_t)__guest_thread_start,
 	(uint32_t)__guest_thread_attach,
+	(uint32_t)__guest_thread_detach,
 	(uint32_t)__guest_init_start,
 	(uint32_t)__guest_init_end,
 };
@@ -0,0 +1,37 @@
+/*
+GUEST_STRING.C
+
+String functions faster than musl's generic C ones, which the guest takes
+in their place (tools/android_build.py MUSL_EXCLUDE). The renderer's state
+caches compare their keys with memcmp on every draw (the pixel shaders'
+keys, the vertex constants, the uniforms), and musl's compares a byte at a
+time.
+*/
+
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+/* eight bytes at a time while they match (AArch64 loads them unaligned),
+then the bytes that differ, or the tail. no_builtin: clang would turn the
+loops back into a call to memcmp */
+__attribute__((no_builtin)) int memcmp(const void *left, const void *right, size_t size)
+{
+	const unsigned char *l = left, *r = right;
+
+	for (; size >= 8; size -= 8, l += 8, r += 8)
+	{
+		uint64_t a, b;
+
+		__builtin_memcpy(&a, l, 8);
+		__builtin_memcpy(&b, r, 8);
+		if (a != b)
+			break;
+	}
+	for (; size; size--, l++, r++)
+	{
+		if (*l != *r)
+			return *l - *r;
+	}
+	return 0;
+}
@@ -125,6 +125,18 @@ unsigned int __guest_thread_attach(void)
 	return (unsigned int)thread;
 }

+/* a host thread that ran guest code (__guest_thread_attach) is ending:
+its struct pthread goes */
+void __guest_thread_detach(void)
+{
+	struct guest_thread *thread = (struct guest_thread *)host_get_tp();
+
+	if (!thread || thread == &main_thread)
+		return;
+	host_set_tp(0);
+	thread_free(thread);
+}
+
 int pthread_create(pthread_t *restrict result, const pthread_attr_t *restrict attributes,
 	void *(*start)(void *), void *restrict argument)
 {
@@ -37,6 +37,10 @@ mappings) from pools of address space it reserves below 4 GB on demand. */

 /* reserves the fixed ranges; returns 0 on success */
 int host_memory_initialize(uint32_t image_base, uint32_t image_size);
+/* Makes the write tracking compare page contents instead of catching page
+faults (host_watch_hash.h), for when the app cannot receive its own
+SIGSEGV (ARM translation). Call before the guest starts. */
+void host_memory_watch_use_hashes(void);
 /* page-granular allocations below 4 GB; NULL on failure */
 void *host_low_map(size_t size, int protection);
 void host_low_unmap(void *address, size_t size);
@@ -92,6 +96,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)
 {
@@ -57,25 +101,26 @@ int host_gl_has_extension(const char *name)
 	return 0;
 }

-/* one 32-bit word of a buffer object (the visibility test counters of
-d3d8_gl.c); ES has no glGetBufferSubData, and the mapping it offers
-instead is a host pointer */
-uint32_t host_gl_read_buffer_word(uint32_t buffer, uint32_t offset)
+/* copies size bytes of a buffer object (the snapshots of the visibility
+tests' counters, d3d8_gl.c); ES has no glGetBufferSubData, and the mapping
+it offers instead is a host pointer. Binds GL_COPY_READ_BUFFER, which the
+renderer uses only for its copies, and leaves it unbound. */
+void host_gl_read_buffer(uint32_t buffer, uint32_t offset, uint32_t size, void *data)
 {
-	uint32_t value = 0;
-	GLint previous = 0;
 	const void *mapping;

-	glGetIntegerv(GL_ATOMIC_COUNTER_BUFFER_BINDING, &previous);
-	glBindBuffer(GL_ATOMIC_COUNTER_BUFFER, buffer);
-	mapping = glMapBufferRange(GL_ATOMIC_COUNTER_BUFFER, offset, sizeof(value), GL_MAP_READ_BIT);
+	glBindBuffer(GL_COPY_READ_BUFFER, buffer);
+	mapping = glMapBufferRange(GL_COPY_READ_BUFFER, offset, size, GL_MAP_READ_BIT);
 	if (mapping)
 	{
-		memcpy(&value, mapping, sizeof(value));
-		glUnmapBuffer(GL_ATOMIC_COUNTER_BUFFER);
+		memcpy(data, mapping, size);
+		glUnmapBuffer(GL_COPY_READ_BUFFER);
 	}
-	glBindBuffer(GL_ATOMIC_COUNTER_BUFFER, (GLuint)previous);
-	return value;
+	else
+	{
+		memset(data, 0, size);
+	}
+	glBindBuffer(GL_COPY_READ_BUFFER, 0);
 }

 /* The visibility tests' counters (d3d8_gl.c), copied at the end of each
@@ -88,14 +133,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 +152,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 +170,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;
 }

@@ -25,12 +25,14 @@ that runs here.
 #include <SDL3/SDL.h>
 #include <SDL3/SDL_main.h>
 #include <android/log.h>
+#include <jni.h>
 #include <errno.h>
 #include <ftw.h>
 #include <stdarg.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#include <sys/system_properties.h>
 #include <sys/mman.h>
 #include <sys/stat.h>
 #include <time.h>
@@ -63,7 +65,7 @@ void host_fatal(const char *format, ...)
 	vsnprintf(message, sizeof(message), format, arguments);
 	va_end(arguments);
 	__android_log_write(ANDROID_LOG_FATAL, "halo", message);
-	SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, "Halo", message, NULL);
+	SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, "Ringfall: Mjolnir VR", message, NULL);
 	_exit(1);
 }

@@ -90,6 +92,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/RingfallMjolnirVR"

 void host_android_path(int which, char *buffer, uint32_t size)
 {
@@ -135,6 +139,52 @@ struct environment
 	int count;
 };

+/* asks the activity for Android's system gesture insets via JNI
+(HaloActivity.getSystemGestureInsetsPixels); the guest calls it at every
+finger down because the insets change when the phone rotates; the method is
+found on the activity's own class because the game's native thread has the
+system's class loader, which does not know the app's classes; a change is
+logged so the log shows the value the game works with; all 0 on any failure
+(the touch controls then use the whole screen) */
+void host_gesture_insets(int *insets)
+{
+	static int logged[4] = { -1, -1, -1, -1 };
+	JNIEnv *env = (JNIEnv *)SDL_GetAndroidJNIEnv();
+	jobject activity = (jobject)SDL_GetAndroidActivity();
+	jint values[4] = { 0, 0, 0, 0 };
+	int index;
+
+	if (env && activity)
+	{
+		jclass activity_class = (*env)->GetObjectClass(env, activity);
+		jmethodID method = activity_class ? (*env)->GetMethodID(env, activity_class, "getSystemGestureInsetsPixels", "()[I") : NULL;
+		jintArray array = method ? (jintArray)(*env)->CallObjectMethod(env, activity, method) : NULL;
+
+		if (array && !(*env)->ExceptionCheck(env) && (*env)->GetArrayLength(env, array) == 4)
+			(*env)->GetIntArrayRegion(env, array, 0, 4, values);
+		/* a Java exception left pending would break the next JNI call of the
+		thread, and a failed read must leave zeros */
+		if ((*env)->ExceptionCheck(env))
+		{
+			(*env)->ExceptionClear(env);
+			for (index = 0; index < 4; index++)
+				values[index] = 0;
+		}
+		if (array)
+			(*env)->DeleteLocalRef(env, array);
+		if (activity_class)
+			(*env)->DeleteLocalRef(env, activity_class);
+		(*env)->DeleteLocalRef(env, activity);
+	}
+	for (index = 0; index < 4; index++)
+		insets[index] = (int)values[index];
+	if (memcmp(logged, insets, sizeof(logged)))
+	{
+		memcpy(logged, insets, sizeof(logged));
+		host_logf(HOST_LOG_INFO, "system gesture insets %d,%d,%d,%d", insets[0], insets[1], insets[2], insets[3]);
+	}
+}
+
 static void environment_set(struct environment *environment, const char *name, const char *value)
 {
 	size_t length = strlen(name);
@@ -203,6 +253,37 @@ static double config_number(const char *path, const char *key, double fallback)
 	return value;
 }

+/* a boolean setting of config.toml (a dotted name), or otherwise when the
+file, the setting or a boolean is missing */
+static int config_boolean_or(const char *path, const char *name, int otherwise)
+{
+	toml_result_t result = toml_parse_file_ex(path);
+	int value = otherwise;
+
+	if (!result.ok)
+		return otherwise;
+	{
+		toml_datum_t datum = toml_seek(result.toptab, name);
+
+		if (datum.type == TOML_BOOLEAN)
+			value = datum.u.boolean ? 1 : 0;
+	}
+	toml_free(result);
+	return value;
+}
+
+/* Whether the app runs through an ARM translator. The x86 emulator runs the
+app's ARM code through one, which ro.dalvik.vm.native.bridge names; it
+cannot deliver the page faults of the write tracking to the app
+(host_memory.c). */
+static int native_bridge_active(void)
+{
+	char value[PROP_VALUE_MAX] = "";
+
+	__system_property_get("ro.dalvik.vm.native.bridge", value);
+	return value[0] && strcmp(value, "0") != 0;
+}
+
 /* POSIX TZ for the current local offset (the guest's musl has no zone
 database) */
 static void time_zone(char *buffer, size_t size)
@@ -255,6 +336,11 @@ static uint32_t make_boot(const struct environment *environment)

 #define MAIN_STACK_SIZE (16 * 1024 * 1024)

+/* the thread that runs the game: passes the display and its density, the
+time zone and the data and save folders to the guest through its
+environment, chooses the write tracking (page protection, or page hashes when
+translated or when debug.memory_watch is false), and runs the guest's main;
+never returns normally */
 static void *game_main(void *unused)
 {
 	struct environment environment = { { 0 }, 0 };
@@ -269,6 +355,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 */
@@ -284,7 +376,7 @@ static void *game_main(void *unused)
 	}
 	if (!directory_has_maps(data_root))
 	{
-		host_fatal("The Halo game data was not found.\n\nCopy the PAL game data (build 01.01.14.2342), "
+		host_fatal("The game data was not found.\n\nCopy the PAL game data (build 01.01.14.2342), "
 			"the folder that contains maps, into\n%s\nor import it from the launcher screen.", data_root);
 	}

@@ -293,6 +385,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 +410,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;

@@ -329,6 +454,7 @@ static void *game_main(void *unused)
 			(landscape) unless display.screen_width says otherwise (d3d8_gl.c) */
 			const SDL_DisplayMode *mode;
 			char width[16];
+			char text_density[16];

 			SDL_InitSubSystem(SDL_INIT_VIDEO);
 			mode = SDL_GetDesktopDisplayMode(SDL_GetPrimaryDisplay());
@@ -341,6 +467,18 @@ static void *game_main(void *unused)
 				environment_set(&environment, "HALO_DISPLAY_WIDTH", width);
 				host_logf(HOST_LOG_INFO, "display %dx%d: rendering %sx480", mode->w, mode->h, width);
 			}
+			{
+				/* dp for the touch controls (port/linux/src/touch_input.c): SDL
+				gives Android's densityDpi / 160 */
+				float density = SDL_GetDisplayContentScale(SDL_GetPrimaryDisplay());
+
+				if (density > 0.0f)
+				{
+					snprintf(text_density, sizeof(text_density), "%g", density);
+					environment_set(&environment, "HALO_DISPLAY_DENSITY", text_density);
+					host_logf(HOST_LOG_INFO, "display density %s", text_density);
+				}
+			}
 		}
 	}

@@ -350,6 +488,20 @@ static void *game_main(void *unused)
 		if (config_sample_seconds(path, seconds, sizeof(seconds)))
 			host_debug_start_sampler(seconds);
 	}
+	if (native_bridge_active())
+	{
+		host_memory_watch_use_hashes();
+		host_logf(HOST_LOG_INFO, "write tracking: page hashes (ARM translation)");
+	}
+	else if (!config_boolean_or(path, "debug.memory_watch", 1))
+	{
+		host_memory_watch_use_hashes();
+		host_logf(HOST_LOG_INFO, "write tracking: page hashes (debug.memory_watch = false)");
+	}
+	else
+	{
+		host_logf(HOST_LOG_INFO, "write tracking: page protection");
+	}
 	boot = make_boot(&environment);
 	host_logf(HOST_LOG_INFO, "data %s, saves %s", data_root, save_root);
 	host_run_guest_main(boot);
@@ -359,7 +511,7 @@ int main(int argc, char *argv[])
 {
 	(void)argc;
 	(void)argv;
-	host_logf(HOST_LOG_INFO, "Halo for Android starting");
+	host_logf(HOST_LOG_INFO, "Ringfall: Mjolnir VR starting");
 	host_install_signal_handlers();
 	if (host_native_thread_create(game_main, NULL, MAIN_STACK_SIZE) != 0)
 		host_fatal("cannot start the game thread");
@@ -17,10 +17,13 @@ This file also implements guest memory write tracking (the interface of
 port/linux/src/memory_watch.c): the renderer write-protects the pages behind
 the textures it caches, and the SIGSEGV handler here records the first
 write to each. Other faults are reported (with guest-relative addresses) and
-passed on to the previous handler.
+passed on to the previous handler. Under ARM translation (the x86 emulator)
+page faults cannot be caught, and the tracking compares page contents
+instead (host_watch_hash.c).
 */

 #include "host.h"
+#include "host_watch_hash.h"

 #include <errno.h>
 #include <pthread.h>
@@ -478,6 +481,21 @@ static uint8_t page_protected[WATCH_PAGE_COUNT];
 static uint32_t page_generation[WATCH_PAGE_COUNT];
 static volatile uint32_t current_generation = 1;
 static int watch_active;
+static int watch_hashing;
+static uint8_t page_hash_watched[WATCH_PAGE_COUNT];
+static uint64_t page_hash[WATCH_PAGE_COUNT];
+static uint32_t page_hashed_frame[WATCH_PAGE_COUNT];
+static struct watch_hash page_hashes =
+{
+	.base = (const uint8_t *)(uintptr_t)HALO_GUEST_WINDOW_BASE,
+	.page_count = WATCH_PAGE_COUNT,
+	.watched = page_hash_watched,
+	.hash = page_hash,
+	.hashed_frame = page_hashed_frame,
+	.generation = page_generation,
+	.current_generation = &current_generation,
+	.frame = 1,
+};

 static int in_window(uint64_t address)
 {
@@ -601,6 +619,14 @@ void host_memory_watch_initialize(void)
 	watch_active = 1;
 }

+void host_memory_watch_use_hashes(void)
+{
+	watch_hashing = 1;
+}
+
+/* memory_watch_protect: write-protects the pages of a range, or keeps their
+hash under host_memory_watch_use_hashes; a size outside the guest window
+is ignored */
 void host_memory_watch_protect(uint32_t address, uint32_t size)
 {
 	uint64_t first, last, page;
@@ -611,6 +637,11 @@ void host_memory_watch_protect(uint32_t address, uint32_t size)
 	last = watch_page((uint64_t)address + size - 1);
 	if (last >= WATCH_PAGE_COUNT)
 		last = WATCH_PAGE_COUNT - 1;
+	if (watch_hashing)
+	{
+		watch_hash_protect(&page_hashes, (uint32_t)first, (uint32_t)last);
+		return;
+	}
 	for (page = first; page <= last; page++)
 	{
 		if (!page_protected[page])
@@ -626,6 +657,8 @@ uint32_t host_memory_watch_serial(void)
 	return current_generation;
 }

+/* memory_watch_generation: the newest generation of the pages of a range.
+Under hashing this hashes the pages again, once a frame. */
 uint32_t host_memory_watch_generation(uint32_t address, uint32_t size)
 {
 	uint64_t first, last, page;
@@ -637,6 +670,8 @@ uint32_t host_memory_watch_generation(uint32_t address, uint32_t size)
 	last = watch_page((uint64_t)address + size - 1);
 	if (last >= WATCH_PAGE_COUNT)
 		last = WATCH_PAGE_COUNT - 1;
+	if (watch_hashing)
+		return watch_hash_generation(&page_hashes, (uint32_t)first, (uint32_t)last);
 	for (page = first; page <= last; page++)
 	{
 		if (page_generation[page] > newest)
@@ -645,11 +680,14 @@ uint32_t host_memory_watch_generation(uint32_t address, uint32_t size)
 	return newest;
 }

+/* memory_watch_prepare_write: unprotects the pages the host itself is about
+to write into. Nothing under hashing: the write shows in the next hash and
+there is no protection to fault on. */
 void host_memory_watch_prepare_write(uint32_t address, uint32_t size)
 {
 	uint64_t start = address, first, last, page;

-	if (!watch_active || !size)
+	if (!watch_active || watch_hashing || !size)
 		return;
 	if (start + size <= HALO_GUEST_WINDOW_BASE || start >= (uint64_t)HALO_GUEST_WINDOW_BASE + HALO_GUEST_WINDOW_SIZE)
 		return;
@@ -666,6 +704,8 @@ void host_memory_watch_prepare_write(uint32_t address, uint32_t size)
 	}
 }

+/* memory_watch_forget: the pages of a range were remapped or reprotected, so
+treat them as written and unwatched */
 void host_memory_watch_forget(uint32_t address, uint32_t size)
 {
 	uint64_t first, last, page;
@@ -676,9 +716,22 @@ void host_memory_watch_forget(uint32_t address, uint32_t size)
 	last = watch_page((uint64_t)address + size - 1);
 	if (last >= WATCH_PAGE_COUNT)
 		last = WATCH_PAGE_COUNT - 1;
+	if (watch_hashing)
+	{
+		watch_hash_forget(&page_hashes, (uint32_t)first, (uint32_t)last);
+		return;
+	}
 	for (page = first; page <= last; page++)
 	{
 		page_protected[page] = 0;
 		page_generation[page] = __sync_add_and_fetch(&current_generation, 1);
 	}
 }
+
+/* memory_watch_begin_frame: pages may be hashed again; nothing under page
+protection */
+void host_memory_watch_begin_frame(void)
+{
+	if (watch_hashing)
+		watch_hash_begin_frame(&page_hashes);
+}
@@ -32,6 +32,8 @@ struct handle
 {
 	int type;
 	void *object;
+	/* an audio stream with a callback: its binding (below) */
+	void *binding;
 };

 static struct handle handles[HANDLE_COUNT];
@@ -59,6 +61,7 @@ static uint32_t handle_new(int type, void *object)
 		{
 			handles[index].type = type;
 			handles[index].object = object;
+			handles[index].binding = NULL;
 			pthread_mutex_unlock(&handle_lock);
 			return index;
 		}
@@ -81,6 +84,30 @@ static void *handle_get(uint32_t handle, int type)
 	return object;
 }

+/* the object of a handle, which the handle no longer refers to; NULL when
+there is none. *binding gets what handle_new's caller stored (audio) */
+static void *handle_release(uint32_t handle, int type, void **binding)
+{
+	void *object = NULL;
+
+	if (binding)
+		*binding = NULL;
+	if (handle == 0 || handle >= HANDLE_COUNT)
+		return NULL;
+	pthread_mutex_lock(&handle_lock);
+	if (handles[handle].type == type)
+	{
+		object = handles[handle].object;
+		if (binding)
+			*binding = handles[handle].binding;
+		handles[handle].type = _handle_free;
+		handles[handle].object = NULL;
+		handles[handle].binding = NULL;
+	}
+	pthread_mutex_unlock(&handle_lock);
+	return object;
+}
+
 /* ---------- general */

 int host_sdl_init(uint32_t flags)
@@ -98,6 +125,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 +178,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)
@@ -207,6 +248,15 @@ uint32_t host_sdl_gamepad_from_id(uint32_t id)
 	return handle_new(_handle_gamepad, SDL_GetGamepadFromID((SDL_JoystickID)id));
 }

+/* (the event thread, when the controller goes: sdl_platform.c) */
+void host_sdl_close_gamepad(uint32_t gamepad)
+{
+	SDL_Gamepad *object = handle_release(gamepad, _handle_gamepad, NULL);
+
+	if (object)
+		SDL_CloseGamepad(object);
+}
+
 int host_sdl_gamepad_axis(uint32_t gamepad, int axis)
 {
 	SDL_Gamepad *object = handle_get(gamepad, _handle_gamepad);
@@ -253,6 +303,8 @@ struct audio_binding
 	pthread_cond_t requested;
 	pthread_cond_t done;
 	int pending;
+	/* the stream is destroyed: the thread frees the binding and ends */
+	int quit;
 	int additional;
 	int total;
 	unsigned char *buffer;
@@ -272,8 +324,10 @@ static void *audio_thread(void *context)
 	{
 		int additional, total;

-		while (!binding->pending)
+		while (!binding->pending && !binding->quit)
 			pthread_cond_wait(&binding->requested, &binding->lock);
+		if (binding->quit)
+			break;
 		additional = binding->additional;
 		total = binding->total;
 		pthread_mutex_unlock(&binding->lock);
@@ -284,6 +338,12 @@ static void *audio_thread(void *context)
 		binding->pending = 0;
 		pthread_cond_signal(&binding->done);
 	}
+	pthread_mutex_unlock(&binding->lock);
+	pthread_cond_destroy(&binding->done);
+	pthread_cond_destroy(&binding->requested);
+	pthread_mutex_destroy(&binding->lock);
+	SDL_free(binding->buffer);
+	SDL_free(binding);
 	return NULL;
 }

@@ -329,9 +389,19 @@ static int audio_keep(struct audio_binding *binding, const void *data, int lengt

 uint32_t host_sdl_open_audio_stream(uint32_t device, const void *spec, uint32_t callback, uint32_t userdata)
 {
-	struct audio_binding *binding = SDL_calloc(1, sizeof(*binding));
+	struct audio_binding *binding;
 	SDL_AudioStream *stream;

+	/* (one without a callback, the microphone's, which the guest reads:
+	nothing to bind) */
+	if (!callback)
+	{
+		stream = SDL_OpenAudioDeviceStream((SDL_AudioDeviceID)device, spec, NULL, NULL);
+		return stream ? handle_new(_handle_audio, stream) : 0;
+	}
+	binding = SDL_calloc(1, sizeof(*binding));
+	if (!binding)
+		return 0;
 	binding->callback = callback;
 	binding->userdata = userdata;
 	pthread_mutex_init(&binding->lock, NULL);
@@ -346,7 +416,19 @@ uint32_t host_sdl_open_audio_stream(uint32_t device, const void *spec, uint32_t
 	}
 	/* the device starts paused, so no callback can run before this */
 	binding->handle = handle_new(_handle_audio, stream);
-	if (callback && host_native_thread_create(audio_thread, binding, 256 * 1024) != 0)
+	if (!binding->handle)
+	{
+		SDL_DestroyAudioStream(stream);
+		pthread_cond_destroy(&binding->done);
+		pthread_cond_destroy(&binding->requested);
+		pthread_mutex_destroy(&binding->lock);
+		SDL_free(binding);
+		return 0;
+	}
+	pthread_mutex_lock(&handle_lock);
+	handles[binding->handle].binding = binding;
+	pthread_mutex_unlock(&handle_lock);
+	if (host_native_thread_create(audio_thread, binding, 256 * 1024) != 0)
 		host_fatal("cannot start the audio thread");
 	return binding->handle;
 }
@@ -369,6 +451,43 @@ int host_sdl_resume_audio_stream_device(uint32_t stream)
 	return object ? SDL_ResumeAudioStreamDevice(object) : 0;
 }

+/* (voice chat's microphone: port/linux/src/voice_audio.c) */
+int host_sdl_get_audio_stream_data(uint32_t stream, void *data, int length)
+{
+	SDL_AudioStream *object = handle_get(stream, _handle_audio);
+
+	return object ? SDL_GetAudioStreamData(object, data, length) : -1;
+}
+
+int host_sdl_get_audio_stream_available(uint32_t stream)
+{
+	SDL_AudioStream *object = handle_get(stream, _handle_audio);
+
+	return object ? SDL_GetAudioStreamAvailable(object) : -1;
+}
+
+/* (a stream with a callback has a thread the guest's callbacks run on:
+once no callback can run any more, it is told to end, and frees the
+binding and its stack as it goes) */
+void host_sdl_destroy_audio_stream(uint32_t stream)
+{
+	void *context;
+	SDL_AudioStream *object = handle_release(stream, _handle_audio, &context);
+	struct audio_binding *binding = context;
+
+	if (!object)
+		return;
+	/* (returns once a callback that is running has finished) */
+	SDL_DestroyAudioStream(object);
+	if (binding)
+	{
+		pthread_mutex_lock(&binding->lock);
+		binding->quit = 1;
+		pthread_cond_signal(&binding->requested);
+		pthread_mutex_unlock(&binding->lock);
+	}
+}
+
 /* ---------- the clipboard (internet play's invite links) */

 int host_sdl_set_clipboard_text(const char *text)
@@ -131,6 +131,10 @@ static void *thread_main(void *context)
 	free(context);
 	host_debug_thread_started();
 	start.function(start.argument);
+	/* (a thread the guest made has let its struct pthread go by now; one
+	of the host's that ran guest code, the audio thread, has it still) */
+	if (guest_tp)
+		((guest_function)(uintptr_t)host_image.header->thread_detach)(0, 0, 0, 0);
 	host_debug_thread_exited();
 	guest_tp = 0;

@@ -0,0 +1,229 @@
+/*
+HOST_TOUCH.C
+
+The on-screen touch controls between the overlay and the game. The overlay
+(app/.../TouchControls.java) is an Android view over SDL's surface: it
+hands its stick, buttons, view swipes and gyroscope turns over JNI on the UI
+thread, and the game reads them through host imports when it reads port 0's
+controller (port/linux/src/xinput_sdl.c). The game hands back what the
+overlay needs to know: whether it is in a game with no menu or cinematic up
+and the input.touch_controls setting (host_touch_scene), the profile's
+button mapping, which names the buttons (host_touch_bindings), and how hard
+port 0 rumbles.
+*/
+
+#include <jni.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <string.h>
+#include <time.h>
+
+/* a press shorter than this still reaches the game: it reads the
+controller once a frame and acts at 30 ticks a second, and a quick tap can
+go down and up between two reads */
+#define TOUCH_TAP_NS 60000000LL
+/* view motion and rumble older than this are dropped: left over from the
+menus, a cinematic or the app in the background */
+#define TOUCH_STALE_NS 150000000LL
+
+/* SDL's 15 gamepad buttons, then the left and right triggers */
+#define TOUCH_INPUTS 17
+
+static pthread_mutex_t touch_lock = PTHREAD_MUTEX_INITIALIZER;
+/* the SDL axes (left x, y, right x, y, left trigger, right trigger), then
+the SDL button bits */
+static int32_t touch_state[7];
+static int64_t touch_pressed_ns[TOUCH_INPUTS];
+static float look_delta[2];
+static int64_t look_ns;
+/* the gyroscope's turn, apart: the profile's invert is the swipe's only */
+static float gyro_delta[2];
+static int64_t gyro_ns;
+static int rumble_amplitude;
+static int64_t rumble_ns;
+static volatile int touch_scene;
+/* the game control on each controller button (-1: none), and a count of
+its changes, which the overlay polls */
+#define TOUCH_BUTTONS 16
+static int32_t touch_bindings[TOUCH_BUTTONS];
+static int touch_bindings_serial;
+
+static int64_t now_ns(void)
+{
+	struct timespec now;
+
+	clock_gettime(CLOCK_MONOTONIC, &now);
+	return (int64_t)now.tv_sec * 1000000000LL + now.tv_nsec;
+}
+
+/* the inputs of a state as bits: buttons, then the triggers */
+static uint32_t touch_inputs(const int32_t *state)
+{
+	return ((uint32_t)state[6] & 0x7fff) | (state[4] ? 1u << 15 : 0) | (state[5] ? 1u << 16 : 0);
+}
+
+JNIEXPORT void JNICALL Java_com_halo_decomp_TouchControls_nativeState(
+	JNIEnv *env, jclass cls, jint lx, jint ly, jint rx, jint ry,
+	jint lt, jint rt, jint buttons)
+{
+	int32_t next[] = { lx, ly, rx, ry, lt, rt, buttons };
+	uint32_t pressed;
+	int64_t now = now_ns();
+	int input;
+
+	(void)env;
+	(void)cls;
+	pthread_mutex_lock(&touch_lock);
+	pressed = touch_inputs(next) & ~touch_inputs(touch_state);
+	for (input = 0; input < TOUCH_INPUTS; input++)
+	{
+		if (pressed & (1u << input))
+			touch_pressed_ns[input] = now;
+	}
+	memcpy(touch_state, next, sizeof(next));
+	pthread_mutex_unlock(&touch_lock);
+}
+
+/* the guest's: the overlay's controller state, with each press held for
+at least TOUCH_TAP_NS */
+void host_touch_read(int32_t *state)
+{
+	int64_t now = now_ns();
+	int input;
+
+	pthread_mutex_lock(&touch_lock);
+	memcpy(state, touch_state, sizeof(touch_state));
+	for (input = 0; input < TOUCH_INPUTS; input++)
+	{
+		if (touch_pressed_ns[input] && now - touch_pressed_ns[input] < TOUCH_TAP_NS)
+		{
+			if (input < 15)
+				state[6] |= 1 << input;
+			else if (!state[4 + input - 15])
+				state[4 + input - 15] = 32767;
+		}
+	}
+	pthread_mutex_unlock(&touch_lock);
+}
+
+JNIEXPORT void JNICALL Java_com_halo_decomp_TouchControls_nativeLook(
+	JNIEnv *env, jclass cls, jfloat dx, jfloat dy)
+{
+	(void)env;
+	(void)cls;
+	pthread_mutex_lock(&touch_lock);
+	look_delta[0] += dx;
+	look_delta[1] += dy;
+	look_ns = now_ns();
+	pthread_mutex_unlock(&touch_lock);
+}
+
+JNIEXPORT void JNICALL Java_com_halo_decomp_TouchControls_nativeGyro(
+	JNIEnv *env, jclass cls, jfloat dx, jfloat dy)
+{
+	(void)env;
+	(void)cls;
+	pthread_mutex_lock(&touch_lock);
+	gyro_delta[0] += dx;
+	gyro_delta[1] += dy;
+	gyro_ns = now_ns();
+	pthread_mutex_unlock(&touch_lock);
+}
+
+JNIEXPORT void JNICALL Java_com_halo_decomp_TouchControls_nativeLookReset(JNIEnv *env, jclass cls)
+{
+	(void)env;
+	(void)cls;
+	pthread_mutex_lock(&touch_lock);
+	look_delta[0] = look_delta[1] = 0.0f;
+	gyro_delta[0] = gyro_delta[1] = 0.0f;
+	pthread_mutex_unlock(&touch_lock);
+}
+
+/* the guest's: the view swipe, then the gyroscope's turn, since the last
+read, into delta[4], in the overlay's logical pixels with its sensitivity
+applied */
+void host_touch_look_read(float *delta)
+{
+	int64_t now = now_ns();
+
+	pthread_mutex_lock(&touch_lock);
+	memcpy(delta, look_delta, sizeof(look_delta));
+	memcpy(delta + 2, gyro_delta, sizeof(gyro_delta));
+	if (now - look_ns > TOUCH_STALE_NS)
+		delta[0] = delta[1] = 0.0f;
+	if (now - gyro_ns > TOUCH_STALE_NS)
+		delta[2] = delta[3] = 0.0f;
+	look_delta[0] = look_delta[1] = 0.0f;
+	gyro_delta[0] = gyro_delta[1] = 0.0f;
+	pthread_mutex_unlock(&touch_lock);
+}
+
+/* the guest's: port 0's motors (XInputSetState), each 0..65535; the game
+sends them every frame, and zero while paused or with the profile's
+vibration off */
+void host_touch_rumble(unsigned int low, unsigned int high)
+{
+	unsigned int strength = low > high ? low : high;
+
+	pthread_mutex_lock(&touch_lock);
+	rumble_amplitude = strength ? 64 + (int)(strength * 191u / 65535u) : 0;
+	rumble_ns = now_ns();
+	pthread_mutex_unlock(&touch_lock);
+}
+
+/* the phone's vibration strength, 0 or 64..255 */
+JNIEXPORT jint JNICALL Java_com_halo_decomp_TouchControls_nativeRumble(JNIEnv *env, jclass cls)
+{
+	int amplitude;
+
+	(void)env;
+	(void)cls;
+	pthread_mutex_lock(&touch_lock);
+	amplitude = now_ns() - rumble_ns > TOUCH_STALE_NS ? 0 : rumble_amplitude;
+	pthread_mutex_unlock(&touch_lock);
+	return amplitude;
+}
+
+/* the guest's, at every read of port 0: port/linux/src/touch_input.c's
+_touch_scene_* bits */
+void host_touch_scene(int scene)
+{
+	touch_scene = scene;
+}
+
+/* the guest's, when the profile's mapping changes: the game control on
+each of the 16 controller buttons (port/linux/game/touch_game.c) */
+void host_touch_bindings(const int32_t *controls)
+{
+	pthread_mutex_lock(&touch_lock);
+	memcpy(touch_bindings, controls, sizeof(touch_bindings));
+	touch_bindings_serial++;
+	pthread_mutex_unlock(&touch_lock);
+}
+
+/* the mapping into controls[16]; returns its count of changes (0 before the
+game has sent it) */
+JNIEXPORT jint JNICALL Java_com_halo_decomp_TouchControls_nativeBindings(JNIEnv *env, jclass cls,
+	jintArray controls)
+{
+	int32_t copy[TOUCH_BUTTONS];
+	int serial;
+
+	(void)cls;
+	pthread_mutex_lock(&touch_lock);
+	memcpy(copy, touch_bindings, sizeof(copy));
+	serial = touch_bindings_serial;
+	pthread_mutex_unlock(&touch_lock);
+	if (controls && (*env)->GetArrayLength(env, controls) >= TOUCH_BUTTONS)
+		(*env)->SetIntArrayRegion(env, controls, 0, TOUCH_BUTTONS, (const jint *)copy);
+	return serial;
+}
+
+/* 0 until the game has read its controller once */
+JNIEXPORT jint JNICALL Java_com_halo_decomp_TouchControls_nativeScene(JNIEnv *env, jclass cls)
+{
+	(void)env;
+	(void)cls;
+	return touch_scene;
+}
@@ -0,0 +1,114 @@
+/*
+HOST_WATCH_HASH.C
+
+Write tracking by page contents (host_watch_hash.h).
+*/
+
+#include "host_watch_hash.h"
+
+/*
+FNV-style mixing in four independent lanes, so that the multiplies of
+one lane do not wait for another's. A change of one word changes its
+lane's state for good (xor and an odd multiply are both invertible), so
+a single-word write always shows. Changes of several words could cancel
+each other, which is unlikely for game data. (host_watch_hash.h)
+*/
+uint64_t watch_hash_page(const uint8_t *page)
+{
+	const uint64_t *words = (const uint64_t *)page;
+	uint64_t lane0 = 0xcbf29ce484222325ULL, lane1 = 0x9e3779b97f4a7c15ULL;
+	uint64_t lane2 = 0xc2b2ae3d27d4eb4fULL, lane3 = 0x165667b19e3779f9ULL;
+	uint32_t index;
+
+	for (index = 0; index < WATCH_HASH_PAGE_SIZE / 8; index += 4)
+	{
+		lane0 = (lane0 ^ words[index + 0]) * 0x100000001b3ULL;
+		lane1 = (lane1 ^ words[index + 1]) * 0x100000001b3ULL;
+		lane2 = (lane2 ^ words[index + 2]) * 0x100000001b3ULL;
+		lane3 = (lane3 ^ words[index + 3]) * 0x100000001b3ULL;
+	}
+	return lane0 ^ ((lane1 << 16) | (lane1 >> 48)) ^ ((lane2 << 32) | (lane2 >> 32)) ^
+		((lane3 << 48) | (lane3 >> 16));
+}
+
+/* clamps last to the watched memory; 0 when nothing is left of the range */
+static int clamp(const struct watch_hash *watch, uint32_t first, uint32_t *last)
+{
+	if (first >= watch->page_count || first > *last)
+		return 0;
+	if (*last >= watch->page_count)
+		*last = watch->page_count - 1;
+	return 1;
+}
+
+static const uint8_t *page_memory(const struct watch_hash *watch, uint32_t page)
+{
+	return watch->base + (uint64_t)page * WATCH_HASH_PAGE_SIZE;
+}
+
+void watch_hash_protect(struct watch_hash *watch, uint32_t first, uint32_t last)
+{
+	uint32_t page;
+
+	if (!clamp(watch, first, &last))
+		return;
+	for (page = first; page <= last; page++)
+	{
+		if (watch->watched[page])
+			continue;
+		watch->watched[page] = 1;
+		watch->hash[page] = watch_hash_page(page_memory(watch, page));
+		watch->hashed_frame[page] = watch->frame;
+	}
+}
+
+uint32_t watch_hash_generation(struct watch_hash *watch, uint32_t first, uint32_t last)
+{
+	uint32_t page, newest = 0;
+
+	if (!clamp(watch, first, &last))
+		return 0;
+	for (page = first; page <= last; page++)
+	{
+		if (watch->watched[page] && watch->hashed_frame[page] != watch->frame)
+		{
+			uint64_t hash = watch_hash_page(page_memory(watch, page));
+
+			watch->hashed_frame[page] = watch->frame;
+			if (hash != watch->hash[page])
+			{
+				watch->hash[page] = hash;
+				watch->generation[page] = __sync_add_and_fetch(watch->current_generation, 1);
+			}
+		}
+		if (watch->generation[page] > newest)
+			newest = watch->generation[page];
+	}
+	return newest;
+}
+
+void watch_hash_forget(struct watch_hash *watch, uint32_t first, uint32_t last)
+{
+	uint32_t page;
+
+	if (!clamp(watch, first, &last))
+		return;
+	for (page = first; page <= last; page++)
+	{
+		watch->watched[page] = 0;
+		watch->generation[page] = __sync_add_and_fetch(watch->current_generation, 1);
+	}
+}
+
+/*
+The serial changes each frame, so a cache that skips generation queries
+while the serial stays the same (xbox_textures.c's recent_textures) asks
+again once a frame. (host_watch_hash.h)
+*/
+void watch_hash_begin_frame(struct watch_hash *watch)
+{
+	watch->frame++;
+	if (!watch->frame)
+		watch->frame = 1;
+	__sync_add_and_fetch(watch->current_generation, 1);
+}
@@ -0,0 +1,57 @@
+/*
+HOST_WATCH_HASH.H
+
+Write tracking by page contents, for processes that cannot catch their own
+page protection faults: the ARM translation of the x86 Android emulator
+cannot deliver SIGSEGV to the app, so the protection-based tracking of
+host_memory.c would stop the game at its first write to a cached page.
+
+A watched page's hash is kept. Asking for its generation hashes it again,
+at most once a frame (watch_hash_begin_frame), and a different hash counts
+as a write. A write is therefore seen in the next frame, not at once.
+*/
+
+#ifndef HOST_WATCH_HASH_H
+#define HOST_WATCH_HASH_H
+
+#include <stdint.h>
+
+#define WATCH_HASH_PAGE_SIZE 0x1000u
+
+struct watch_hash
+{
+	/* the memory of page 0 */
+	const uint8_t *base;
+	uint32_t page_count;
+	/* page_count entries each */
+	uint8_t *watched;
+	uint64_t *hash;
+	uint32_t *hashed_frame;
+	/* shared with the protection-based tracking (host_memory.c) */
+	uint32_t *generation;
+	volatile uint32_t *current_generation;
+	uint32_t frame;
+};
+
+/* a hash of one page (WATCH_HASH_PAGE_SIZE bytes, 8-byte aligned) that
+changes whenever a word of it changes */
+uint64_t watch_hash_page(const uint8_t *page);
+
+/* Starts watching pages first to last (inclusive), remembering their hashes.
+Pages already watched keep their hash; pages beyond page_count are
+ignored. */
+void watch_hash_protect(struct watch_hash *watch, uint32_t first, uint32_t last);
+
+/* The newest generation among pages first to last (inclusive), after hashing
+again the watched ones not yet hashed this frame; a page whose hash
+changed gets a new generation. 0 if the range is outside the watched
+memory. */
+uint32_t watch_hash_generation(struct watch_hash *watch, uint32_t first, uint32_t last);
+
+/* The pages were remapped: treat them as written and unwatched. */
+void watch_hash_forget(struct watch_hash *watch, uint32_t first, uint32_t last);
+
+/* A new frame: pages may be hashed again, and the serial changes. */
+void watch_hash_begin_frame(struct watch_hash *watch);
+
+#endif
@@ -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,14 +1219,20 @@ 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;
 	instance.next = &android;
-	strcpy(instance.applicationInfo.applicationName, "Halo VR");
+	strcpy(instance.applicationInfo.applicationName, "Ringfall Mjolnir VR");
 	instance.applicationInfo.applicationVersion = 1;
 	strcpy(instance.applicationInfo.engineName, "halo-ce-universal");
 	instance.applicationInfo.engineVersion = 1;
@@ -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 };
@@ -1557,7 +2167,7 @@ void host_xr_test(void)
 	SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, SDL_GL_CONTEXT_PROFILE_ES);
 	SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 3);
 	SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 2);
-	window = SDL_CreateWindow("Halo", 640, 480, SDL_WINDOW_OPENGL | SDL_WINDOW_FULLSCREEN);
+	window = SDL_CreateWindow("Ringfall: Mjolnir VR", 640, 480, SDL_WINDOW_OPENGL | SDL_WINDOW_FULLSCREEN);
 	context = window ? SDL_GL_CreateContext(window) : NULL;
 	if (!context || !SDL_GL_MakeCurrent(window, context))
 		host_fatal("VR test: no OpenGL ES context: %s", SDL_GetError());
@@ -13,6 +13,7 @@ host_memory_watch_generation
 host_memory_watch_serial
 host_memory_watch_prepare_write
 host_memory_watch_forget
+host_memory_watch_begin_frame
 host_sdl_init
 host_sdl_set_hint
 host_sdl_get_error
@@ -38,12 +39,18 @@ host_sdl_gamepad_axis
 host_sdl_gamepad_button
 host_sdl_gamepad_type
 host_sdl_rumble_gamepad
+host_sdl_close_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
+host_sdl_get_audio_stream_data
+host_sdl_get_audio_stream_available
+host_sdl_destroy_audio_stream
 host_gl_get_string
 host_gl_has_extension
-host_gl_read_buffer_word
+host_gl_read_buffer
 host_gl_buffer_write
 host_gl_buffer_storage
 host_gl_persistent_write
@@ -59,6 +66,14 @@ 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_gesture_insets
+host_touch_read
+host_touch_look_read
+host_touch_rumble
+host_touch_scene
+host_touch_bindings

 host_errno
@@ -35,7 +35,7 @@ keeps its heaps low in the address space and fills it upwards */
 #define HALO_GUEST_WINDOW_SIZE 0x08000000u

 #define HALO_GUEST_MAGIC 0x4f4c4148u /* 'HALO' */
-#define HALO_GUEST_ABI_VERSION 1
+#define HALO_GUEST_ABI_VERSION 2

 /* at HALO_GUEST_IMAGE_BASE */
 struct halo_guest_header
@@ -49,6 +49,7 @@ struct halo_guest_header
 	uint32_t start;              /* void __guest_start(struct halo_guest_boot *) */
 	uint32_t thread_start;       /* void __guest_thread_start(uint32_t thread) */
 	uint32_t thread_attach;      /* uint32_t __guest_thread_attach(void) */
+	uint32_t thread_detach;      /* void __guest_thread_detach(void) */
 	uint32_t init_array_start;   /* void (*)(void) entries, 4 bytes each */
 	uint32_t init_array_end;
 };
@@ -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,39 @@
+diff --git a/android-project/app/src/main/java/org/libsdl/app/SDLControllerManager.java b/android-project/app/src/main/java/org/libsdl/app/SDLControllerManager.java
+index 8681d05..1beeac4 100644
+--- a/android-project/app/src/main/java/org/libsdl/app/SDLControllerManager.java
+++ b/android-project/app/src/main/java/org/libsdl/app/SDLControllerManager.java
+@@ -787,6 +787,34 @@ class SDLGenericMotionListener_API14 implements View.OnGenericMotionListener {
+                         consumed = true;
+                         break;
+ 
+                    case MotionEvent.ACTION_BUTTON_PRESS:
+                        if (checkRelativeEvent(event)) {
+                            x = getEventX(event, i);
+                            y = getEventY(event, i);
+                            SDLActivity.onNativeMouse(event.getButtonState(), MotionEvent.ACTION_DOWN, x, y, true);
+                            consumed = true;
+                        }
+                        break;
+
+                    case MotionEvent.ACTION_BUTTON_RELEASE:
+                        if (checkRelativeEvent(event)) {
+                            x = getEventX(event, i);
+                            y = getEventY(event, i);
+                            SDLActivity.onNativeMouse(event.getButtonState(), MotionEvent.ACTION_UP, x, y, true);
+                            consumed = true;
+                        }
+                        break;
+
+                    case MotionEvent.ACTION_MOVE:
+                        // Pointer capture delivers relative mouse motion as ACTION_MOVE.
+                        if (checkRelativeEvent(event)) {
+                            x = getEventX(event, i);
+                            y = getEventY(event, i);
+                            SDLActivity.onNativeMouse(0, action, x, y, true);
+                            consumed = true;
+                        }
+                        break;
+
+                     case MotionEvent.ACTION_HOVER_MOVE:
+                         x = getEventX(event, i);
+                         y = getEventY(event, i);
@@ -0,0 +1,288 @@
+#!/bin/bash
+# Ringfall: Mjolnir VR's installer for the Steam Frame, run in its Desktop
+# Mode from the bundle the release's "Install Ringfall: Mjolnir VR" desktop
+# file downloads (steam_frame_installer.desktop; the bundle: this script,
+# RingfallMjolnirVR.apk, ringfall-mjolnir-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/RingfallMjolnirVR (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 folder of the builds
+#   before the name, ~/Documents/HaloCE, becomes it;
+# - the game data: the maps folder copied out of a disc image of the
+#   original Xbox game (.iso or .xiso) found in Downloads, Documents, the
+#   Desktop or on a memory card, or chosen, unless it is there already;
+# - the game in the Steam library, with its pictures, unless it is there
+#   already: added by Steam itself (steam://addnonsteamgame, as SteamOS's
+#   "Add to Steam" does), from a desktop file beside the game. Steam is not
+#   closed: it keeps its shortcuts in memory and writes them back, and on the
+#   Steam Frame Desktop Mode runs inside Gaming Mode's session, which ends
+#   with Steam. The shortcut of the builds before the name ("Halo VR") is
+#   left for the player to remove (Steam would write it back).
+# RINGFALL_UNATTENDED=1 answers every question with its default and prints
+# instead of showing dialogs (RINGFALL_IMAGE: the disc image to use), for
+# testing over adb; it never closes Steam.
+
+BUNDLE="$(cd "$(dirname "$0")" && pwd)"
+GAME_DIR="$HOME/Documents/RingfallMjolnirVR"
+STEAM_DIR="$HOME/.local/share/Steam"
+LEPTON="$STEAM_DIR/steamapps/common/Lepton/lepton"
+TITLE="Ringfall: Mjolnir VR"
+NAME="Ringfall: Mjolnir VR"
+APK_NAME="RingfallMjolnirVR.apk"
+LAUNCHER="ringfall-mjolnir-vr.sh"
+EXE="\"$GAME_DIR/$LAUNCHER\""
+# (the desktop file Steam adds the game from)
+NAME_FILE="Ringfall Mjolnir VR"
+# the builds before the name: their folder and Steam shortcut
+OLD_DIR="$HOME/Documents/HaloCE"
+OLD_NAME="Halo VR"
+
+# what the installer did, for looking into problems: written to /tmp while
+# it runs, then kept beside the game as install.log
+LOG="/tmp/ringfall-mjolnir-vr-install.log"
+: > "$LOG"
+log() { echo "$(date '+%F %T') $*" >> "$LOG"; }
+keep_log() { [ -d "$GAME_DIR" ] && cp -f "$LOG" "$GAME_DIR/install.log" 2>/dev/null; }
+trap keep_log EXIT
+log "installer from $BUNDLE"
+
+# whether Steam runs: its pid file (~/.steam/steam.pid), or its client's
+# process (ubuntu12_32/steam: the process is not always named "steam")
+steam_running()
+{
+    local pid
+    pid="$(cat "$HOME/.steam/steam.pid" 2>/dev/null)"
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+        return 0
+    fi
+    pgrep -f 'ubuntu12_32/steam( |$)' >/dev/null || pgrep -x steam >/dev/null
+}
+
+unattended() { [ "${RINGFALL_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()
+{
+    log "error: $1"
+    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 for the Xbox (.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 (the game's 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" "$GAME_DIR" 2>"$log" | grep '^#' | tail -n 1
+        status=${PIPESTATUS[0]}
+    else
+        python3 "$BUNDLE/steam_frame_xiso.py" "$image" "$GAME_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 Steam users' shortcut files (userdata/0 is no user)
+shortcut_files()
+{
+    local config
+    for config in "$STEAM_DIR"/userdata/*/config; do
+        case "$config" in */userdata/0/*) continue ;; esac
+        [ -f "$config/shortcuts.vdf" ] && echo "$config/shortcuts.vdf"
+    done
+}
+
+# whether a Steam user's library holds the launcher given
+have_shortcut_to()
+{
+    local file
+    while read -r file; do
+        grep -qaF "$1" "$file" && return 0
+    done < <(shortcut_files)
+    return 1
+}
+
+have_shortcut() { have_shortcut_to "$GAME_DIR/$LAUNCHER"; }
+
+# the id Steam gave the shortcut whose Exe is $2, in shortcuts.vdf $1 (Steam
+# picks it; its library pictures in config/grid are named after it)
+shortcut_id()
+{
+    python3 - "$1" "$2" <<'PYTHON'
+import struct, sys
+
+path, exe = sys.argv[1], sys.argv[2].encode()
+
+# 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].lower(); 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((key, value))
+
+with open(path, "rb") as file:
+    top, _ = read_map(file.read(), 0)
+for key, shortcuts in top:
+    if key == b"shortcuts":
+        for _, entry in shortcuts:
+            fields = dict(entry)
+            if fields.get(b"exe") == exe and b"appid" in fields:
+                print(fields[b"appid"])
+                sys.exit(0)
+sys.exit(1)
+PYTHON
+}
+
+# the game added to the library of the Steam user logged in, by Steam (it
+# must run), from a desktop file beside the game; then its pictures
+add_shortcut()
+{
+    local desktop="$GAME_DIR/$NAME_FILE.desktop" url file id
+    printf '[Desktop Entry]\nType=Application\nName=%s\nExec=%s\nPath=%s\nIcon=steam\nTerminal=false\n' \
+        "$NAME" "$GAME_DIR/$LAUNCHER" "$GAME_DIR" > "$desktop" && chmod 755 "$desktop" || return 1
+    url="steam://addnonsteamgame/$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$desktop")"
+    log "asking Steam: $url"
+    # (Steam's own "Add to Steam" touches this first: steamos-add-to-steam)
+    touch /tmp/addnonsteamgamefile
+    steam "$url" >/dev/null 2>&1 &
+    for _ in $(seq 30); do have_shortcut && break; sleep 1; done
+    have_shortcut || return 1
+    while read -r file; do
+        id="$(shortcut_id "$file" "$EXE")" || continue
+        log "shortcut $id in $file"
+        mkdir -p "$(dirname "$file")/grid"
+        cp "$BUNDLE/grid/library.png" "$(dirname "$file")/grid/${id}.png"
+        cp "$BUNDLE/grid/libraryp.png" "$(dirname "$file")/grid/${id}p.png"
+        cp "$BUNDLE/grid/library_hero.png" "$(dirname "$file")/grid/${id}_hero.png"
+        cp "$BUNDLE/grid/library_logo.png" "$(dirname "$file")/grid/${id}_logo.png"
+    done < <(shortcut_files)
+    return 0
+}
+
+# --- 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 "$APK_NAME" "$LAUNCHER" steam_frame_xiso.py grid/library.png; do
+    [ -f "$BUNDLE/$file" ] || fail "The installer is incomplete ($file is missing). Download it again."
+done
+
+# the builds before the name: their folder becomes the game's (settings,
+# saves and game data kept), without their APK and launcher
+if [ -d "$OLD_DIR" ] && [ ! -e "$GAME_DIR" ]; then
+    log "renaming $OLD_DIR to $GAME_DIR"
+    mv "$OLD_DIR" "$GAME_DIR" || fail "Could not rename $OLD_DIR to $GAME_DIR."
+    rm -f "$GAME_DIR/HaloVR.apk" "$GAME_DIR/halo-vr.sh"
+fi
+
+if [ -f "$GAME_DIR/$APK_NAME" ] || [ -f "$GAME_DIR/maps/ui.map" ]; then
+    ask "$NAME is installed already. Update it to this version?\n\n(Your settings, saves and game data stay.)" yes || exit 0
+else
+    ask "This installs $NAME on your Steam Frame.\n\nYou need your own disc image of Halo: Combat Evolved for the original Xbox (an .iso or .xiso file, any version), for example in Downloads.\n\nContinue?" yes || exit 0
+fi
+
+mkdir -p "$GAME_DIR/maps" || fail "Could not create $GAME_DIR."
+# (the game runs in Lepton's container as a user of its own)
+chmod 777 "$GAME_DIR" "$GAME_DIR/maps"
+cp "$BUNDLE/$LAUNCHER" "$GAME_DIR/$LAUNCHER.tmp" && chmod 755 "$GAME_DIR/$LAUNCHER.tmp" &&
+    mv -f "$GAME_DIR/$LAUNCHER.tmp" "$GAME_DIR/$LAUNCHER" || fail "Could not write $GAME_DIR/$LAUNCHER."
+# (newer than the installed one: Lepton installs it at the next start)
+cp "$BUNDLE/$APK_NAME" "$GAME_DIR/$APK_NAME.tmp" && chmod 666 "$GAME_DIR/$APK_NAME.tmp" &&
+    mv -f "$GAME_DIR/$APK_NAME.tmp" "$GAME_DIR/$APK_NAME" && touch "$GAME_DIR/$APK_NAME" ||
+    fail "Could not write $GAME_DIR/$APK_NAME (is the storage full?)."
+
+# --- the game data
+
+if [ ! -f "$GAME_DIR/maps/ui.map" ]; then
+    image="${RINGFALL_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
+    log "extracting $image"
+    extract_maps "$image"
+    chmod -R a+rwX "$GAME_DIR/maps"
+    image_note="\n\nThe disc image itself is no longer needed:\n$image"
+fi
+
+# --- Steam
+
+if have_shortcut; then
+    log "the Steam shortcut is there"
+elif unattended; then
+    echo "info: the Steam shortcut is missing (not added unattended)"
+elif ! steam_running; then
+    info "Steam is not running, so $NAME could not be added to your library.\n\nStart Steam and run the installer again."
+else
+    add_shortcut || fail "Steam did not add $NAME to your library. Run the installer again; if it happens again, add\n$GAME_DIR/$NAME_FILE.desktop\nwith Steam's \"Add a Non-Steam Game\"."
+fi
+
+if unattended; then
+    echo "info: installed in $GAME_DIR"
+    exit 0
+fi
+if have_shortcut_to "$OLD_DIR/halo-vr.sh"; then
+    info "The library still shows the old \"$OLD_NAME\" from before the game's new name. It no longer starts: remove it in Steam (its gear or Manage > Remove non-Steam game)."
+fi
+if ask "$NAME is installed.${image_note:-}\n\nSwitch to Gaming Mode now? Start $NAME from your library there (its pictures may show once Steam starts again)." 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)."
+fi
@@ -0,0 +1,14 @@
+[Desktop Entry]
+# Ringfall: Mjolnir VR's installer for the Steam Frame
+# (port/android/STEAM_FRAME.md): a release asset,
+# "Install-Ringfall-Mjolnir-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 Ringfall: Mjolnir VR
+Comment=Installs Ringfall: Mjolnir VR for the Steam Frame, or updates it
+Icon=steam
+Terminal=false
+Exec=bash -c "if curl -fL --retry 3 -o /tmp/ringfall-mjolnir-vr-steam-frame.zip https://github.com/@REPOSITORY@/releases/latest/download/ringfall-mjolnir-vr-steam-frame.zip && rm -rf /tmp/ringfall-mjolnir-vr-install && python3 -m zipfile -e /tmp/ringfall-mjolnir-vr-steam-frame.zip /tmp/ringfall-mjolnir-vr-install; then exec bash /tmp/ringfall-mjolnir-vr-install/install.sh; else zenity --error --width=460 --title='Ringfall: Mjolnir VR' --text='Ringfall: Mjolnir VR could not be downloaded. Is the Steam Frame online?'; fi"
@@ -0,0 +1,86 @@
+#!/bin/bash
+# Ringfall: Mjolnir 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/RingfallMjolnirVR.
+# (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"
+DATA="$HOME/Documents/RingfallMjolnirVR"
+APK="$DATA/RingfallMjolnirVR.apk"
+LOG="$DATA/launcher.log"
+# (written by the game when the player quits it: no start again)
+QUIT="$DATA/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="$DATA/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,216 @@
+/*
+HOST_WATCH_HASH_TEST.C
+
+Tests of the page-hash write tracking (port/android/host/host_watch_hash.c).
+Built and run by tools/test_host_watch_hash.py; exits nonzero on a failure.
+*/
+
+#include "../host/host_watch_hash.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define PAGES 4
+
+static int failures;
+
+#define CHECK(condition) \
+	do \
+	{ \
+		if (!(condition)) \
+		{ \
+			printf("FAIL %s:%d: %s\n", __FILE__, __LINE__, #condition); \
+			failures++; \
+		} \
+	} while (0)
+
+struct fixture
+{
+	uint8_t *memory;
+	uint8_t watched[PAGES];
+	uint64_t hash[PAGES];
+	uint32_t hashed_frame[PAGES];
+	uint32_t generation[PAGES];
+	volatile uint32_t current;
+	struct watch_hash watch;
+};
+
+static void setup(struct fixture *f)
+{
+	memset(f, 0, sizeof(*f));
+	f->memory = aligned_alloc(WATCH_HASH_PAGE_SIZE, PAGES * WATCH_HASH_PAGE_SIZE);
+	memset(f->memory, 0x5a, PAGES * WATCH_HASH_PAGE_SIZE);
+	f->current = 1;
+	f->watch.base = f->memory;
+	f->watch.page_count = PAGES;
+	f->watch.watched = f->watched;
+	f->watch.hash = f->hash;
+	f->watch.hashed_frame = f->hashed_frame;
+	f->watch.generation = f->generation;
+	f->watch.current_generation = &f->current;
+	f->watch.frame = 1;
+}
+
+static void teardown(struct fixture *f)
+{
+	free(f->memory);
+}
+
+static uint8_t *byte_of(struct fixture *f, uint32_t page, uint32_t offset)
+{
+	return f->memory + page * WATCH_HASH_PAGE_SIZE + offset;
+}
+
+static void test_unchanged_page_keeps_generation(void)
+{
+	struct fixture f;
+	uint32_t before;
+
+	setup(&f);
+	watch_hash_protect(&f.watch, 0, 0);
+	before = watch_hash_generation(&f.watch, 0, 0);
+	watch_hash_begin_frame(&f.watch);
+	CHECK(watch_hash_generation(&f.watch, 0, 0) == before);
+	teardown(&f);
+}
+
+static void test_write_is_seen_next_frame(void)
+{
+	struct fixture f;
+	uint32_t before, after;
+
+	setup(&f);
+	watch_hash_protect(&f.watch, 1, 1);
+	before = watch_hash_generation(&f.watch, 1, 1);
+	*byte_of(&f, 1, 100) ^= 1;
+	/* the page was hashed in this frame already */
+	CHECK(watch_hash_generation(&f.watch, 1, 1) == before);
+	watch_hash_begin_frame(&f.watch);
+	after = watch_hash_generation(&f.watch, 1, 1);
+	CHECK(after > before);
+	CHECK(f.current >= after);
+	teardown(&f);
+}
+
+static void test_any_byte_is_seen(void)
+{
+	static const uint32_t offsets[] = { 0, 2047, WATCH_HASH_PAGE_SIZE - 1 };
+	unsigned index;
+
+	for (index = 0; index < sizeof(offsets) / sizeof(offsets[0]); index++)
+	{
+		struct fixture f;
+		uint32_t before;
+
+		setup(&f);
+		watch_hash_protect(&f.watch, 2, 2);
+		watch_hash_begin_frame(&f.watch);
+		before = watch_hash_generation(&f.watch, 2, 2);
+		*byte_of(&f, 2, offsets[index]) += 1;
+		watch_hash_begin_frame(&f.watch);
+		CHECK(watch_hash_generation(&f.watch, 2, 2) > before);
+		teardown(&f);
+	}
+}
+
+static void test_hash_at_most_once_per_frame(void)
+{
+	struct fixture f;
+	uint32_t before;
+
+	setup(&f);
+	watch_hash_protect(&f.watch, 0, 0);
+	watch_hash_begin_frame(&f.watch);
+	before = watch_hash_generation(&f.watch, 0, 0);
+	CHECK(f.hashed_frame[0] == f.watch.frame);
+	*byte_of(&f, 0, 8) ^= 0xff;
+	CHECK(watch_hash_generation(&f.watch, 0, 0) == before);
+	watch_hash_begin_frame(&f.watch);
+	CHECK(watch_hash_generation(&f.watch, 0, 0) > before);
+	teardown(&f);
+}
+
+static void test_unwatched_page_is_not_hashed(void)
+{
+	struct fixture f;
+
+	setup(&f);
+	*byte_of(&f, 3, 0) ^= 1;
+	watch_hash_begin_frame(&f.watch);
+	CHECK(watch_hash_generation(&f.watch, 3, 3) == 0);
+	CHECK(f.hashed_frame[3] == 0);
+	teardown(&f);
+}
+
+static void test_forget_unwatches_and_bumps(void)
+{
+	struct fixture f;
+	uint32_t before;
+
+	setup(&f);
+	watch_hash_protect(&f.watch, 2, 2);
+	before = watch_hash_generation(&f.watch, 2, 2);
+	watch_hash_forget(&f.watch, 2, 2);
+	CHECK(f.watched[2] == 0);
+	CHECK(watch_hash_generation(&f.watch, 2, 2) > before);
+	teardown(&f);
+}
+
+static void test_range_returns_newest(void)
+{
+	struct fixture f;
+	uint32_t newest;
+
+	setup(&f);
+	watch_hash_protect(&f.watch, 0, 3);
+	watch_hash_begin_frame(&f.watch);
+	*byte_of(&f, 3, 5) ^= 1;
+	watch_hash_begin_frame(&f.watch);
+	newest = watch_hash_generation(&f.watch, 0, 3);
+	CHECK(newest == f.generation[3]);
+	CHECK(watch_hash_generation(&f.watch, 0, 2) < newest);
+	teardown(&f);
+}
+
+static void test_begin_frame_changes_serial(void)
+{
+	struct fixture f;
+	uint32_t serial;
+
+	setup(&f);
+	serial = f.current;
+	watch_hash_begin_frame(&f.watch);
+	CHECK(f.current != serial);
+	teardown(&f);
+}
+
+static void test_ranges_are_clamped(void)
+{
+	struct fixture f;
+
+	setup(&f);
+	watch_hash_protect(&f.watch, 2, 99);
+	CHECK(f.watched[2] == 1 && f.watched[3] == 1);
+	CHECK(watch_hash_generation(&f.watch, 5, 9) == 0);
+	watch_hash_forget(&f.watch, 7, 8);
+	teardown(&f);
+}
+
+int main(void)
+{
+	test_unchanged_page_keeps_generation();
+	test_write_is_seen_next_frame();
+	test_any_byte_is_seen();
+	test_hash_at_most_once_per_frame();
+	test_unwatched_page_is_not_hashed();
+	test_forget_unwatches_and_bumps();
+	test_range_returns_newest();
+	test_begin_frame_changes_serial();
+	test_ranges_are_clamped();
+	if (failures)
+		printf("%d failures\n", failures);
+	else
+		printf("all tests passed\n");
+	return failures != 0;
+}
@@ -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"}
+ ]
+}