Merge merge/upstream-oct18: OpenCE's high-resolution Xbox HUD, pause menu artwork, client-side mods, resampler, unsteered vehicles

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitattributes

@@ -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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -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.

.github/ISSUE_TEMPLATE/config.yml

@@ -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.

.github/workflows/build.yml

@@ -1,29 +1,41 @@
 name: Build
 
-# Debug and release builds of the native ports (Linux, Windows, Android) for
-# every pushed commit, uploaded as artifacts. tools/ci_build.py does each
-# build; see it for the options.
+# Debug and release builds of the native ports (Linux, Windows, Android) and
+# the web port for every pushed commit, uploaded as artifacts.
+# tools/ci_build.py does each build; see it for the options.
 #
 # Kept cheap:
 # - 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;
+# - Ringfall: Mjolnir VR builds only Android (the VR app): the Linux and
+#   Windows jobs are kept, off (if: false), so that upstream's changes to
+#   them still merge;
 # - artifacts are kept for three days.
 #
 # A successful build of main is also published as a GitHub release, the
 # newest marked latest, so that
 # https://github.com/<repository>/releases/latest/download/<file> always
-# gives the latest build; the last five are kept.
+# gives the latest build; the last five are kept. Its web build is then the
+# site on GitHub Pages (https://halocombatevolved.com/, port/web/README.md).
 on:
+  # (Ringfall: Mjolnir VR: main only; its branches are tried on the headsets
+  # from local builds)
   push:
+    branches: [main]
     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 }}
@@ -40,8 +52,14 @@ env:
 
 jobs:
   linux:
+    # (off: Ringfall: Mjolnir VR ships the Android app only)
+    if: ${{ false }}
     # 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 +68,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 +78,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_android_asm_convert.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 +143,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 +178,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
 
@@ -161,6 +198,8 @@ jobs:
           retention-days: 3
 
   windows:
+    # (off: Ringfall: Mjolnir VR ships the Android app only)
+    if: ${{ false }}
     # The runner image has LLVM, Python and Visual Studio's x86 libraries and
     # Windows SDK.
     runs-on: windows-2025
@@ -200,6 +239,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,12 +257,105 @@ 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
+
+  web:
+    # (off: Ringfall: Mjolnir VR ships the Android app only)
+    if: ${{ false }}
+    # Emscripten (emsdk, the version below, cached) builds the web port's
+    # site (port/web/README.md); the tests check its graph, the page's
+    # importer and service worker, its sockets, that it starts in a
+    # headless Chromium (with no game data, as far as the menus' map), and
+    # that two browsers join a room through a local MQTT broker.
+    runs-on: ubuntu-24.04
+    timeout-minutes: 40
+    env:
+      EMSDK_VERSION: 6.0.10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/emsdk
+          key: emsdk-${{ env.EMSDK_VERSION }}-${{ hashFiles('port/web/halo_sdl3.py') }}
+
+      - name: Install the toolchain
+        run: |
+          if [ ! -x ~/emsdk/upstream/emscripten/emcc ]; then
+            rm -rf ~/emsdk
+            git clone --depth 1 https://github.com/emscripten-core/emsdk.git ~/emsdk
+            ~/emsdk/emsdk install "$EMSDK_VERSION"
+          fi
+          ~/emsdk/emsdk activate "$EMSDK_VERSION"
+          sudo apt-get update -q
+          sudo apt-get install -y -q ninja-build ccache python3-pytest mosquitto
+
+      - uses: actions/cache@v4
+        with:
+          path: .ccache
+          key: ccache-web-${{ github.sha }}
+          restore-keys: ccache-web-
+
+      - name: Debug
+        run: |
+          source ~/emsdk/emsdk_env.sh
+          python3 tools/ci_build.py web debug
+
+      - name: Release
+        run: |
+          source ~/emsdk/emsdk_env.sh
+          python3 tools/ci_build.py web release
+
+      - name: Test
+        run: |
+          source ~/emsdk/emsdk_env.sh
+          node --test "port/web/tests/*.test.js"
+          python3 -m pytest -q tools/test_web_build.py
+
+      - name: Test in Chromium and Firefox
+        run: |
+          npm install --no-save --prefix "$RUNNER_TEMP/playwright" playwright@1.58
+          "$RUNNER_TEMP/playwright/node_modules/.bin/playwright" install --with-deps chromium firefox
+          NODE_PATH="$RUNNER_TEMP/playwright/node_modules" node port/web/tests/smoke.mjs dist/halo-web-release
+          NODE_PATH="$RUNNER_TEMP/playwright/node_modules" node port/web/tests/rooms.mjs dist/halo-web-release
+          # (the native builds' WebRTC, port/linux/src/p2p_webrtc.c, with both)
+          NODE_PATH="$RUNNER_TEMP/playwright/node_modules" node port/web/tests/webrtc_native.mjs chromium firefox
+
+      - name: Compile cache
+        run: ccache --show-stats
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: halo-web-debug
+          path: dist/halo-web-debug
+          include-hidden-files: true
+          retention-days: 3
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: halo-web-release
+          path: dist/halo-web-release
+          include-hidden-files: true
+          retention-days: 3
+
   release:
-    # The six builds as a release, tagged build-<run number> and marked latest
+    # The eight 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.
-    needs: [linux, android, windows]
+    needs: [android]
     if: ${{ github.ref == 'refs/heads/main' }}
     runs-on: ubuntu-24.04
     timeout-minutes: 15
@@ -232,6 +367,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 +382,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 +405,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 \
@@ -272,12 +457,47 @@ jobs:
             gh release delete "$tag" --cleanup-tag --yes
           done
 
+  pages:
+    # (off: Ringfall: Mjolnir VR ships the Android app only)
+    if: ${{ false }}
+    # The release's web build to GitHub Pages, which serves it at
+    # https://halocombatevolved.com/ (port/web/README.md, "Hosting"). Only
+    # main, only once every platform built and the release is out (the site
+    # and the release are one build), and a deployment is never cancelled
+    # halfway. The repository's Pages source must be GitHub Actions.
+    needs: [release]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: halo-web-release
+          path: site
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - id: deploy
+        uses: actions/deploy-pages@v4
+
   notify:
     # A Discord embed for the run, to the DISCORD_WEBHOOK secret (nothing
     # without it): green when every platform built, red when one did not,
     # with each platform's result, this run's release (main only), and links
     # to the latest release's builds.
-    needs: [linux, android, windows, release]
+    needs: [android, release]
     if: ${{ !cancelled() }}
     runs-on: ubuntu-24.04
     timeout-minutes: 5
@@ -288,6 +508,9 @@ jobs:
           LINUX: ${{ needs.linux.result }}
           ANDROID: ${{ needs.android.result }}
           WINDOWS: ${{ needs.windows.result }}
+          WEB: ${{ needs.web.result }}
+          PAGES: ${{ needs.pages.result }}
+          SITE_URL: https://halocombatevolved.com/
           RELEASE_TAG: ${{ needs.release.outputs.tag }}
           SERVER: ${{ github.server_url }}
           REPOSITORY: ${{ github.repository }}
@@ -310,15 +533,18 @@ jobs:
               *) echo "➖ Skipped" ;;
             esac
           }
-          if [ "$LINUX" = success ] && [ "$ANDROID" = success ] && [ "$WINDOWS" = success ]; then
+          if [ "$ANDROID" = success ]; then
             title="Build succeeded"; color=5763719
           else
             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)"
+            if [ "$PAGES" = success ]; then
+              release="$release, on [the site]($SITE_URL)"
+            fi
           else
             release="None (only a successful build of main makes one)"
           fi
@@ -328,6 +554,7 @@ jobs:
             --arg description "[\`${SHA:0:7}\`]($COMMIT_URL) $subject — $ACTOR ($BRANCH)" \
             --arg release "$release" --arg downloads "$downloads" \
             --arg linux "$(status "$LINUX")" --arg windows "$(status "$WINDOWS")" --arg android "$(status "$ANDROID")" \
+            --arg web "$(status "$WEB")" \
             --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
             '{embeds: [{
               title: $title, url: $url, color: $color, description: $description, timestamp: $timestamp,
@@ -335,6 +562,7 @@ jobs:
                 {name: "Linux", value: $linux, inline: true},
                 {name: "Windows", value: $windows, inline: true},
                 {name: "Android", value: $android, inline: true},
+                {name: "Web", value: $web, inline: true},
                 {name: "Release", value: $release},
                 {name: "Latest release builds", value: $downloads}
               ]

.gitignore

@@ -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

AGENTS.md

@@ -0,0 +1,227 @@
+# Notes for agents
+
+This repository ports the Halo: Combat Evolved decompilation (Xbox build
+01.01.14.2342, `cachebeta.exe`) to Linux, Windows, Android and the web. 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`), the mods folder (`port_mods.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, map sharing (`map_share*.c`), 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`), mods (`mods.c`, `mod_*.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/web/` | The web build: its runtime (`src/`: entry, sockets inside the page, memory watch), the page and its service worker (`site/`), the SDL port, tests |
+| `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`, `web_build.py`, `ci_build.py`, `web_serve.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`, `mods.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 web                      # build/web/site (Emscripten: port/web/README.md)
+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.
+- Web: the game is `wasm32` (also ILP32), run on a Web Worker; calls must
+  match their callee's type exactly (the link fails on a mismatch), and
+  WebGL 2 is ES 3.0. Run `ninja web` after changing what it compiles (as
+  for Android, and `port/web`). Refer to [port/web/README.md](port/web/README.md).
+
+### Defines
+
+| Define | Set by | Meaning |
+| --- | --- | --- |
+| `HALO_ANDROID` | Android | The app: its display, input, files and lifecycle |
+| `HALO_GLES` | Android, web | The OpenGL ES renderer |
+| `HALO_ARM64_GUEST` | Android | The guest's ABI (ILP32 AArch64) |
+| `HALO_WEB` | Web | The browser: its frames, storage, sockets and WebGL 2's limits (with `HALO_GLES`, not `HALO_ANDROID`) |
+| `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_mods.py                      # mods played over a map (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
+python -m pytest -q tools/test_web_build.py                 # the web build's graph, sockets, menus
+node --test "port/web/tests/*.test.js"                      # the web page's importer and service worker
+node port/web/tests/webrtc_native.mjs chromium firefox      # the native builds' WebRTC with browsers (Playwright)
+```
+
+`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.
+- Internet play is the same code in every build, the web's too: a browser's
+  tunnel is a WebRTC data channel (`port/web/src/web_p2p.c`), which the
+  native builds take on their tunnel's socket (`p2p_webrtc.c`, `posix_dtls.c`).
+  Check a change with both (`port/web/tests/webrtc_native.mjs`, and with the
+  maps `port/web/tests/internet.mjs`).
+- 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, map sharing, 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, map sharing, 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/web/README.md](port/web/README.md) | The web build, the page, the game data in the browser, limits, how it operates, hosting on GitHub Pages |
+| [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 |
+| [docs/mods.md](docs/mods.md) | Mods: folders of Halo PC tag files whose sounds, bitmaps, text and models play over a map's on one machine |
+| [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 |

AUTHORS.md

@@ -0,0 +1,23 @@
+# 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`).
+- **The controller's A, B, X and Y buttons** (the menus' button icons and
+  the HUD messages'): redraws by saulob (`port/assets/buttons`).
+- **The high-res HUD** (its meters, icons, scopes and messages, and the
+  weapons' reticles): redraws by MrBruh (`port/assets/hud`), based on
+  reference photos by Aerocatia. The sniper rifle's zoom labels (2x, 10x)
+  are set in Overpass (`port/assets/fonts`).
+
+## 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`).
+- **The Mods menu's warning icons** (a mod out of its requested order, and
+  a mod that cannot be played): `triangle-alert` and `circle-x` from
+  [Lucide](https://lucide.dev) 1.53.0, under the same licence.

README.md

@@ -1,140 +1,203 @@
-# 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. The game plays in the disc's language; on the European disc in
+  Spanish and Italian it takes your headset's language (else the first).
 
-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).
+The game updates itself: when a new version is out, it is downloaded
+while you play and used from the next start on. 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.
+- **Voice chat** in network games: hold the grip of the hand without the
+  weapon to talk (not while it holds the weapon or the Warthog's wheel).
+  The *BUTTONS* page can put push to talk on another button.
 
-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).

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
+<in@fishtank.com>.*
+
+## 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.

configure.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 # root build script: writes build.ninja for the native ports (Linux, Windows,
-# Android)
+# Android) and the web port
 
 import argparse
 import io
@@ -12,7 +12,8 @@ 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.web_build import generate_web_build, web_configure_inputs
 from tools.windows_build import generate_windows_build, windows_configure_inputs
 
 # arguments
@@ -31,7 +32,13 @@ parser.add_argument(
 parser.add_argument(
     "--release",
     action="store_true",
-    help="release builds (Linux, Windows, Android): assertions are not checked",
+    help="release builds (Linux, Windows, Android, web): 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",
@@ -44,7 +51,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",
@@ -73,7 +84,16 @@ parser.add_argument(
     type=str,
     help="clang with the arm64_32 target for the Android guest (default: clang)",
 )
+parser.add_argument(
+    "--web-emcc",
+    type=str,
+    help="Emscripten's emcc for `ninja web` (default: emcc on the PATH, then EMSDK's or ~/emsdk's)",
+)
 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,12 +101,14 @@ 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,
     port_pgo_profile=args.pgo_profile,
     android_ndk=args.android_ndk,
     android_guest_cc=args.android_guest_cc,
+    web_emcc=args.web_emcc,
 )
 
 
@@ -112,6 +134,7 @@ n.newline()
 generate_linux_build(n, sln)
 generate_android_build(n, sln)
 generate_windows_build(n, sln)
+generate_web_build(n, sln)
 
 n.comment("Reconfigure on change")
 n.rule(
@@ -129,6 +152,7 @@ n.build(
         *linux_configure_inputs(),
         *android_configure_inputs(),
         *windows_configure_inputs(),
+        *web_configure_inputs(),
     ],
 )
 n.newline()

docs/OPENCE_README.md

@@ -0,0 +1,209 @@
+> 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, Android and the web
+
+[![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, Android and web browsers. 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) |
+| Web | [halocombatevolved.com](https://halocombatevolved.com/) (or [halo-web-release.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-web-release.zip) for your own server) | [halo-web-debug.zip](https://github.com/OpenCommunityEdition/OpenCE/releases/latest/download/halo-web-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). The web site offers
+each new build when it is out.
+
+Each build of the `main` branch that passes on all four platforms is a new
+release, and the web site then plays it. 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.
+
+### Arch-based Linux Distributions
+
+The above Linux binary release is available on the [AUR](https://aur.archlinux.org/packages/opence-bin).
+
+## Game data
+
+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.
+
+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). On
+the web, the page copies `maps/` out of the disc image into the browser's
+storage for the site; nothing is uploaded. Refer to
+[port/web/README.md](port/web/README.md).
+
+## Mods
+
+Mods are folders of Halo PC tag files, as the Halo Editing Kit and Invader
+write them, in `mods/` next to `maps/`: texture, sound, text and model packs
+that play over the maps' on your machine only, in any game. Each has a
+`mod.toml`. Every mod in the folder is on; the main menu's Mods turns them
+off and on and sets the order they load in.
+Refer to [docs/mods.md](docs/mods.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) |
+| Web (WebAssembly, WebGL 2, SDL3; desktop Chrome, Edge and Firefox) | [port/web/README.md](port/web/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 and browsers can play in the same
+  game. On a local network, the native builds play system link; browsers
+  play each other in rooms, over WebRTC
+  ([port/web/README.md](port/web/README.md)).
+- An invite link, or the server browser, lets a machine join a game on the
+  internet, browsers too: a native build takes a browser's WebRTC
+  ([port/linux/README.md](port/linux/README.md), "Browsers"). 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` |
+| `ninja web` | `build/web/site/`, the web site (`python tools/web_serve.py` serves it) |
+
+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". |
+| `--web-emcc PATH` | The Emscripten `emcc` for `ninja web` (else the one on the PATH, or `~/emsdk`'s). |
+
+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`.

docs/custom_edition_caches.md

@@ -0,0 +1,656 @@
+# 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.
+
+Maps keep their names. A network game's level name is the map's own
+(`custom_maps\hugeass`), and its game record's map version is the first 32
+bits of the map's hash (`port/linux/game/map_share_files.c`), so a client
+plays its file of that name and version, whatever else it has of the name
+(`custom_edition_map_find_version`); a player without it downloads it
+(`port/linux/NETCODE.md`, "Map sharing"). A download beside another version
+of its name is named `hugeass_0e2b3ee4.map`, the first 8 hexadecimal digits
+of its hash after `_`, and the menus show it as "Hugeass (2)". A level name
+without the hash (a saved last map, a test's) finds the one map of that
+name in `custom_maps`, and one with it (an earlier build's, which named
+every map so) the map given its name back. Maps in a Custom Edition
+install's folder are found and shared as `custom_maps`' are.
+
+A map needs only the resource maps that hold its tags: its tag index says
+which (`cache_file_resource_maps_needed`, `cache_file_formats.c`: a tag
+whose entry's word at 0x18 is set is held whole by `bitmaps.map` for a
+bitmap, `sounds.map` for a sound, `loc.map` for a font, string list or HUD
+message text). A map without such tags of a kind plays without that
+resource map; one that lacks a resource map it needs is refused, saying
+which.
+
+### 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 map's hash's first 32 bits 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, at most 64000 of each (the game's limit, to which the validator
+   cuts a material's counts), 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),
+and a tag name that lies in any tag's block or data is emptied (what the
+game writes there could take away its end). 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 with a maps folder missing the host's Xbox map was shown the
+error and left the game. A joining machine without `hugeass` (or without
+`sounds.map` and `loc.map` too) downloaded them and played (map sharing,
+`port/linux/NETCODE.md`): in the lobby, into a game in progress, from the
+host and another player at once with a second machine downloading beside it
+(on loopback, and through internet play's tunnels with a local broker), each
+file the same as the host's; with `network.map_download` off, or a host with
+`network.map_share` off, it was shown the error and left.
+
+### 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, with
+  added bounds checks: `port/third_party/stb_vorbis`) 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.

docs/mods.md

@@ -0,0 +1,329 @@
+# Mods
+
+A mod is a folder of Halo PC tag files that the game plays over a map's own
+tags on your machine, as a resource pack does: sounds (a high-res audio
+pack), bitmaps (a texture pack, a HUD redraw), text (a translation) and
+models (higher-detail weapons, vehicles and scenery). Only the machine that
+has a mod plays it. Nothing of a mod is sent to another machine, and a mod
+changes nothing that the machines of a network game must agree on, so you
+can play with mods in any game, with players who have other mods or none. (A host's mod sounds of other lengths change how long
+the host's scripts and AI wait for dialogue to end; the host decides those
+for every machine, so they still agree.)
+
+The game's code is `port/linux/game/mods.c` (with `mod_sounds.c`,
+`mod_bitmaps.c`, `mod_strings.c` and `mod_models.c`, one for each kind of
+tag) and `port/linux/src/port_mods.c` (the mods folder and its files).
+
+## A mod's folder
+
+The mods are in the `mods` folder of the data root (the folder with
+`maps/`; on Android the app's data folder, on the web the browser's storage
+for the site). Each mod is a folder in it, with a `mod.toml` and a `tags`
+folder:
+
+```
+mods/
+  hd_audio/
+    mod.toml
+    tags/
+      sound/sfx/weapons/assault rifle/fire.sound
+      sound/dialog/...
+  german/
+    mod.toml
+    tags/
+      ui/hud/hud_item_messages.unicode_string_list
+```
+
+The files in `tags` have the paths of the tags they replace: a tag's name,
+then its group's extension, as the Halo Editing Kit and Invader keep them.
+`tags/sound/sfx/weapons/assault rifle/fire.sound` replaces the sound tag
+`sound\sfx\weapons\assault rifle\fire` of every map that has one. Names are
+not case-sensitive. The game only looks up the names of the map's tags among
+a mod's files: a mod cannot add tags, and no tag name of a map makes a path
+outside the mod.
+
+`mod.toml` says what the mod is. Every key is optional:
+
+```toml
+name = "High-res audio"       # what the Mods menu shows (else the folder's name)
+id = "hd_audio"               # what other mods name it by (else the folder's name)
+version = "1.0"
+authors = ["Someone", "Someone else"]   # or one string
+description = "The game's sounds at 44 kHz"
+maps = ["a10", "bloodgulch"]  # the maps it is for, by their files' names (else every map)
+load_after = ["hd_textures"]  # mods it plays over: they load before it
+load_before = ["fixes"]       # mods that play over it: they load after it
+incompatible = ["other_audio"]  # mods it cannot be played with
+format = 1                    # the mods' format it is made for
+```
+
+`load_after`, `load_before` and `incompatible` name other mods by their `id`
+or their folder's name, not case-sensitive. A mod they name that is not in
+the mods folder is passed over. `maps = []` is every map.
+
+A folder without `mod.toml` is not a mod. A mod made for a later `format`
+than the build's, or whose `maps` names no map, is not played. The game
+logs anything else wrong in `mod.toml` (an unknown key, a value of the
+wrong type) and uses the rest; a `mod.toml` that is not TOML at all is
+logged, and the mod played without what it says.
+
+The game's log is its output: the terminal on Linux, `halo.log` beside
+`halo.exe` on Windows, logcat on Android, and the page's log on the web.
+
+Limits: 256 mods, folder names of 63 bytes at most, 262144 files in all, 24
+folders deep under `tags`, and 64 maps in a mod's `maps`.
+
+## The load order
+
+Every mod in the mods folder is on until you turn it off. The mods load in
+an order, and where two mods have a file for the same tag, the one loaded
+later plays.
+
+- The default order is the folders' names in alphabetical order (not
+  case-sensitive), except that the mods a mod must load after (those it
+  asks to load after, and those that ask to load before it) are taken to
+  just before it. Mods that ask in a ring (a after b, b after a) load
+  alphabetically, and the game's log says so.
+- The main menu's **Mods** (in the PC version's menus, `display.menus =
+  "pc"`, the default) is laid out as the game lobby is: the mods on the
+  left as a resource pack list has them, the one at the top playing over
+  all those below it (the load order upside down: the mod loaded last is at
+  the top), and the chosen mod's details in the frame on the right (its
+  name, what is wrong with it, whether it is on, its priority, 1 the top,
+  and its version, authors, folder, maps and description). Choosing a mod
+  (A, or a click on the chosen one: the first click chooses it) turns it on
+  or off (ON, OFF); left and right, or **Move up** and **Move down**, move
+  the chosen mod (up: over one more mod). **OK** keeps the order and plays
+  it at once (on a map that is loaded, too); **Cancel** leaves it as it was.
+- A warning sign beside a mod means it is on the wrong side of a mod it
+  asks to load before or after (both on): a mod that loads after another is
+  above it in the menu. A red cross means a mod that is on says it cannot be
+  played with this one, or that it cannot be played at all (made for a later
+  build, or its `maps` names none): it stays off. The details say which.
+
+The menu keeps the order, and the mods turned off, in `mods/load_order.toml`,
+by the mods' folders' names:
+
+```toml
+order = ["german", "hd_audio", "hd_textures"]
+disabled = ["hd_textures"]
+```
+
+A mod added to the folder later is put where the default order puts it,
+after the mod before it there (but on the side it asks for of the mods it
+names), and is on. A mod gone from the folder is left out. When the file
+cannot be written, the game says so in its log and keeps the order until it
+quits.
+
+### Mods that cannot be played together
+
+When a mod that is on names another that is on as `incompatible`, the game
+asks as it starts, before the window opens:
+
+- **Play anyway** plays them all (closing the box does too);
+- **Turn off ...** turns off the mods named as incompatible (if mod A says
+  it cannot be played with mod B, B is turned off), and keeps that in
+  `load_order.toml`;
+- **Quit** closes the game.
+
+The Mods menu turns them on again. On the web, **Quit** starts the page
+again. A run nobody watches (`debug.hidden_window`, `debug.null_renderer`,
+`debug.exit_after` or `debug.network_test`) is not asked: it plays them all,
+and the game's log says which conflict.
+
+At the console:
+
+| Command | What it does |
+| --- | --- |
+| `mods_list` | Lists the mods in the mods folder in their load order, and which are on, then how many of the map's string lists, bitmaps, sounds and models the mods play. |
+| `mods_reload` | Finds the mods again and reads their files again: a changed file is read again (one that now fails a check leaves what was played before), a new one is played, and the map's tag comes back for a file that is gone. If a sound changed, all sounds stop. It does nothing while `mods_enable false`. |
+| `mods_enable false` | Plays the map's own tags until `mods_enable true` or the next map. |
+
+These commands work in any game, a client's too: they change nothing of the
+game.
+
+### Getting a mod onto each platform
+
+- **Linux, Windows**: put the mod's folder in `mods/` next to `maps/`.
+- **Android**: put it in `mods/` in the app's data folder,
+  `/sdcard/Android/data/com.halo.decomp/files/mods`, for example with
+  `adb push hd_audio /sdcard/Android/data/com.halo.decomp/files/mods/`.
+- **Web**: on the page, **Mods**, **Add a mod folder…** copies a mod's
+  `mod.toml` and `tags` folder into the browser's storage for the site.
+  **Remove** deletes it again.
+
+## What a mod can replace
+
+The game plays these groups from a mod. It does not read the files of any
+other group (a `.weapon`, `.vehicle`, `.model_collision_geometry` or
+`.scenario`, for example): they would change what the machines of a network
+game must agree on.
+
+| Group | Extension | What it is |
+| --- | --- | --- |
+| Sound | `.sound` | Sounds, music and dialogue |
+| Bitmap | `.bitmap` | Textures, sprites, the HUD's pictures |
+| Unicode string list | `.unicode_string_list` | The text the game shows |
+| String list | `.string_list` | Other text |
+| Model | `.gbxmodel` (Halo PC's), `.model` (the Xbox's) | What objects look like: weapons, first-person weapons and arms, vehicles, scenery, characters |
+
+A file must be a Halo PC tag file of its group, as the Halo Editing Kit's
+tools and Invader write them (a model also as `invader-extract` writes an
+Xbox map's: `.model`). The game checks every count, size and offset
+in it against the file, and every value against what the game reads, before
+it uses the file. A file that fails a check is left out (the map's tag
+plays), and `debug.txt` and the console say why.
+
+### Sounds
+
+- The samples can be 16-bit PCM, Xbox ADPCM or Ogg Vorbis, mono or stereo,
+  at 22 or 44 kHz. The game converts them to the Xbox ADPCM that it plays,
+  as it does for Custom Edition maps: mono at 22 kHz, stereo at its own rate.
+- Empty values are filled in as a map's build fills them in: the defaults
+  of the sound's class, the playback rates and the bend.
+- A sound must have permutations: a file with an empty pitch range (some
+  Halo PC translations have them) is left out.
+- A permutation must fit in a block of the sound cache (one sound's samples:
+  `MAXIMUM_SOUND_DATA_SIZE`).
+
+### Bitmaps
+
+- A bitmap's types and formats are those the game draws: 2D, 3D and cube
+  maps; A8, Y8, AY8, A8Y8, R5G6B5, A1R5G5B5, A4R4G4B4, X8R8G8B8, A8R8G8B8,
+  DXT1, DXT3, DXT5 and P8 bump. Sides are 4096 at most (512 for a 3D
+  bitmap). A bitmap that is not a power of two on each side is drawn
+  linear, as a Custom Edition map's is: it must be an uncompressed 2D
+  bitmap.
+- One bitmap's pixels may take a quarter of the texture cache: 64 MB on
+  Linux and Windows, 5.5 MB on Android and the web (a 2048 x 2048 DXT5 with
+  its mipmaps fits on all of them).
+- A bitmap replaces the map's bitmap of its name, and the map's other tags
+  use it as the map's: it must have at least as many bitmaps, of the same
+  types, and as many sequences, each with at least as many sprites. It can
+  be larger: a redraw at twice the size is drawn at the map's size, sharper.
+- The HUD draws a bitmap at its own size. So for each HUD element that draws
+  a mod's bitmap, the game scales the element by the map's size of what it
+  draws (its sprite, or with no sprites its bitmap) to the mod's, when that
+  is the same ratio for all of them. A bitmap the HUD draws that is not the
+  map's redrawn so (Halo PC's HUD bitmaps lay their sprites out to other
+  sizes) is left out. The HUD's digits can be the map's size or twice it.
+- The menus draw a bitmap in their widgets' bounds, whatever its size.
+- Halo PC keeps the channels of a model shader's multipurpose maps and of
+  the HUD's meters in another order than the Xbox. The game finds those
+  bitmaps among the mod's and draws them in the Xbox's order, as it does for
+  Custom Edition maps (`custom_edition_bitmaps.c`).
+- The pixels are read from the file when the texture cache loads them, not
+  kept in memory.
+
+### Text
+
+- A list keeps the map's number of strings: a mod's strings past it are
+  left out, and the map's own strings stay where the mod's list is shorter.
+- The game uses many strings as the format of what it prints
+  (`%s was killed by %s`). A mod's string replaces the map's only if it has
+  the same conversions in the same order (`%s`, `%d`, ...); otherwise the
+  map's string stays. A translation keeps the conversions of the original.
+- Unicode strings are UTF-16, as the tool writes them.
+- The main menu is the port's own (the PC version's menus, `port/assets/menus`),
+  whose text is in tags named `pc\...`. A mod's `ui\shell` lists change the
+  Xbox's menus (`display.menus = "xbox"`) and the text shown while playing
+  (HUD messages, the multiplayer messages, the pause menu).
+
+### Models
+
+A model is more than what is drawn: its nodes (its skeleton) are what its
+animations move, its markers are where projectiles leave a weapon, where a
+unit sits and where things attach, and its regions and permutations are what
+damage and an object's variant choose among. The machines of a network game
+agree on those, so a mod's model must have the map's:
+
+- the same nodes: their names, hierarchy and default positions;
+- the same markers: their names, regions, permutations, nodes, positions
+  and rotations (on the model's permutations, as the Halo Editing Kit keeps
+  them, or on the model, as a map does);
+- the same regions and permutations: their names and flags.
+
+Positions and rotations may differ from the map's by 0.001 at most (a model
+exported again is not always bit for bit the map's). Only what is drawn is
+the mod's: the geometries, their parts and vertices, which geometry each
+permutation draws at each detail level, the detail levels' cutoffs, the
+base map's scale, and which shaders each part is drawn with. A detail level
+the map draws must draw one of the mod's geometries, and one the map draws
+nothing at stays so. Every shader must be one the map has (a mod cannot add
+tags); a mod's bitmaps can redraw them.
+
+The model is checked against each map's own model of its name as that map
+loads. On a map whose model of that name has other nodes, markers or
+regions (a custom map's own assault rifle, say), or lacks a shader the mod
+names, the mod's model is left out and the map's drawn; the mod's other
+files still play there. `maps` in `mod.toml` keeps a mod to the maps it is
+made for.
+
+- Where a mod has both, its `.gbxmodel` plays; otherwise the file of the mod
+  loaded later, whichever its format.
+- What the tool works out as it builds a map is worked out as it does: a
+  part's strip is its triangles block, its centroid's nodes are its most
+  weighted, its links of 0 to the parts drawn before and after it are none,
+  a base map scale of 0 is 1, and a model whose tag asks for it has the
+  normals of its vertices that share a position blended. The vertices are
+  compressed as the game draws them.
+- A part's links to the parts drawn before and after it (for transparency)
+  must not go round.
+- A model of 44 nodes or more (the renderer skins 43 at once; only Custom
+  Edition maps' have so many) is drawn a part's own nodes at a time, as a
+  Custom Edition map's is: a part's vertices may name 22 nodes at most.
+- The collision geometry, the animations and the object's tag are the map's:
+  a larger weapon still hits and is hit where the map's does, and an object
+  is still left undrawn by the map's bounds of it (a much larger model may
+  vanish at the screen's edges).
+- Every model made from a file is kept until the map changes, a file edited
+  and read again by `mods_reload` too, and counts against the mods' memory.
+
+### Shaders
+
+A model's parts can be drawn with a shader of every group Halo PC has but
+one: `shader_transparent_chicago_extended`, which Gearbox added for Halo PC.
+The Xbox game does not have it, so do not use it: use a
+`shader_transparent_chicago` shader instead. (A Custom Edition map's
+chicago extended shaders become chicago shaders as the map loads, keeping
+only their four-stage maps: see
+[custom_edition_caches.md](custom_edition_caches.md).) As for every
+shader, it must be one the map has.
+
+## Making a mod
+
+1. Get the tags you want to change as tag files. `invader-extract` extracts
+   them from a map, and the Halo Editing Kit's tags are Halo PC's own.
+2. Change them with the Halo Editing Kit or Invader (`invader-bitmap`,
+   `invader-sound` and `invader-model` build bitmaps, sounds and models from
+   images, audio files and JMS files). Keep each tag's name.
+3. Put them in `tags/` of a folder in `mods/`, with a `mod.toml`.
+4. Load a map (a new mod is on). `mods_reload` at the console reads the
+   files again as you change them, without loading the map again.
+
+`debug.txt` has a line for every file the game leaves out, and why, and a
+summary of what each kind of tag plays from the mods:
+
+```
+mods: 9 string lists from their files (9 new), 0 given back, 0 left out
+mods: 66 HUD placements scaled to draw larger bitmaps at the map's size
+mods: 354 bitmaps from their files (354 new), 0 given back, 6 left out
+mods: 313 sounds from their files (313 new), 0 given back, 2 left out
+mods: 4 models from their files (4 new), 0 given back, 1 left out
+```
+
+## How it operates
+
+- When a map's tags load, at `mods_reload` and at the Mods menu's **OK**,
+  the game lists the files of the mods that are on, once, in a table of
+  their tag paths. Each of the map's sound, bitmap, string list and model
+  tags is looked up in it.
+- A tag replaced by a mod takes the file's values in place, so everything
+  that holds the tag keeps it, and the map's own values come back when the
+  file goes. A sound playing or a texture in the cache is never changed
+  under the game: before a reload changes anything, the sounds stop and the
+  caches let go of what they hold.
+- The mods' tags keep at most 512 MB in memory (192 MB on Android and the
+  web): their files, their sounds' samples, their bitmaps' tags and their
+  models' geometry.
+- A Custom Edition map takes mods as an Xbox map does.

port/android/README.md

@@ -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,19 @@ 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` |
+| Mods (`docs/mods.md`) | `mods`: `adb push <mod folder> /sdcard/Android/data/com.halo.decomp/files/mods/`; the main menu's Mods orders them and turns them off |
 | 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 +131,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 +226,13 @@ 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. |
+| `display.shader_cache` | `true` (the default): the linked shader programs are kept in `shader_cache` in the data folder (their binaries, the driver that made them and their sources), and each map's list of the programs it drew with; as a map loads, the programs on its list are made ready, so that its first frames do not wait for the driver to compile them. A driver update compiles them again from the kept sources. `false`: each program is compiled the first time it is drawn. The folder may be deleted at any time. |
+| `display.shader_worker` | `true` (the default): the shader programs are made on a thread of their own, whose GL context shares the game's (loaded from the shader cache, or compiled), and drawn with once there (`debug.shader_warm_up`: `"worker"`, `"load"` on the game's thread as a map loads, or `"off"`); a draw whose program is not made yet is left out for the frames it takes, and the frame does not wait. As a map loads, its own programs and then every map's (`shader_cache/all.txt`) are asked for. `false`: each is made on the game's thread when first drawn with. |
 | `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 +266,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 +294,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 +310,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 +358,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 +368,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
@@ -266,7 +389,9 @@ The guest is the game, the platform layer and a small runtime:
    AArch64 target of clang. The options `-U__APPLE__` and
    `-fno-define-target-os-macros` hide the Darwin environment.
 2. `tools/android_asm_convert.py` changes the Mach-O assembly to ELF
-   assembly.
+   assembly. It renames symbols, but keeps string literals (`.ascii`,
+   `.asciz`) byte for byte: they hold tables as well as text
+   (`tools/test_android_asm_convert.py`).
 3. The AArch64 assembler makes the objects.
 4. `ld.lld` links the objects with `guest/guest.ld` to a static image,
    `build/android/halo_guest.elf`, at a fixed address above the Xbox memory
@@ -287,7 +412,7 @@ and supplies the thread pointer and TLS.
 
 - Reserves the address space of the guest below 4 GB: the Xbox memory at
   `0x80000000`, the image, and pools for the memory of the guest
-  (`host/host_memory.c`).
+  (`host/host_memory.c`). Refer to "The fixed addresses".
 - Loads the image and fills its import table (`host/host_loader.c`).
 - Starts the `main` of the game and each guest thread on a stack in guest
   memory, because ILP32 code keeps stack addresses in 32-bit registers
@@ -295,8 +420,9 @@ and supplies the thread pointer and TLS.
 - Gives the audio callback of SDL to a thread with a guest stack
   (`host/host_sdl.c`).
 - Does the calls of the guest: system calls (`host/host_syscall.c`), SDL
-  (`host/host_sdl.c`), OpenGL ES (`host/host_gl.c`), and the file and socket
-  functions of `port/linux/src/posix_*.c`.
+  (`host/host_sdl.c`), OpenGL ES (`host/host_gl.c`), and the file, socket,
+  UPnP and DTLS functions of `port/linux/src/posix_*.c` (DTLS with Mbed TLS,
+  for internet play with browsers: `posix_dtls.c`).
 
 The guest calls the host through stubs (`tools/android_imports.py`). The
 two ABIs use the same registers for 32-bit integers, floats and pointers.
@@ -304,6 +430,49 @@ two ABIs use the same registers for 32-bit integers, floats and pointers.
 `port/linux/src/gl.h`. `tools/android_posix_stubs.py` makes the stubs of the
 `posix_*` functions, which copy the `errno` of the host.
 
+### The fixed addresses
+
+The guest needs the Xbox memory at `0x80000000` to `0x88000000` and the
+image above it, to `0x8c000000`. The cache files contain pointers to these
+addresses. The Java runtime of Android (ART) also reserves its spaces below
+4 GB. On some devices, for example handhelds with a large Java heap (the
+AYN Thor, the Retroid Pocket), ART's large object space covers
+`0x80000000`. ART fills that space from its bottom, so the part at
+`0x80000000` is usually empty.
+
+Thus:
+
+1. The game operates in a process of its own (`:game`), with a fresh Java
+   heap. The launcher, the import of a disc image and an earlier game do
+   not leave objects there.
+2. At the start of that process, `HaloApplication` loads `libmain.so`. Its
+   `JNI_OnLoad` reserves the fixed addresses before the Java side
+   allocates large objects.
+3. If ART's large object space is in the way, the host takes back only the
+   part that covers the fixed addresses, and only if no page of it is in
+   use (`/proc/self/pagemap`, or `mincore` and the swap of that part if
+   the device refuses `pagemap`). The host never takes the other spaces of
+   ART.
+
+If the addresses are not available, the game shows a message, and writes
+the mappings below 4 GB to `memory_map.txt` in the data folder and to the
+log.
+
+To test the reclaim on any device, set a system property before you start
+the game. The app then puts a stand-in for ART's large object space over
+the fixed addresses:
+
+- `adb shell setprop debug.halo.art_overlap idle`: the stand-in is empty
+  at `0x80000000`. The log shows `reclaimed idle ART range`, and the game
+  starts.
+- `adb shell setprop debug.halo.art_overlap busy`: a page at `0x80100000`
+  is in use. The game shows the message and writes `memory_map.txt`.
+- Add `-nopagemap` to either value (`idle-nopagemap`) to test as on a
+  device that refuses `/proc/self/pagemap`. Add `-swapped`
+  (`idle-nopagemap-swapped`) to also move the objects of the stand-in to
+  swap; with `busy`, the page in the fixed addresses too.
+- `adb shell setprop debug.halo.art_overlap ""`: normal operation.
+
 ### OpenGL ES
 
 The renderer (`port/linux/src/d3d8_gl.c`) uses OpenGL ES 3.0, and some
@@ -321,7 +490,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 +517,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,13 +554,25 @@ 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
 
 - Bink video is not available. The game skips the movies.
 - 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.
+  `0x80000000` to `0x8c000000`. If ART uses them, the app shows a message
+  (refer to "The fixed addresses").
+- 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.

port/android/STEAM_FRAME.md

@@ -0,0 +1,180 @@
+# 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.
+
+The game updates itself: while it runs, its launcher looks for a newer
+release, fetches it and puts it in place as the next start begins
+(`steam_frame_launch.sh`; `update.auto = false` in `config.toml` stops it;
+`launcher.log` says what it did). Opening the same file again updates it
+too (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.

port/android/VR_ROADMAP.md

@@ -0,0 +1,598 @@
+# 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 | The eyes drawn one by one (both at once, multiview, only with `debug.multiview`: its eyes did not always fuse, see the open points); 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 29, 2026-10-14): 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 |
+| Voice chat | Push to talk on any button (`vr.button_talk`, BUTTONS page; the free hand's grip by default, sending nothing while it reaches for the foregrip or the wheel), open mic, off (2026-10-13) |
+| Builds | The Android build's assembly conversion (`tools/android_asm_convert.py`) keeps string data as it is: strings and tables starting with "_" or holding \" lost a "_" (Opus's pulse cache among them: the Steam Frame's crashes in online games while talking), 2026-10-13 |
+| Languages | The European disc in Spanish and Italian (a maps folder for each, `maps_es` and `maps_it`, none called `maps`) imported on the Quest and the Steam Frame: the headset's language's, its language the game's and the menus' (`maps/language.txt`, unless `game.language` is set), 2026-10-17; not yet tried with that disc |
+| 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; moving by swinging the arms (in place of the stick, never faster than it: online too), and a sprint by swinging them harder (faster than the game allows: offline only) | 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). Arm swinging and its offline sprint still open |
+| 5 | Later: multiview again (both eyes in one pass, half the drawing's CPU cost): find why its eyes do not fuse in big online games on the Quest 3 (and now and then on the Steam Frame), then turn it back on | open: off by default since 2026-10-16 (`debug.multiview`); findings in the open points |
+| 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` | `"auto"` (default, branch `fix/vr-frame-hitches`), `"low"`, `"medium"`, `"high"`, `"max"` |
+| `vr.foveation` | `"off"` (default), `"low"`, `"medium"` (the Quest only; branch `fix/vr-frame-hitches`) |
+| `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, melee and push to talk each go on one of eight
+  buttons: A, B, X, Y, the move stick's click, the turning stick's, the
+  weapon hand's grip, the free hand's grip. Moving an action to a button
+  swaps it with the action there, so none is ever left without one.
+- The free hand's grip as a button (`free_grip_down`): pressed once held
+  0.15 s at the foregrip's threshold, and not at all while it holds the
+  weapon's foregrip or the Warthog's wheel (taken in that time, the press
+  is theirs until the grip opens).
+- The triggers, 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).
+
+## Frame hitches and GPU time (built: branch `fix/vr-frame-hitches`)
+
+Measured on the Quest 3 (2026-10-12; 90 Hz, multiview, graphics "high",
+full body, a 15-bot game on Blood Gulch): the game's CPU work 5-6 ms a
+frame; the app's GPU time 5.5-6.4 ms (`xr: metrics`), the same with
+foveation off, low, medium and high: **the GPU is not the bottleneck**.
+The doubled pictures come from single long frames: shader programs compiled
+in a frame (29 new ones in a 794 ms frame 22 s into a match, single ones
+18-64 ms), draws of 254 ms (the first frame in a map) and 74 ms with
+nothing compiled (most likely the driver making a program's variants at
+its first draw), and the menus' PNG pictures (7 in 108 ms).
+
+What the branch has:
+
+| Part | What |
+| --- | --- |
+| Long frames | `VR: long frame N ms: input, ticks, camera, draw, present; shaders compiled or linked, programs from the cache; textures uploaded, menu pictures, render targets; draw calls N ms, the slowest N ms (vertex program, program key); N draws left out waiting for their programs`. The 5 s report counts the draws left out |
+| GPU time | XR_META_performance_metrics on with `vr.log_performance`: `xr: metrics (mean/most) app/gpu_frametime=... compositor/dropped_frame_count=...` |
+| Foveation | `vr.foveation` "off" (default) / "low" / "medium" on the MORE page (GL_QCOM_texture_foveated, the eyes only, lens centres); "high" taken out (it drew a grey rectangle below the player). Kept for later, no gain measured |
+| Shader cache | `display.shader_cache`: programs kept in `shader_cache/` (binary, driver, sources); each map's list (`maps/<map>.txt`) and every map's (`all.txt`) |
+| Worker | `display.shader_worker` (default true): programs made on a thread with a GL context sharing the game's (`gl worker: running`), from the cache's binary or compiled; a draw whose program is not made yet is left out for those frames, the frame never waits. As a map loads, its programs and then every map's are asked for |
+| Warm-up | `debug.shader_warm_up`: "worker" (default: each program drawn with once on the worker into a small target of the eyes' kinds), "load" (the map's programs drawn with on the game's thread as it loads), "off" |
+| Menus | The PC menus' pictures decoded on a thread of their own, drawn transparent for the frames that takes |
+
+Second Quest test (latest build): the worker works, no long frame after the
+map's first frames (245 ms and 72 ms there, each one draw of 67-75 ms with
+vertex program 4). But doubled pictures in spells of seconds with the GPU
+at 9-13 ms a frame (GPU% 0.91-0.94, 4-37 stale frames a second), 5-7 ms in
+between: "high" is too much for 90 Hz in heavy scenes, "medium" holds.
+Hence:
+
+| Part | What |
+| --- | --- |
+| Graphics "auto" | `vr.graphics = "auto"`, the new default (Graphics row: Auto): "high" while the GPU keeps up. Past 4/5 of the frame (8.9 ms at 90 Hz) for a quarter second it leaves out the next steps (shield glow, shadows, reflections, specular light, lens flares, bump maps, the rest of "low"), as many as their learnt costs say; brings one back once GPU time + its cost stays under 7/10 of the frame for 3 s (longer if it had to go again within 10 s). Logs `VR graphics auto: shadows left out (step 2): the GPU 10.2 ms a frame of 11.1`, `... saved 1.9 ms`, `... back`. On the Steam Frame (no GPU time from SteamVR) "auto" is "high" |
+| Measuring | `debug.vr_graphics_measure = true`: each effect left out in turn (1.5 s on, 1.5 s off), `VR graphics measure: shadows 2.10 ms (...)` and means each round |
+
+What the effects cost, from the code (to be measured with the option above):
+object shadows are drawn once a frame with multiview (the scene is drawn
+once), twice one eye at a time; each shadow-casting object (every bot, its
+weapon, vehicles) renders its map, blurs it and projects it onto the level
+beneath: a pass of fill on both eyes per object. Reflections and specular
+light are passes over the level's geometry. The shield's glow
+(`display.shield_glow`, off by default) is a dynamic light per flaring unit
+(at most 8), each lighting the level's surfaces in its reach once more, not
+a pass per object; upstream's shield colour on the arms only changes a
+colour. The whole body adds the player's own model and its shadow.
+
+Not done, and why:
+- Drawing the eyes straight into the swapchain: moot now (GPU not the
+  bottleneck); it needs GL_EXT_sRGB_write_control, the vignette as a pass
+  of its own and array swapchains acquired mid-frame.
+- Decoding all menu pictures ahead: 165 pictures, about 350 MB decoded with
+  their mipmaps.
+- Later: XR_KHR_visibility_mask.
+
+### Headset test, graphics "auto" (Quest 3)
+
+1. VR options, MORE: Graphics **Auto** (a `config.toml` written before
+   still says "high"), Foveation Off; `vr.log_performance = true`.
+2. Log at start: `xr: performance metrics on (... the app's GPU time read)`,
+   `VR: graphics auto`.
+3. 15-bot match on Blood Gulch, a few minutes, also into the busy middle:
+   - `VR graphics auto: ... left out (step N): the GPU X ms` within a
+     quarter to half a second of a heavy spell, `... saved Y ms`, and
+     `... back` a few seconds after it.
+   - VrApi: `Stale=` 0 nearly every second (at most a few in the second a
+     spell begins), no `ASW=1` spells; App GPU under about 9 ms.
+   - Look for effects that pop: shadows going and coming back. If they
+     change more than every ten seconds or so, note the log lines.
+4. Costs: a second match with `debug.vr_graphics_measure = true` (Graphics
+   setting ignored meanwhile; stand somewhere busy, a few minutes):
+   `VR graphics measure: means (ms of GPU a frame): shadows ...;
+   reflections ...`. The steps' order should follow the largest costs.
+5. The first frames of a map (245/72 ms, vertex program 4): try
+   `debug.shader_warm_up = "load"` once and compare those lines.
+
+### Headset test, shader worker (Quest 3)
+
+Before: `adb logcat -G 16M` (again after any reboot); in `config.toml`
+`vr.log_performance = true`, 90 Hz, graphics "high", multiview, full body;
+Foveation Off (VR options, MORE: the config may still say "medium"). After
+each test: `adb logcat -d -s halo VrApi > test.txt`. The shader cache from
+the earlier tests stays.
+
+1. Start: `gl worker: running (ES 3, surfaceless, programs warmed up)` and
+   `shader cache: ... N programs kept (... N listed) ...; programs made on
+   the worker, warmed up there`. As the menus load: `shader cache:
+   levels_ui_ui: N programs listed; N asked of the worker ...; N of other
+   maps to ask for`.
+2. Bot match on Blood Gulch: as it loads, `... bloodgulch: N listed; ...
+   N there already` (made while in the menus). In play no `VR: long frame`
+   with shaders compiled; at most a few `draws left out` (objects appearing
+   a frame or two late), and VrApi `Stale=0` most seconds, no `ASW=1`.
+   Any long frame left: its `draw calls ... the slowest N ms (vertex program
+   N, program K)` says whether a draw (a driver variant) is the cause.
+3. A map not played yet (Damnation): as it loads, `N programs listed` is 0
+   but `N there already` should not matter: its programs mostly come from
+   every map's list (made in the menus). New ones are compiled on the worker
+   (`draws left out` for a moment, no long frame).
+4. If draws of 70-250 ms remain with nothing compiled: `debug.shader_warm_up
+   = "load"` (the log: `shader cache: N programs drawn with once as the map
+   loaded, in N ms`), then compare; and `"off"` for the baseline.
+5. Menus: open new screens; pictures may appear a frame late, no long
+   frames with `menu pictures`.
+6. If anything breaks (missing objects for good, a crash):
+   `display.shader_worker = false` brings the game's-thread compiling back.
+
+Steam Frame: the worker also runs there if its EGL shares contexts (the log
+says `gl worker: running` or why not); no foveation. A short bot game to
+see that nothing is missing or slower.
+
+## Open points outside the order
+
+- Multiview's doubled pictures (2026-10-16): on the developer's Quest 3,
+  doubled and shifted pictures from the start of big online games (26-35
+  players) as the head turned, nauseating; none in a local game with 48
+  bots; none online either with the eyes drawn one by one. Not the frame
+  rate: one by one, online at 72 Hz, the compositor repeated as many
+  frames (about 4 a second) and nothing was seen. Not the facing jumps
+  (respawns only) nor the camera (it moves every frame). Before: the
+  Steam Frame's (2026-10-05), each eye alone sharp. So the eyes are drawn
+  one by one by default now (`debug.multiview` for both at once). To do:
+  find what the shared pass draws wrongly online, e.g. by saving both
+  eyes' pictures in a big online game and comparing what is doubled
+  (sprites and effects projected by the game itself, `mv_depth`; programs
+  made on the shader worker; the sky rows), then turn it back on: it
+  halves the drawing's CPU cost.
+- Big online games (2026-10-16): doubled pictures on a 32-player server,
+  none in a local game with 48 bots. Not the GPU (60–80 %): the ticks cost
+  3.3–4.6 ms as a client there (1.3–1.9 ms with bots or 16 players), so
+  47–70 of 150 frames with a tick missed 90 Hz's 11.1 ms (the doubling
+  itself was multiview's, above). In `main` 2026-10-16 (Quest 3 good):
+  `vr.refresh_rate_auto`
+  (VR options MORE, "Lower it when frames are late", on by default) steps
+  the rate down a step (90, 80, 72 Hz) while more than one frame in 32
+  comes late, and back up once they would keep up; "VR: refresh rate" in
+  the log. First try: 90 to 80 Hz a few seconds into a 30-player game, no
+  doubled picture seen; 2-5 stale frames a second left at 80, hence one
+  in 32 (was 16). Later:
+  why a client's ticks cost that much per remote player.
+
+- Doubled pictures when turning on the developer's Quest 3 (2026-10-12):
+  with every build tried, back to 2026-10-06's, at 90 and at 72 Hz, even
+  in seconds the compositor reported no stale frame. That Quest runs
+  Horizon OS from the Public Test Channel (PTC; its build 2026-10-08),
+  the likeliest cause. Released with `vr.graphics` "medium" as the
+  default (smooth there). To do: try this and later builds with "high" on
+  a Quest 3 outside PTC (the developer's wife's), and set the default
+  back to "high" or "auto" if it holds.
+  Resolved 2026-10-16: multiview (above), not the Horizon OS PTC.
+
+- 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), in `main`;
+  still to check in a game of 30 and more players; upstream raised them
+  to 2048 too (2026-10-12).
+
+## 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).

port/android/app/build.gradle

@@ -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
             }
         }
     }

port/android/app/src/main/AndroidManifest.xml

@@ -19,17 +19,25 @@
     <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:name=".HaloApplication"
         android:label="@string/app_name"
         android:icon="@mipmap/ic_launcher"
         android:allowBackup="false"
         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 -->
@@ -68,7 +76,10 @@
              (without them Horizon OS shows it as a flat panel, and the OpenXR
              session never gets focus); phones ignore them. The launcher,
              a flat panel on a headset, starts it once the game data is
-             there. -->
+             there. (port: upstream runs it in a process of its own,
+             ":game", for handhelds whose Java heap covers the Xbox window;
+             not here: on the Steam Frame Lepton waits for the app's process
+             to end, and the headsets have no such overlap) -->
         <activity
             android:name=".HaloActivity"
             android:exported="true"
@@ -93,7 +104,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" />
 

port/android/app/src/main/java/com/halo/decomp/GyroscopeAim.java

@@ -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);
+    }
+}

port/android/app/src/main/java/com/halo/decomp/HaloActivity.java

@@ -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

port/android/app/src/main/java/com/halo/decomp/HaloApplication.java

@@ -0,0 +1,33 @@
+package com.halo.decomp;
+
+import android.app.Application;
+
+/**
+ * The game (HaloActivity) runs in a process of its own, ":game", so that
+ * its Java runtime starts fresh for it: nothing the launcher, the disc
+ * image import or an earlier game did is left in its heap.
+ *
+ * There the native library is loaded first thing, and reserves the fixed
+ * addresses the game needs at 0x80000000 (port/android/host/host_main.c,
+ * JNI_OnLoad) before the Java side has allocated anything large: on some
+ * devices, handhelds with a large Java heap especially, ART's large object
+ * space covers those addresses, and only an idle part of it can be taken
+ * back (port/android/host/host_memory.c).
+ */
+public class HaloApplication extends Application {
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        String process = Application.getProcessName();
+        if (process == null || !process.endsWith(":game"))
+            return;
+        try {
+            // in SDLActivity's order (HaloActivity.getLibraries); it
+            // finds them loaded
+            System.loadLibrary("SDL3");
+            System.loadLibrary("main");
+        } catch (UnsatisfiedLinkError e) {
+            // SDLActivity reports it
+        }
+    }
+}

port/android/app/src/main/java/com/halo/decomp/LauncherActivity.java

@@ -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;
+    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() : "") + "/");

port/android/app/src/main/java/com/halo/decomp/TouchLayout.java

@@ -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;
+    }
+}

port/android/app/src/main/java/com/halo/decomp/UpdateProvider.java

@@ -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);

port/android/app/src/main/java/com/halo/decomp/Updater.java

@@ -36,7 +36,8 @@ import java.util.zip.ZipInputStream;
  * the latest release when it starts, on a thread of its own, and if it is
  * newer asks the player whether to update:
  *
- * - Yes: the release's app (halo-android-release.zip or -debug.zip) is
+ * - Yes: the release's app (ringfall-mjolnir-vr-android-release.zip or
+ *   -debug.zip) is
  *   downloaded and handed to Android's package installer, which replaces the
  *   game (closing it) and offers to open the new version.
  * - No: nothing, until the next start.
@@ -45,13 +46,19 @@ import java.util.zip.ZipInputStream;
  *
  * Every build of main is signed with the same key (the workflow's), which an
  * app must keep for Android to install a new version over it.
+ *
+ * Not on the Steam Frame: Lepton installs the APK in the game's folder there
+ * at every start, so its launcher updates that (steam_frame_launch.sh).
  */
 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() {
     }
@@ -60,7 +67,8 @@ final class Updater {
     static void start(Activity activity) {
         File config = configFile(activity);
 
-        if (BuildConfig.HALO_BUILD_NUMBER <= 0 || config == null || !autoUpdate(config))
+        if (BuildConfig.HALO_BUILD_NUMBER <= 0 || config == null || !autoUpdate(config) ||
+                new File(LauncherActivity.SHARED_DATA_ROOT).isDirectory())
             return;
         new Thread(() -> {
             int latest = latestRelease();
@@ -202,8 +210,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 +223,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 +240,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 +255,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 +283,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 +312,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 +339,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;
             }

port/android/app/src/main/java/com/halo/decomp/XisoExtractor.java

@@ -9,6 +9,7 @@ import java.nio.channels.FileChannel;
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Locale;
 
 /**
  * Copies the maps folder out of an Xbox disc image (an "xiso", or a whole
@@ -29,6 +30,12 @@ import java.util.List;
  * The files are written to maps.partial first and moved into maps once they
  * all are, so an interrupted extraction never leaves maps/ui.map behind.
  *
+ * A European disc in two languages (Spanish and Italian) has no maps folder
+ * but one for each, maps_es and maps_it: the device's language's is taken,
+ * else English's, else the first, and its language written to
+ * maps/language.txt, which the game asks the Xbox for (game.language unset,
+ * port/linux/src/xbox_xapi.c): the menus in it too.
+ *
  * Some parts of this code are copyright in@fishtank.com. This product
  * includes software developed by in <in@fishtank.com>.
  *
@@ -135,6 +142,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 +211,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)
@@ -210,6 +232,28 @@ final class XisoExtractor {
             if (entry.name.equalsIgnoreCase("maps"))
                 maps = entry;
         }
+        String language = null;
+        if (maps == null) {
+            String wanted = Locale.getDefault().getLanguage();
+            Entry english = null, first = null;
+
+            for (Entry entry : directories) {
+                String code = mapsLanguage(entry.name);
+
+                if (code == null)
+                    continue;
+                if (code.equals(wanted))
+                    maps = entry;
+                if (code.equals("en"))
+                    english = entry;
+                if (first == null)
+                    first = entry;
+            }
+            if (maps == null)
+                maps = english != null ? english : first;
+            if (maps != null)
+                language = mapsLanguage(maps.name);
+        }
         if (maps == null)
             throw new ExtractException("The disc image has no maps folder: it is not a Halo disc.");
 
@@ -271,5 +315,22 @@ final class XisoExtractor {
                 throw new ExtractException("Could not move " + file.name + " into " + finished + ".");
         }
         partial.delete();
+        File languageFile = new File(finished, "language.txt");
+        languageFile.delete();
+        if (language != null) {
+            try (FileOutputStream out = new FileOutputStream(languageFile)) {
+                out.write((language + "\n").getBytes(StandardCharsets.US_ASCII));
+            } catch (IOException e) {
+                throw new ExtractException("Could not write " + languageFile + " (is the storage full?).");
+            }
+        }
+    }
+
+    /** a language's maps folder's language ("maps_it": "it"), else null */
+    static String mapsLanguage(String name) {
+        if (name.length() != 7 || !name.regionMatches(true, 0, "maps_", 0, 5))
+            return null;
+        String code = name.substring(5).toLowerCase(Locale.ROOT);
+        return Character.isLetter(code.charAt(0)) && Character.isLetter(code.charAt(1)) ? code : null;
     }
 }

port/android/app/src/main/res/values/strings.xml

@@ -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>

port/android/guest/runtime/guest_host.h

@@ -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,8 +70,15 @@ 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);
+/* SDL_ShowMessageBox of up to three buttons (SDL_MessageBoxData has not the
+guest's layout): the index of the one chosen, else -1 */
+int host_sdl_show_message_box(unsigned int flags, const char *title, const char *message, int default_index,
+	const char *button0, const char *button1, const char *button2);
 int host_sdl_get_gamepads(unsigned int *ids, int capacity);
 unsigned int host_sdl_open_gamepad(unsigned int id);
 unsigned int host_sdl_gamepad_from_id(unsigned int id);
@@ -77,11 +86,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 +103,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
@@ -105,6 +120,23 @@ void host_gl_wait_frame(unsigned int slot);
 reads a snapshot once its frame is finished */
 void host_gl_counters_snapshot(unsigned int buffer, unsigned int size, unsigned int slot);
 int host_gl_counters_read(unsigned int slot, void *out, unsigned int size);
+/* the shader programs' worker (port/android/host/host_gl_worker.c), for
+port/linux/src/xgpu_program_cache.c: started on the game's thread with its
+context current (1: running); a program asked for (its binary tried first,
+else its sources compiled; urgent: a draw waits for it), a job's number or
+0; hurried along; polled (1 done: *program, its kept binary's size, the
+time it took; 0 not yet; -1 failed); its kept binary copied out; the job
+forgotten; how many jobs are not done; and a warm-up draw with a program on
+the calling thread's context */
+int host_gl_worker_start(int warm_up);
+unsigned int host_gl_program_request(int urgent, const char *vertex_source, const char *fragment_source,
+	unsigned int binary_format, const void *binary, unsigned int binary_size, int keep_binary);
+void host_gl_program_hurry(unsigned int id);
+int host_gl_program_poll(unsigned int id, unsigned int *program, unsigned int *binary_size, unsigned int *microseconds);
+unsigned int host_gl_program_binary(unsigned int id, void *buffer, unsigned int size, unsigned int *format);
+void host_gl_program_release(unsigned int id);
+unsigned int host_gl_worker_waiting(void);
+void host_gl_program_warm_up(unsigned int program, int multiview);
 
 /* ---------- OpenXR (port/android/host/host_xr.c; the structures are in
 halo_xr_abi.h) */
@@ -116,7 +148,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 +164,38 @@ 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);
+/* the app's GPU time of a recent frame (ms; 0: the runtime does not tell
+it), for vr.graphics "auto" */
+float host_xr_gpu_time(void);
 
 /* ---------- 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

port/android/guest/runtime/guest_memory_watch.c

@@ -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();
+}

port/android/guest/runtime/guest_sdl.c

@@ -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();
@@ -82,6 +95,31 @@ bool SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, cons
 	return host_sdl_show_simple_message_box((unsigned int)flags, title, message) != 0;
 }
 
+/* (up to three buttons, their ids those of the guest's) */
+bool SDL_ShowMessageBox(const SDL_MessageBoxData *data, int *buttonid)
+{
+	const char *labels[3] = { NULL, NULL, NULL };
+	int default_index = -1;
+	int index;
+	int chosen;
+
+	if (!data || data->numbuttons < 1 || data->numbuttons > 3)
+		return false;
+	for (index = 0; index < data->numbuttons; index++)
+	{
+		labels[index] = data->buttons[index].text;
+		if (data->buttons[index].flags & SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT)
+			default_index = index;
+	}
+	chosen = host_sdl_show_message_box((unsigned int)data->flags, data->title, data->message, default_index,
+		labels[0], labels[1], labels[2]);
+	if (chosen < 0 || chosen >= data->numbuttons)
+		return false;
+	if (buttonid)
+		*buttonid = data->buttons[chosen].buttonID;
+	return true;
+}
+
 void SDL_Delay(Uint32 milliseconds)
 {
 	struct timespec duration;
@@ -203,6 +241,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 +264,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);
+}

port/android/guest/runtime/guest_start.c

@@ -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,
 };

port/android/guest/runtime/guest_string.c

@@ -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;
+}

port/android/guest/runtime/guest_thread.c

@@ -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)
 {

port/android/host/host.h

@@ -12,6 +12,7 @@ port/android/include/halo_android_abi.h for the guest contract.
 #include <stdarg.h>
 #include <stddef.h>
 #include <stdint.h>
+#include <stdio.h>
 
 #include "halo_android_abi.h"
 
@@ -35,8 +36,21 @@ Xbox window and the image's range at start-up, and hands out pages for
 everything else (the guest's malloc arenas, thread stacks, anonymous
 mappings) from pools of address space it reserves below 4 GB on demand. */
 
-/* reserves the fixed ranges; returns 0 on success */
+/* reserves the fixed ranges (the Xbox window and the image's) as early as
+the process allows: from JNI_OnLoad, before the Java side of the game's
+process allocates much (host_main.c); a failure is reported again by
+host_memory_initialize */
+void host_memory_reserve_early(void);
+/* takes the fixed ranges for the image; returns 0 on success */
 int host_memory_initialize(uint32_t image_base, uint32_t image_size);
+/* 1 if the fixed ranges could not be reserved (something else holds them) */
+int host_memory_fixed_unavailable(void);
+/* lists the mappings below 4 GB in logcat and, if file is not NULL, in it */
+void host_memory_report_low_mappings(FILE *file);
+/* 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 +106,17 @@ 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);
+/* the shader programs' worker (host_gl_worker.c; the guest's imports) */
+int host_gl_worker_start(int warm_up);
+uint32_t host_gl_program_request(int urgent, const char *vertex_source, const char *fragment_source,
+	uint32_t binary_format, const void *binary, uint32_t binary_size, int keep_binary);
+void host_gl_program_hurry(uint32_t id);
+int host_gl_program_poll(uint32_t id, uint32_t *program, uint32_t *binary_size, uint32_t *microseconds);
+uint32_t host_gl_program_binary(uint32_t id, void *buffer, uint32_t size, uint32_t *format);
+void host_gl_program_release(uint32_t id);
+uint32_t host_gl_worker_waiting(void);
+void host_gl_program_warm_up(uint32_t program, int multiview);
 
 /* ---------- VR (host_xr.c) */
 

port/android/host/host_gl.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;
 }
 

port/android/host/host_gl_worker.c

@@ -0,0 +1,671 @@
+/*
+HOST_GL_WORKER.C
+
+The shader programs' worker (port/linux/src/xgpu_program_cache.c): a thread
+with a GL context of its own, sharing the game's objects, that makes the
+programs the game asks for while the game goes on drawing. The drivers
+compile a program the first time it is drawn with, 10 to 70 ms each on the
+Quest's, and the frame waited for it: in VR a frame shown late, the picture
+doubled as the head turns.
+
+- host_gl_worker_start, on the game's thread with its context current:
+  makes a context that shares the game's (surfaceless, or on a 1x1
+  pbuffer) and the thread that keeps it current.
+- host_gl_program_request: a program of these sources, from their binary
+  where one is given and the driver takes it, else compiled and linked
+  (its binary kept for the cache's file). The sources and the binary are
+  copied: the caller's may go at once. Urgent requests (a draw waits for
+  them) go before the others (a map's programs made ready as it loads).
+- On the worker each program is linked, its samplers set to their units
+  (as d3d8_gl.c sets them), drawn with once into a small target of its own
+  (a degenerate triangle: the driver makes the variants it makes at a
+  first draw now, not in the game's frame; "warm up"), and a fence put
+  after it all.
+- host_gl_program_poll, on the game's thread: done once the fence has
+  passed (GL's rule for an object made in one context and used in another:
+  the work finished before the other binds it); then the program is the
+  game's (a program name is the same in both contexts).
+
+host_gl_program_warm_up draws once with a program on the calling thread's
+context instead (debug.shader_warm_up "load": on the game's, as a map
+loads), for comparing the two.
+*/
+
+#include "host.h"
+
+#include <EGL/egl.h>
+#include <EGL/eglext.h>
+#include <GLES3/gl32.h>
+#include <GLES2/gl2ext.h>
+#include <pthread.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+#define JOB_BUCKETS 1024
+/* the warm-up's target, each way */
+#define WARM_UP_SIZE 16
+
+enum
+{
+	JOB_QUEUED,
+	JOB_WORKING,
+	JOB_DONE,
+	JOB_FAILED,
+};
+
+struct job
+{
+	struct job *next_in_bucket;
+	struct job *next_in_queue;
+	uint32_t id;
+	int urgent;
+	char *sources[2];
+	void *binary;
+	uint32_t binary_size;
+	uint32_t binary_format;
+	int keep_binary;
+	int state;
+	/* the results */
+	GLuint program;
+	GLsync sync;
+	int from_binary;
+	void *kept_binary;
+	uint32_t kept_size;
+	uint32_t kept_format;
+	uint32_t microseconds;
+};
+
+/* a context's warm-up target: the eyes' kinds, one layer and two
+(multiview), RGBA8 with a depth and stencil buffer */
+struct warm_up_targets
+{
+	int made;
+	/* each kind's framebuffer complete */
+	int complete[2];
+	GLuint framebuffers[2];
+	GLuint textures[4];
+	GLuint vertex_array;
+	GLuint counters;
+};
+
+static struct
+{
+	int started;
+	int running;
+	int warm_up;
+	EGLDisplay display;
+	EGLContext context;
+	EGLSurface surface;
+	pthread_t thread;
+	pthread_mutex_t lock;
+	pthread_cond_t wake;
+	pthread_cond_t ready;
+	struct job *buckets[JOB_BUCKETS];
+	struct job *urgent_first, *urgent_last;
+	struct job *later_first, *later_last;
+	uint32_t next_id;
+	uint32_t waiting;
+	int failures_logged;
+	PFNGLFRAMEBUFFERTEXTUREMULTIVIEWOVRPROC framebuffer_texture_multiview;
+	struct warm_up_targets targets[2];
+} worker;
+
+static uint64_t now_us(void)
+{
+	struct timespec now;
+
+	clock_gettime(CLOCK_MONOTONIC, &now);
+	return (uint64_t)now.tv_sec * 1000000u + (uint64_t)now.tv_nsec / 1000u;
+}
+
+/* ---------- the warm-up draw */
+
+static int targets_make(struct warm_up_targets *targets)
+{
+	GLint major = 0, minor = 0;
+	int kind;
+
+	if (targets->made)
+		return targets->made > 0;
+	targets->made = -1;
+	glGenTextures(4, targets->textures);
+	glGenFramebuffers(2, targets->framebuffers);
+	for (kind = 0; kind < 2; kind++)
+	{
+		GLenum target = kind ? GL_TEXTURE_2D_ARRAY : GL_TEXTURE_2D;
+
+		glBindTexture(target, targets->textures[kind * 2]);
+		if (kind)
+			glTexStorage3D(target, 1, GL_RGBA8, WARM_UP_SIZE, WARM_UP_SIZE, 2);
+		else
+			glTexStorage2D(target, 1, GL_RGBA8, WARM_UP_SIZE, WARM_UP_SIZE);
+		glBindTexture(target, targets->textures[kind * 2 + 1]);
+		if (kind)
+			glTexStorage3D(target, 1, GL_DEPTH24_STENCIL8, WARM_UP_SIZE, WARM_UP_SIZE, 2);
+		else
+			glTexStorage2D(target, 1, GL_DEPTH24_STENCIL8, WARM_UP_SIZE, WARM_UP_SIZE);
+		glBindTexture(target, 0);
+		glBindFramebuffer(GL_FRAMEBUFFER, targets->framebuffers[kind]);
+		if (kind)
+		{
+			if (!worker.framebuffer_texture_multiview)
+				continue;
+			worker.framebuffer_texture_multiview(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, targets->textures[2], 0, 0, 2);
+			worker.framebuffer_texture_multiview(GL_FRAMEBUFFER, GL_DEPTH_STENCIL_ATTACHMENT, targets->textures[3], 0,
+				0, 2);
+		}
+		else
+		{
+			glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, targets->textures[0], 0);
+			glFramebufferTexture2D(GL_FRAMEBUFFER, GL_DEPTH_STENCIL_ATTACHMENT, GL_TEXTURE_2D, targets->textures[1], 0);
+		}
+		targets->complete[kind] = glCheckFramebufferStatus(GL_FRAMEBUFFER) == GL_FRAMEBUFFER_COMPLETE;
+		if (!targets->complete[kind])
+			host_logf(HOST_LOG_WARN, "gl worker: the %s warm-up target is incomplete; no warm-up there",
+				kind ? "multiview" : "plain");
+	}
+	glBindFramebuffer(GL_FRAMEBUFFER, 0);
+	glGenVertexArrays(1, &targets->vertex_array);
+	/* (the visibility tests' programs count samples into binding 0) */
+	glGetIntegerv(GL_MAJOR_VERSION, &major);
+	glGetIntegerv(GL_MINOR_VERSION, &minor);
+	if (major > 3 || (major == 3 && minor >= 1))
+	{
+		glGenBuffers(1, &targets->counters);
+		glBindBuffer(GL_ATOMIC_COUNTER_BUFFER, targets->counters);
+		glBufferData(GL_ATOMIC_COUNTER_BUFFER, 64, NULL, GL_DYNAMIC_DRAW);
+		glBindBuffer(GL_ATOMIC_COUNTER_BUFFER, 0);
+	}
+	targets->made = 1;
+	return 1;
+}
+
+/* one degenerate triangle with the program into the target of its kind,
+depth tested and blended as most of the game's draws are; the GL state it
+changes is left changed (the worker's context has no other use, and the
+game's sets it again: d3d8_host_state_changed) */
+static void warm_up_draw(struct warm_up_targets *targets, GLuint program, int multiview)
+{
+	if (!targets_make(targets) || !targets->complete[multiview ? 1 : 0])
+		return;
+	glBindFramebuffer(GL_FRAMEBUFFER, targets->framebuffers[multiview ? 1 : 0]);
+	glViewport(0, 0, WARM_UP_SIZE, WARM_UP_SIZE);
+	glDisable(GL_SCISSOR_TEST);
+	glDisable(GL_STENCIL_TEST);
+	glDisable(GL_CULL_FACE);
+	glEnable(GL_DEPTH_TEST);
+	glDepthFunc(GL_LEQUAL);
+	glDepthMask(GL_TRUE);
+	glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE);
+	glEnable(GL_BLEND);
+	glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+	glBindVertexArray(targets->vertex_array);
+	if (targets->counters)
+		glBindBufferBase(GL_ATOMIC_COUNTER_BUFFER, 0, targets->counters);
+	glUseProgram(program);
+	glDrawArrays(GL_TRIANGLES, 0, 3);
+	glUseProgram(0);
+	glBindVertexArray(0);
+	glBindFramebuffer(GL_FRAMEBUFFER, 0);
+}
+
+void host_gl_program_warm_up(uint32_t program, int multiview)
+{
+	if (!worker.running || !program)
+		return;
+	warm_up_draw(&worker.targets[0], program, multiview);
+}
+
+/* ---------- the worker's jobs */
+
+static struct job *job_find(uint32_t id)
+{
+	struct job *job;
+
+	for (job = worker.buckets[id % JOB_BUCKETS]; job; job = job->next_in_bucket)
+	{
+		if (job->id == id)
+			return job;
+	}
+	return NULL;
+}
+
+static void queue_append(struct job *job)
+{
+	struct job **first = job->urgent ? &worker.urgent_first : &worker.later_first;
+	struct job **last = job->urgent ? &worker.urgent_last : &worker.later_last;
+
+	job->next_in_queue = NULL;
+	if (*last)
+		(*last)->next_in_queue = job;
+	else
+		*first = job;
+	*last = job;
+}
+
+static struct job *queue_take(void)
+{
+	struct job *job = worker.urgent_first;
+
+	if (job)
+	{
+		worker.urgent_first = job->next_in_queue;
+		if (!worker.urgent_first)
+			worker.urgent_last = NULL;
+		return job;
+	}
+	job = worker.later_first;
+	if (job)
+	{
+		worker.later_first = job->next_in_queue;
+		if (!worker.later_first)
+			worker.later_last = NULL;
+	}
+	return job;
+}
+
+static GLuint shader_compile(GLenum type, const char *source)
+{
+	GLuint shader = glCreateShader(type);
+	GLint status = 0;
+
+	glShaderSource(shader, 1, &source, NULL);
+	glCompileShader(shader);
+	glGetShaderiv(shader, GL_COMPILE_STATUS, &status);
+	if (!status)
+	{
+		char log[1024];
+
+		log[0] = 0;
+		glGetShaderInfoLog(shader, sizeof(log), NULL, log);
+		if (worker.failures_logged++ < 4)
+			host_logf(HOST_LOG_WARN, "gl worker: a %s shader does not compile: %s",
+				type == GL_VERTEX_SHADER ? "vertex" : "pixel", log);
+		glDeleteShader(shader);
+		return 0;
+	}
+	return shader;
+}
+
+/* the job's program (outside the lock: only the worker touches a job
+being worked on) */
+static void job_work(struct job *job)
+{
+	uint64_t start = now_us();
+	GLuint program = 0;
+	GLint status = 0;
+
+	if (job->binary && job->binary_size)
+	{
+		program = glCreateProgram();
+		glProgramBinary(program, (GLenum)job->binary_format, job->binary, (GLsizei)job->binary_size);
+		glGetProgramiv(program, GL_LINK_STATUS, &status);
+		if (status)
+			job->from_binary = 1;
+		else
+		{
+			glDeleteProgram(program);
+			program = 0;
+			while (glGetError() != GL_NO_ERROR)
+			{
+			}
+		}
+	}
+	if (!program && job->sources[0] && job->sources[1])
+	{
+		GLuint vertex = shader_compile(GL_VERTEX_SHADER, job->sources[0]);
+		GLuint fragment = vertex ? shader_compile(GL_FRAGMENT_SHADER, job->sources[1]) : 0;
+
+		if (vertex && fragment)
+		{
+			program = glCreateProgram();
+			glProgramParameteri(program, GL_PROGRAM_BINARY_RETRIEVABLE_HINT, GL_TRUE);
+			glAttachShader(program, vertex);
+			glAttachShader(program, fragment);
+			glLinkProgram(program);
+			glGetProgramiv(program, GL_LINK_STATUS, &status);
+			if (!status)
+			{
+				char log[1024];
+
+				log[0] = 0;
+				glGetProgramInfoLog(program, sizeof(log), NULL, log);
+				if (worker.failures_logged++ < 4)
+					host_logf(HOST_LOG_WARN, "gl worker: a program does not link: %s", log);
+				glDeleteProgram(program);
+				program = 0;
+			}
+		}
+		/* (attached, they go with the program) */
+		if (vertex)
+			glDeleteShader(vertex);
+		if (fragment)
+			glDeleteShader(fragment);
+		if (program && job->keep_binary)
+		{
+			GLint length = 0;
+			GLsizei written = 0;
+			GLenum format = 0;
+
+			glGetProgramiv(program, GL_PROGRAM_BINARY_LENGTH, &length);
+			if (length > 0 && (job->kept_binary = malloc((size_t)length)) != NULL)
+			{
+				glGetProgramBinary(program, length, &written, &format, job->kept_binary);
+				if (written > 0 && written <= length)
+				{
+					job->kept_size = (uint32_t)written;
+					job->kept_format = (uint32_t)format;
+				}
+				else
+				{
+					free(job->kept_binary);
+					job->kept_binary = NULL;
+				}
+			}
+		}
+	}
+	if (program)
+	{
+		int unit;
+
+		/* the samplers' units, as d3d8_gl.c's program_get sets them (a
+		first draw with two kinds of sampler on one unit draws nothing) */
+		glUseProgram(program);
+		for (unit = 0; unit < 4; unit++)
+		{
+			char name[8];
+
+			snprintf(name, sizeof(name), "tex%d", unit);
+			glUniform1i(glGetUniformLocation(program, name), unit);
+		}
+		glUseProgram(0);
+		if (worker.warm_up)
+			warm_up_draw(&worker.targets[1], program,
+				job->sources[0] && strstr(job->sources[0], "GL_OVR_multiview") != NULL);
+		job->sync = glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0);
+	}
+	glFlush();
+	job->program = program;
+	job->microseconds = (uint32_t)(now_us() - start);
+}
+
+static void *worker_main(void *unused)
+{
+	(void)unused;
+	if (!eglMakeCurrent(worker.display, worker.surface, worker.surface, worker.context))
+	{
+		host_logf(HOST_LOG_ERROR, "gl worker: its context cannot be made current (0x%x)", eglGetError());
+		pthread_mutex_lock(&worker.lock);
+		worker.started = -1;
+		pthread_cond_broadcast(&worker.ready);
+		pthread_mutex_unlock(&worker.lock);
+		return NULL;
+	}
+	pthread_mutex_lock(&worker.lock);
+	worker.started = 1;
+	pthread_cond_broadcast(&worker.ready);
+	for (;;)
+	{
+		struct job *job;
+
+		while ((job = queue_take()) == NULL)
+			pthread_cond_wait(&worker.wake, &worker.lock);
+		job->state = JOB_WORKING;
+		pthread_mutex_unlock(&worker.lock);
+		job_work(job);
+		pthread_mutex_lock(&worker.lock);
+		free(job->binary);
+		job->binary = NULL;
+		free(job->sources[0]);
+		free(job->sources[1]);
+		job->sources[0] = job->sources[1] = NULL;
+		job->state = job->program ? JOB_DONE : JOB_FAILED;
+		worker.waiting--;
+	}
+	return NULL;
+}
+
+/* ---------- the game's */
+
+int host_gl_worker_start(int warm_up)
+{
+	EGLDisplay display = eglGetCurrentDisplay();
+	EGLContext shared = eglGetCurrentContext();
+	EGLint config_id = 0, count = 0, version = 3;
+	EGLint config_attributes[] = { EGL_CONFIG_ID, 0, EGL_NONE };
+	EGLint context_attributes[] = { EGL_CONTEXT_CLIENT_VERSION, 3, EGL_NONE };
+	EGLConfig config;
+	const char *extensions;
+	int started;
+
+	if (worker.running)
+		return 1;
+	if (worker.started)
+		return 0;
+	worker.warm_up = warm_up;
+	if (display == EGL_NO_DISPLAY || shared == EGL_NO_CONTEXT)
+	{
+		host_logf(HOST_LOG_WARN, "gl worker: no current context to share");
+		worker.started = -1;
+		return 0;
+	}
+	eglQueryContext(display, shared, EGL_CONFIG_ID, &config_id);
+	eglQueryContext(display, shared, EGL_CONTEXT_CLIENT_VERSION, &version);
+	config_attributes[1] = config_id;
+	if (!eglChooseConfig(display, config_attributes, &config, 1, &count) || count != 1)
+	{
+		host_logf(HOST_LOG_WARN, "gl worker: the game's context's configuration is not found");
+		worker.started = -1;
+		return 0;
+	}
+	context_attributes[1] = version;
+	extensions = eglQueryString(display, EGL_EXTENSIONS);
+	worker.surface = EGL_NO_SURFACE;
+	if (!extensions || !strstr(extensions, "EGL_KHR_surfaceless_context"))
+	{
+		/* (a 1x1 pbuffer to be current on, of a configuration that has one) */
+		EGLint pbuffer_config[] = { EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT_KHR, EGL_SURFACE_TYPE, EGL_PBUFFER_BIT,
+			EGL_NONE };
+		EGLint pbuffer_size[] = { EGL_WIDTH, 1, EGL_HEIGHT, 1, EGL_NONE };
+
+		if (!eglChooseConfig(display, pbuffer_config, &config, 1, &count) || count != 1 ||
+			(worker.surface = eglCreatePbufferSurface(display, config, pbuffer_size)) == EGL_NO_SURFACE)
+		{
+			host_logf(HOST_LOG_WARN, "gl worker: neither surfaceless contexts nor a pbuffer");
+			worker.started = -1;
+			return 0;
+		}
+	}
+	worker.context = eglCreateContext(display, config, shared, context_attributes);
+	if (worker.context == EGL_NO_CONTEXT)
+	{
+		host_logf(HOST_LOG_WARN, "gl worker: no context sharing the game's (0x%x)", eglGetError());
+		worker.started = -1;
+		return 0;
+	}
+	worker.display = display;
+	worker.next_id = 1;
+	worker.framebuffer_texture_multiview = (PFNGLFRAMEBUFFERTEXTUREMULTIVIEWOVRPROC)eglGetProcAddress(
+		"glFramebufferTextureMultiviewOVR");
+	pthread_mutex_init(&worker.lock, NULL);
+	pthread_cond_init(&worker.wake, NULL);
+	pthread_cond_init(&worker.ready, NULL);
+	if (pthread_create(&worker.thread, NULL, worker_main, NULL) != 0)
+	{
+		eglDestroyContext(display, worker.context);
+		worker.started = -1;
+		return 0;
+	}
+	pthread_mutex_lock(&worker.lock);
+	while (!worker.started)
+		pthread_cond_wait(&worker.ready, &worker.lock);
+	started = worker.started > 0;
+	pthread_mutex_unlock(&worker.lock);
+	worker.running = started;
+	/* (Mesa's trace markers, for the new context's too: host_gl.c) */
+	if (started)
+		host_gl_quiet_trace_markers();
+	host_logf(HOST_LOG_INFO, "gl worker: %s (ES %d, %s%s)", started ? "running" : "failed", (int)version,
+		worker.surface == EGL_NO_SURFACE ? "surfaceless" : "on a pbuffer", warm_up ? ", programs warmed up" : "");
+	return started;
+}
+
+uint32_t host_gl_program_request(int urgent, const char *vertex_source, const char *fragment_source,
+	uint32_t binary_format, const void *binary, uint32_t binary_size, int keep_binary)
+{
+	struct job *job;
+	uint32_t id;
+
+	if (!worker.running)
+		return 0;
+	job = calloc(1, sizeof(*job));
+	if (!job)
+		return 0;
+	job->urgent = urgent != 0;
+	job->keep_binary = keep_binary != 0;
+	job->sources[0] = vertex_source ? strdup(vertex_source) : NULL;
+	job->sources[1] = fragment_source ? strdup(fragment_source) : NULL;
+	if (binary && binary_size && (job->binary = malloc(binary_size)) != NULL)
+	{
+		memcpy(job->binary, binary, binary_size);
+		job->binary_size = binary_size;
+		job->binary_format = binary_format;
+	}
+	pthread_mutex_lock(&worker.lock);
+	id = job->id = worker.next_id++;
+	if (!worker.next_id)
+		worker.next_id = 1;
+	job->state = JOB_QUEUED;
+	job->next_in_bucket = worker.buckets[id % JOB_BUCKETS];
+	worker.buckets[id % JOB_BUCKETS] = job;
+	queue_append(job);
+	worker.waiting++;
+	pthread_cond_signal(&worker.wake);
+	pthread_mutex_unlock(&worker.lock);
+	return id;
+}
+
+/* a queued job a draw now waits for: before the others */
+void host_gl_program_hurry(uint32_t id)
+{
+	struct job *job, **link;
+
+	if (!worker.running)
+		return;
+	pthread_mutex_lock(&worker.lock);
+	job = job_find(id);
+	if (job && job->state == JOB_QUEUED && !job->urgent)
+	{
+		for (link = &worker.later_first; *link; link = &(*link)->next_in_queue)
+		{
+			if (*link == job)
+			{
+				struct job *previous = NULL, *walk;
+
+				*link = job->next_in_queue;
+				/* (the last of the later queue found again) */
+				for (walk = worker.later_first; walk; walk = walk->next_in_queue)
+					previous = walk;
+				worker.later_last = previous;
+				job->urgent = 1;
+				queue_append(job);
+				break;
+			}
+		}
+	}
+	pthread_mutex_unlock(&worker.lock);
+}
+
+int host_gl_program_poll(uint32_t id, uint32_t *program, uint32_t *binary_size, uint32_t *microseconds)
+{
+	struct job *job;
+	int result = 0;
+
+	if (!worker.running)
+		return -1;
+	pthread_mutex_lock(&worker.lock);
+	job = job_find(id);
+	if (!job || job->state == JOB_FAILED)
+		result = -1;
+	else if (job->state == JOB_DONE)
+	{
+		/* (the fence passed: everything the worker did with the program is
+		done, and this context may use it) */
+		if (job->sync)
+		{
+			GLenum waited = glClientWaitSync(job->sync, 0, 0);
+
+			if (waited == GL_ALREADY_SIGNALED || waited == GL_CONDITION_SATISFIED || waited == GL_WAIT_FAILED)
+			{
+				glDeleteSync(job->sync);
+				job->sync = NULL;
+			}
+		}
+		if (!job->sync)
+		{
+			*program = job->program;
+			*binary_size = job->kept_size;
+			*microseconds = job->microseconds;
+			result = 1;
+		}
+	}
+	pthread_mutex_unlock(&worker.lock);
+	return result;
+}
+
+uint32_t host_gl_program_binary(uint32_t id, void *buffer, uint32_t size, uint32_t *format)
+{
+	struct job *job;
+	uint32_t copied = 0;
+
+	if (!worker.running)
+		return 0;
+	pthread_mutex_lock(&worker.lock);
+	job = job_find(id);
+	if (job && job->state == JOB_DONE && job->kept_binary && size >= job->kept_size)
+	{
+		memcpy(buffer, job->kept_binary, job->kept_size);
+		*format = job->kept_format;
+		copied = job->kept_size;
+	}
+	pthread_mutex_unlock(&worker.lock);
+	return copied;
+}
+
+/* forgets a job (its program stays: the game's); a job still queued or
+being worked on is let go when it is done */
+void host_gl_program_release(uint32_t id)
+{
+	struct job *job, **link;
+
+	if (!worker.running)
+		return;
+	pthread_mutex_lock(&worker.lock);
+	for (link = &worker.buckets[id % JOB_BUCKETS]; (job = *link) != NULL; link = &job->next_in_bucket)
+	{
+		if (job->id != id)
+			continue;
+		if (job->state == JOB_QUEUED || job->state == JOB_WORKING)
+			break;
+		*link = job->next_in_bucket;
+		if (job->sync)
+			glDeleteSync(job->sync);
+		free(job->kept_binary);
+		free(job);
+		break;
+	}
+	pthread_mutex_unlock(&worker.lock);
+}
+
+uint32_t host_gl_worker_waiting(void)
+{
+	uint32_t waiting;
+
+	if (!worker.running)
+		return 0;
+	pthread_mutex_lock(&worker.lock);
+	waiting = worker.waiting;
+	pthread_mutex_unlock(&worker.lock);
+	return waiting;
+}

port/android/host/host_main.c

@@ -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,18 +385,68 @@ 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)
 		host_fatal("cannot read the game image from the APK: %s", SDL_GetError());
 	if (host_load_image(image, image_size) != 0)
-		host_fatal("cannot load the game image; see logcat (tag \"halo\") for details");
+	{
+		FILE *report;
+
+		if (!host_memory_fixed_unavailable())
+			host_fatal("cannot load the game image; see logcat (tag \"halo\") for details");
+
+		snprintf(path, sizeof(path), "%s/memory_map.txt", data_root);
+		report = fopen(path, "w");
+		host_memory_report_low_mappings(report);
+		if (report)
+			fclose(report);
+		host_fatal("The game cannot start: the memory it needs at 0x80000000 is taken by Android's "
+			"Java runtime on this device.\n\nRestarting the device may help. Please report it with "
+			"memory_map.txt from\n%s\n(or adb logcat -s halo).", data_root);
+	}
 	SDL_free(image);
 
 	/* after the image, whose loading reserves the guest's fixed address
 	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);
+	}
+	/* (vr.log_performance: the compositor's counters too, host_xr.c) */
+	if (config_boolean_or(path, "vr.log_performance", 0))
+		setenv("HALO_XR_LOG_PERFORMANCE", "1", 1);
 	{
 		int eye_width, eye_height;
 
@@ -329,6 +471,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 +484,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,16 +505,42 @@ 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);
 }
 
+/* Called when HaloApplication loads this library at the start of the
+game's own process (":game"), before its Java side has allocated anything
+large: ART's large object space, which on some devices covers the Xbox
+window, is then idle there and can be reclaimed (host_memory.c). */
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved)
+{
+	(void)vm;
+	(void)reserved;
+	host_memory_reserve_early();
+	return JNI_VERSION_1_6;
+}
+
 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");

port/android/host/host_memory.c

@@ -17,18 +17,25 @@ 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 <fcntl.h>
 #include <pthread.h>
 #include <signal.h>
+#include <stdarg.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <sys/mman.h>
+#include <sys/prctl.h>
+#include <sys/system_properties.h>
 #include <ucontext.h>
 #include <unistd.h>
 
@@ -101,58 +108,264 @@ static uint64_t find_gap(uint64_t size, uint64_t minimum)
 	return result;
 }
 
-/* ART reserves its spaces (notably the free-list large object space) at
-addresses chosen at zygote start; on some devices (for example the Retroid
-Pocket Flip2, kernel 4.19) that reservation covers the fixed Xbox memory
-window. That space commits pages lazily from its bottom, and the Java side
-of this app hardly allocates large objects, so the slice over the window is
-normally idle address space: unmap exactly the intersection (never more)
-and let the caller retry. Only that space, and only a slice with no page in
-use (present or swapped out, from /proc/self/pagemap): ART's other spaces
-(its heap, bitmaps and card tables) are live, and unmapping them would
-corrupt it where failing to start is at least clear. */
+/* ART reserves its spaces at addresses chosen at zygote start, and on some
+devices one of them covers the fixed Xbox memory window. ART's heap
+(dalvik.vm.heapsize) decides how much of the low 4 GB its spaces take: on
+handhelds with a large heap (the Retroid Pocket Flip2, the AYN Thor) the
+free-list large object space usually lands right above the boot image, over
+0x80000000.
+
+That space commits pages lazily from its bottom, and the game's process
+(HaloActivity runs in a process of its own, ":game", and reserves the
+window from JNI_OnLoad before its Java side has done anything:
+host_memory_reserve_early) hardly allocates large objects, so the slice
+over the window is normally idle address space: unmap exactly the
+intersection (never more) and let the caller retry. Only that space, and
+only a slice with no page in use (present or swapped out): ART's other
+spaces (its heap, bitmaps and card tables) are live, and unmapping them
+would corrupt it where failing to start is at least clear. */
 #define ART_LARGE_OBJECT_SPACE "[anon:dalvik-free list large object space]"
 
-/* whether no page from..to (page aligned) is present or swapped out; 0 if
-it cannot tell */
-static int range_unused(uint64_t from, uint64_t to)
+/* what range_usage found */
+enum
 {
-	FILE *pagemap = fopen("/proc/self/pagemap", "rb");
+	RANGE_UNUSED,
+	RANGE_IN_USE,
+	RANGE_UNKNOWN
+};
+
+/* why the fixed ranges could not be had: each reason also goes to the
+log, and the report (host_memory_report_low_mappings) starts with them, so
+memory_map.txt alone tells which case it was */
+static char findings[2048];
+
+static void finding(int priority, const char *format, ...)
+{
+	char line[512];
+	size_t used = strlen(findings);
+	va_list arguments;
+
+	va_start(arguments, format);
+	vsnprintf(line, sizeof(line), format, arguments);
+	va_end(arguments);
+	host_logf(priority, "%s", line);
+	if (used + strlen(line) + 2 < sizeof(findings))
+		snprintf(findings + used, sizeof(findings) - used, "%s\n", line);
+}
+
+struct range_usage
+{
+	uint64_t pages_in_use;
+	uint64_t lowest_in_use, highest_in_use;
+	const char *method;
+};
+
+static void note_in_use(struct range_usage *usage, uint64_t address)
+{
+	if (!usage->pages_in_use++)
+		usage->lowest_in_use = address;
+	usage->highest_in_use = address;
+}
+
+/* debug.halo.art_overlap's -nopagemap (simulate_art_overlap) */
+static int simulated_no_pagemap;
+
+/* from /proc/self/pagemap: bit 63 present, bit 62 swapped out */
+static int range_usage_pagemap(uint64_t from, uint64_t to, struct range_usage *usage)
+{
+	int descriptor = simulated_no_pagemap ? -1 : open("/proc/self/pagemap", O_RDONLY | O_CLOEXEC);
 	uint64_t entries[512];
 	uint64_t page = from / PAGE;
-	int unused = 1;
 
-	if (!pagemap)
-		return 0;
-	if (fseeko(pagemap, (off_t)(page * sizeof(uint64_t)), SEEK_SET) != 0)
-		unused = 0;
-	while (unused && page < to / PAGE)
+	if (simulated_no_pagemap)
+		errno = EACCES;
+	if (descriptor < 0)
+	{
+		finding(HOST_LOG_WARN, "cannot read /proc/self/pagemap (%s)", strerror(errno));
+		return RANGE_UNKNOWN;
+	}
+	usage->method = "pagemap";
+	while (page < to / PAGE)
 	{
 		size_t wanted = (size_t)(to / PAGE - page);
-		size_t count;
-		size_t index;
+		ssize_t bytes;
+		size_t count, index;
 
 		if (wanted > sizeof(entries) / sizeof(entries[0]))
 			wanted = sizeof(entries) / sizeof(entries[0]);
-		count = fread(entries, sizeof(entries[0]), wanted, pagemap);
-		if (count != wanted)
+		bytes = pread(descriptor, entries, wanted * sizeof(entries[0]), (off_t)(page * sizeof(entries[0])));
+		if (bytes <= 0 || bytes % sizeof(entries[0]))
 		{
-			unused = 0;
-			break;
+			finding(HOST_LOG_WARN, "cannot read /proc/self/pagemap at %08llx (%s)",
+				(unsigned long long)(page * PAGE), bytes < 0 ? strerror(errno) : "short read");
+			close(descriptor);
+			return RANGE_UNKNOWN;
 		}
-		/* (bit 63 present, bit 62 swapped) */
+		count = (size_t)bytes / sizeof(entries[0]);
 		for (index = 0; index < count; index++)
 		{
 			if (entries[index] & (3ULL << 62))
-			{
-				unused = 0;
-				break;
-			}
+				note_in_use(usage, (page + index) * PAGE);
 		}
 		page += count;
 	}
-	fclose(pagemap);
-	return unused;
+	close(descriptor);
+	return usage->pages_in_use ? RANGE_IN_USE : RANGE_UNUSED;
+}
+
+/* the Swap: line of the /proc/self/smaps entry starting at start, in kB; -1
+if it cannot be read (or no entry starts there); with end, the entry must
+also end there. dont_dump, if not NULL, tells whether its VmFlags have dd
+(MADV_DONTDUMP). */
+static long mapping_swap_kb_ending(uint64_t start, uint64_t end, int *dont_dump)
+{
+	FILE *smaps = fopen("/proc/self/smaps", "r");
+	char line[512];
+	int inside = 0;
+	long result = -1;
+
+	if (dont_dump)
+		*dont_dump = 0;
+	if (!smaps)
+		return -1;
+	while (fgets(line, sizeof(line), smaps))
+	{
+		unsigned long long lo, hi;
+		long kb;
+
+		if (sscanf(line, "%llx-%llx ", &lo, &hi) == 2 && strchr(line, '-') < strchr(line, ' '))
+		{
+			if (inside)
+				break;
+			inside = lo == start && (!end || hi == end);
+			continue;
+		}
+		if (!inside)
+			continue;
+		if (sscanf(line, "Swap: %ld kB", &kb) == 1)
+			result = kb;
+		else if (dont_dump && !strncmp(line, "VmFlags:", 8))
+			*dont_dump = strstr(line, " dd") != NULL;
+	}
+	fclose(smaps);
+	return result;
+}
+
+static long mapping_swap_kb(uint64_t start)
+{
+	return mapping_swap_kb_ending(start, 0, NULL);
+}
+
+/* whether any of from..to (in the mapping starting at mapping_start) is
+swapped out, when that mapping has swap somewhere: smaps counts swap per
+mapping, so the range is made a mapping of its own for a moment
+(MADV_DONTDUMP splits it off and changes nothing about its pages: neither
+ART nor the game ever dumps core), read, and merged back (MADV_DODUMP). Not
+for a mapping already marked so (the restore would then change it). -1 if
+that cannot be done */
+static long range_swap_kb(uint64_t mapping_start, uint64_t from, uint64_t to)
+{
+	int dont_dump;
+	long kb;
+
+	if (mapping_swap_kb_ending(mapping_start, 0, &dont_dump) < 0)
+	{
+		finding(HOST_LOG_WARN, "cannot read the smaps entry of ART's large object space at %08llx",
+			(unsigned long long)mapping_start);
+		return -1;
+	}
+	if (dont_dump)
+	{
+		finding(HOST_LOG_WARN, "ART's large object space at %08llx is marked not to be dumped; "
+			"the swap of %08llx-%08llx cannot be read on its own", (unsigned long long)mapping_start,
+			(unsigned long long)from, (unsigned long long)to);
+		return -1;
+	}
+	if (madvise((void *)from, (size_t)(to - from), MADV_DONTDUMP) != 0)
+	{
+		finding(HOST_LOG_WARN, "cannot split %08llx-%08llx off ART's large object space (%s)",
+			(unsigned long long)from, (unsigned long long)to, strerror(errno));
+		return -1;
+	}
+	kb = mapping_swap_kb_ending(from, to, NULL);
+	madvise((void *)from, (size_t)(to - from), MADV_DODUMP);
+	if (kb < 0)
+		finding(HOST_LOG_WARN, "no smaps entry for %08llx-%08llx once split off", (unsigned long long)from,
+			(unsigned long long)to);
+	return kb;
+}
+
+/* without pagemap (some kernels or policies refuse it): mincore() tells
+which pages are resident, and smaps whether any of the range is swapped
+out, which mincore cannot see */
+static int range_usage_mincore(uint64_t mapping_start, uint64_t from, uint64_t to, struct range_usage *usage)
+{
+	unsigned char residency[4096];
+	uint64_t address = from;
+	long swapped = mapping_swap_kb(mapping_start);
+
+	usage->method = "mincore";
+	if (swapped < 0)
+	{
+		finding(HOST_LOG_WARN, "cannot read the smaps entry of ART's large object space at %08llx",
+			(unsigned long long)mapping_start);
+		return RANGE_UNKNOWN;
+	}
+	if (swapped > 0)
+	{
+		/* (swap somewhere in the space: only the range's own matters) */
+		long range_swapped = range_swap_kb(mapping_start, from, to);
+
+		if (range_swapped < 0)
+			return RANGE_UNKNOWN;
+		if (range_swapped > 0)
+		{
+			/* (objects there, swapped out: which pages smaps does not say) */
+			usage->method = "the range's swap in smaps";
+			usage->pages_in_use = (uint64_t)range_swapped * 1024 / PAGE;
+			usage->lowest_in_use = from;
+			usage->highest_in_use = to - PAGE;
+			return RANGE_IN_USE;
+		}
+		finding(HOST_LOG_INFO, "ART's large object space at %08llx: %ld kB of it swapped out, none of %08llx-%08llx",
+			(unsigned long long)mapping_start, swapped, (unsigned long long)from, (unsigned long long)to);
+	}
+	while (address < to)
+	{
+		uint64_t length = to - address;
+		size_t index;
+
+		if (length > sizeof(residency) * PAGE)
+			length = sizeof(residency) * PAGE;
+		if (mincore((void *)address, length, residency) != 0)
+		{
+			finding(HOST_LOG_WARN, "mincore at %08llx failed (%s)", (unsigned long long)address, strerror(errno));
+			return RANGE_UNKNOWN;
+		}
+		for (index = 0; index < length / PAGE; index++)
+		{
+			if (residency[index] & 1)
+				note_in_use(usage, address + index * PAGE);
+		}
+		address += length;
+	}
+	return usage->pages_in_use ? RANGE_IN_USE : RANGE_UNUSED;
+}
+
+/* whether any page from..to (page aligned) of the mapping starting at
+mapping_start holds data */
+static int range_usage(uint64_t mapping_start, uint64_t from, uint64_t to, struct range_usage *usage)
+{
+	int result;
+
+	memset(usage, 0, sizeof(*usage));
+	result = range_usage_pagemap(from, to, usage);
+	if (result == RANGE_UNKNOWN)
+	{
+		memset(usage, 0, sizeof(*usage));
+		result = range_usage_mincore(mapping_start, from, to, usage);
+	}
+	return result;
 }
 
 static int reclaim_art_overlap(uint64_t address, uint64_t size)
@@ -167,6 +380,7 @@ static int reclaim_art_overlap(uint64_t address, uint64_t size)
 	{
 		unsigned long long lo, hi;
 		uint64_t from, to;
+		struct range_usage usage;
 		char *name;
 		int name_offset = 0;
 
@@ -180,21 +394,31 @@ static int reclaim_art_overlap(uint64_t address, uint64_t size)
 		to = hi < address + size ? hi : address + size;
 		if (strcmp(name, ART_LARGE_OBJECT_SPACE))
 		{
-			host_logf(HOST_LOG_ERROR, "a fixed guest range is overlapped by %08llx-%08llx (%s), which is not ART's large object space; left alone",
+			finding(HOST_LOG_ERROR, "a fixed guest range is overlapped by %08llx-%08llx (%s), which is not ART's large object space; left alone",
 				lo, hi, name[0] ? name : "unnamed");
 			continue;
 		}
-		if (!range_unused(from, to))
+		switch (range_usage(lo, from, to, &usage))
 		{
-			host_logf(HOST_LOG_ERROR, "ART's large object space over %08llx-%08llx is in use (or its pages cannot be read); left alone",
-				(unsigned long long)from, (unsigned long long)to);
+		case RANGE_IN_USE:
+			finding(HOST_LOG_ERROR,
+				"ART's large object space %08llx-%08llx holds objects over %08llx-%08llx "
+				"(%llu pages in use, %08llx-%08llx, by %s); left alone",
+				lo, hi, (unsigned long long)from, (unsigned long long)to,
+				(unsigned long long)usage.pages_in_use, (unsigned long long)usage.lowest_in_use,
+				(unsigned long long)usage.highest_in_use + PAGE, usage.method);
+			continue;
+		case RANGE_UNKNOWN:
+			finding(HOST_LOG_ERROR,
+				"ART's large object space %08llx-%08llx covers %08llx-%08llx, and whether that part is in use "
+				"cannot be told; left alone", lo, hi, (unsigned long long)from, (unsigned long long)to);
 			continue;
 		}
 		if (munmap((void *)from, to - from) == 0)
 		{
 			host_logf(HOST_LOG_INFO,
-				"reclaimed idle ART range %08llx-%08llx (%s)",
-				(unsigned long long)from, (unsigned long long)to, name);
+				"reclaimed idle ART range %08llx-%08llx of %08llx-%08llx (%s, checked by %s)",
+				(unsigned long long)from, (unsigned long long)to, lo, hi, name, usage.method);
 			reclaimed = 1;
 		}
 	}
@@ -214,8 +438,10 @@ static int reserve(uint64_t address, uint64_t size, int reclaim_art)
 		return 0;
 	if (result != MAP_FAILED)
 	{
+		/* (a kernel older than 4.17 takes MAP_FIXED_NOREPLACE as a hint,
+		and maps elsewhere when something is in the way) */
 		munmap(result, size);
-		return -1;
+		errno = EEXIST;
 	}
 	if (reclaim_art && errno == EEXIST)
 	{
@@ -233,11 +459,47 @@ static int reserve(uint64_t address, uint64_t size, int reclaim_art)
 		if (result == (void *)address)
 			return 0;
 		if (result != MAP_FAILED)
+		{
 			munmap(result, size);
+			errno = EEXIST;
+		}
 	}
 	return -1;
 }
 
+/* the mappings below 4 GB, for a report of why the fixed ranges could not
+be had (logcat, and memory_map.txt in the data folder: host_main.c) */
+void host_memory_report_low_mappings(FILE *file)
+{
+	FILE *maps = fopen("/proc/self/maps", "r");
+	char line[512];
+	char model[PROP_VALUE_MAX] = "", heap[PROP_VALUE_MAX] = "", release[PROP_VALUE_MAX] = "";
+
+	__system_property_get("ro.product.model", model);
+	__system_property_get("dalvik.vm.heapsize", heap);
+	__system_property_get("ro.build.version.release", release);
+	if (file)
+	{
+		fprintf(file, "device: %s, Android %s, Java heap %s\n", model[0] ? model : "unknown",
+			release[0] ? release : "unknown", heap[0] ? heap : "unknown");
+		fprintf(file, "why:\n%s\nmappings below 4 GB:\n", findings[0] ? findings : "(no reason recorded)\n");
+	}
+	if (!maps)
+		return;
+	while (fgets(line, sizeof(line), maps))
+	{
+		unsigned long long lo, hi;
+
+		if (sscanf(line, "%llx-%llx", &lo, &hi) != 2 || lo >= LOW_LIMIT)
+			continue;
+		line[strcspn(line, "\n")] = '\0';
+		host_logf(HOST_LOG_INFO, "low mapping: %s", line);
+		if (file)
+			fprintf(file, "%s\n", line);
+	}
+	fclose(maps);
+}
+
 static struct pool *pool_new(void)
 {
 	/* above the image first: ART allocates its own low-4 GB memory from
@@ -274,24 +536,122 @@ static struct pool *pool_new(void)
 	return NULL;
 }
 
+/* The fixed ranges: the Xbox window and, right above it, room for the guest
+image (HALO_GUEST_IMAGE_RESERVE), reserved as early as the process allows
+(host_memory_reserve_early, from JNI_OnLoad) or else when the image loads. */
+static int fixed_reserved;
+static int fixed_error;
+
+/* when: the attempt, as the report names it (the reasons below it are
+those of that attempt) */
+static int reserve_fixed(const char *when)
+{
+	size_t used = strlen(findings);
+
+	if (fixed_reserved)
+		return 0;
+	snprintf(findings + used, sizeof(findings) - used, "%s:\n", when);
+	if (reserve(HALO_GUEST_WINDOW_BASE, HALO_GUEST_WINDOW_SIZE, 1) != 0)
+	{
+		fixed_error = errno;
+		finding(HOST_LOG_ERROR, "cannot reserve the Xbox memory window at %08llx (%s)",
+			(unsigned long long)HALO_GUEST_WINDOW_BASE, strerror(errno));
+		return -1;
+	}
+	if (reserve(HALO_GUEST_IMAGE_BASE, HALO_GUEST_IMAGE_RESERVE, 1) != 0)
+	{
+		fixed_error = errno;
+		finding(HOST_LOG_ERROR, "cannot reserve the guest image range at %08llx (%s)",
+			(unsigned long long)HALO_GUEST_IMAGE_BASE, strerror(errno));
+		munmap((void *)(uintptr_t)HALO_GUEST_WINDOW_BASE, HALO_GUEST_WINDOW_SIZE);
+		return -1;
+	}
+	fixed_reserved = 1;
+	return 0;
+}
+
+int host_memory_fixed_unavailable(void)
+{
+	return !fixed_reserved && fixed_error != 0;
+}
+
+/* For testing the reclaim on any device: with the system property
+debug.halo.art_overlap set (adb shell setprop debug.halo.art_overlap idle,
+or busy), a mapping named as ART's large object space is put over the fixed
+ranges first, idle, or with a page in use inside the window, the way ART's
+is on the devices that need the reclaim. Players never set it.
+
+Either may be followed by -nopagemap, for devices that refuse
+/proc/self/pagemap (the check then falls back to mincore and smaps), and
+by -swapped, which pushes the stand-in's objects (its bottom pages, and the
+window's page if busy) out to swap, as they can be on those devices. */
+#ifndef MADV_PAGEOUT
+#define MADV_PAGEOUT 21
+#endif
+#define PR_SET_VMA_ 0x53564d41
+#define PR_SET_VMA_ANON_NAME_ 0
+#define SIMULATED_SPACE_BASE 0x7c000000ULL
+#define SIMULATED_SPACE_SIZE 0x14000000ULL
+
+static void simulate_art_overlap(void)
+{
+	char value[PROP_VALUE_MAX] = "";
+	char *window_page = (char *)(uintptr_t)HALO_GUEST_WINDOW_BASE + 0x100000;
+	int busy;
+	void *space;
+
+	if (__system_property_get("debug.halo.art_overlap", value) <= 0 || (strncmp(value, "idle", 4) && strncmp(value, "busy", 4)))
+		return;
+	busy = !strncmp(value, "busy", 4);
+	space = mmap((void *)SIMULATED_SPACE_BASE, SIMULATED_SPACE_SIZE, PROT_READ | PROT_WRITE,
+		MAP_PRIVATE | MAP_ANONYMOUS | MAP_NORESERVE | MAP_FIXED_NOREPLACE, -1, 0);
+	if (space != (void *)SIMULATED_SPACE_BASE)
+	{
+		host_logf(HOST_LOG_WARN, "debug.halo.art_overlap: %08llx-%08llx is not free",
+			SIMULATED_SPACE_BASE, SIMULATED_SPACE_BASE + SIMULATED_SPACE_SIZE);
+		if (space != MAP_FAILED)
+			munmap(space, SIMULATED_SPACE_SIZE);
+		return;
+	}
+	prctl(PR_SET_VMA_, PR_SET_VMA_ANON_NAME_, space, SIMULATED_SPACE_SIZE, "dalvik-free list large object space");
+	/* objects at its bottom, as ART allocates them */
+	memset(space, 0x5a, 4 * PAGE);
+	if (busy)
+		memset(window_page, 0x5a, PAGE);
+	if (strstr(value, "-swapped"))
+	{
+		if (madvise(space, 4 * PAGE, MADV_PAGEOUT) != 0 || (busy && madvise(window_page, PAGE, MADV_PAGEOUT) != 0))
+			host_logf(HOST_LOG_WARN, "debug.halo.art_overlap: cannot page out the stand-in (%s)", strerror(errno));
+	}
+	simulated_no_pagemap = strstr(value, "-nopagemap") != NULL;
+	host_logf(HOST_LOG_WARN, "debug.halo.art_overlap=%s: a stand-in for ART's large object space at %08llx-%08llx "
+		"(%ld kB of it swapped out)", value, SIMULATED_SPACE_BASE, SIMULATED_SPACE_BASE + SIMULATED_SPACE_SIZE,
+		mapping_swap_kb(SIMULATED_SPACE_BASE));
+}
+
+void host_memory_reserve_early(void)
+{
+	simulate_art_overlap();
+	if (reserve_fixed("at start-up (JNI_OnLoad)") == 0)
+		host_logf(HOST_LOG_INFO, "reserved the Xbox memory window and the image range at start-up");
+}
+
 int host_memory_initialize(uint32_t base, uint32_t size)
 {
+	if (base != HALO_GUEST_IMAGE_BASE || size > HALO_GUEST_IMAGE_RESERVE)
+	{
+		host_logf(HOST_LOG_ERROR, "the guest image (%08x, %u bytes) does not fit its range", base, size);
+		return -1;
+	}
+	if (reserve_fixed("when the image loaded") != 0)
+	{
+		errno = fixed_error;
+		return -1;
+	}
 	window_base = HALO_GUEST_WINDOW_BASE;
 	window_end = window_base + HALO_GUEST_WINDOW_SIZE;
-	if (reserve(window_base, HALO_GUEST_WINDOW_SIZE, 1) != 0)
-	{
-		host_logf(HOST_LOG_ERROR, "cannot reserve the Xbox memory window at %08llx (%s)",
-			(unsigned long long)window_base, strerror(errno));
-		return -1;
-	}
 	image_base = base;
 	image_end = base + round_up(size);
-	if (reserve(image_base, image_end - image_base, 1) != 0)
-	{
-		host_logf(HOST_LOG_ERROR, "cannot reserve the guest image range at %08llx (%s)",
-			(unsigned long long)image_base, strerror(errno));
-		return -1;
-	}
 	return 0;
 }
 
@@ -478,6 +838,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 +976,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 +994,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 +1014,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 +1027,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 +1037,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 +1061,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 +1073,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);
+}

port/android/host/host_sdl.c

@@ -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)
@@ -395,3 +514,35 @@ int host_sdl_show_simple_message_box(uint32_t flags, const char *title, const ch
 {
 	return SDL_ShowSimpleMessageBox((SDL_MessageBoxFlags)flags, title, message, NULL) ? 1 : 0;
 }
+
+/* ---------- a question for the player (the mods at startup: port_mods.c) */
+
+int host_sdl_show_message_box(uint32_t flags, const char *title, const char *message, int default_index,
+	const char *button0, const char *button1, const char *button2)
+{
+	const char *labels[3] = { button0, button1, button2 };
+	SDL_MessageBoxButtonData buttons[3];
+	SDL_MessageBoxData question;
+	int count = 0;
+	int answer = -1;
+	int index;
+
+	for (index = 0; index < 3; index++)
+	{
+		if (!labels[index])
+			continue;
+		buttons[count].flags = index == default_index ?
+			SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT | SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT : 0;
+		buttons[count].buttonID = index;
+		buttons[count].text = labels[index];
+		count++;
+	}
+	question.flags = (SDL_MessageBoxFlags)flags;
+	question.window = NULL;
+	question.title = title;
+	question.message = message;
+	question.numbuttons = count;
+	question.buttons = buttons;
+	question.colorScheme = NULL;
+	return SDL_ShowMessageBox(&question, &answer) ? answer : -1;
+}

port/android/host/host_thread.c

@@ -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;
 

port/android/host/host_touch.c

@@ -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;
+}

port/android/host/host_watch_hash.c

@@ -0,0 +1,180 @@
+/*
+HOST_WATCH_HASH.C
+
+Write tracking by page contents (host_watch_hash.h).
+*/
+
+#include "host_watch_hash.h"
+
+#ifdef __wasm_simd128__
+/*
+FNV-style mixing in sixteen independent 32-bit lanes, four vectors of four
+(WebAssembly's SIMD: the web build, web_memory_watch.c), so that no lane
+waits for another and the multiplies are the vector unit's own; its 64-bit
+multiplies are scalar, which made the hashing of every watched page each
+frame a quarter of the web build's frame, twice what this takes. A change of
+one word changes its lane's state for good (xor and an odd multiply are both
+invertible), and the fold keeps every lane's bits, 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)
+*/
+typedef uint32_t watch_hash_lanes __attribute__((vector_size(16), aligned(4), may_alias));
+
+uint64_t watch_hash_page(const uint8_t *page)
+{
+	const watch_hash_lanes *words = (const watch_hash_lanes *)page;
+	const watch_hash_lanes prime = { 0x01000193u, 0x01000193u, 0x01000193u, 0x01000193u };
+	watch_hash_lanes lane0 = { 0x811c9dc5u, 0x9e3779b9u, 0x85ebca6bu, 0xc2b2ae35u };
+	watch_hash_lanes lane1 = { 0x27d4eb2fu, 0x165667b1u, 0xd3a2646cu, 0xfd7046c5u };
+	watch_hash_lanes lane2 = { 0xb55a4f09u, 0x7feb352du, 0x846ca68bu, 0x2c1b3c6du };
+	watch_hash_lanes lane3 = { 0x297a2d39u, 0xe6546b64u, 0xcc9e2d51u, 0x1b873593u };
+	watch_hash_lanes folded;
+	uint32_t index;
+
+	for (index = 0; index < WATCH_HASH_PAGE_SIZE / sizeof(watch_hash_lanes); index += 4)
+	{
+		lane0 = (lane0 ^ words[index + 0]) * prime;
+		lane1 = (lane1 ^ words[index + 1]) * prime;
+		lane2 = (lane2 ^ words[index + 2]) * prime;
+		lane3 = (lane3 ^ words[index + 3]) * prime;
+	}
+	/* (each vector's lanes turned before they are combined, so that the same
+	change in two of them does not cancel) */
+	folded = lane0 ^ ((lane1 << 8) | (lane1 >> 24)) ^ ((lane2 << 16) | (lane2 >> 16)) ^ ((lane3 << 24) | (lane3 >> 8));
+	return ((uint64_t)(folded[0] ^ ((folded[2] << 13) | (folded[2] >> 19))) << 32) |
+		(folded[1] ^ ((folded[3] << 13) | (folded[3] >> 19)));
+}
+#else
+/*
+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));
+}
+#endif
+
+/* 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;
+		if (watch->unchanged)
+			watch->unchanged[page] = 0;
+	}
+}
+
+/* a stable page hashed recently enough: not hashed again yet
+(host_watch_hash.h) */
+static int stable_for_now(const struct watch_hash *watch, uint32_t page)
+{
+	return watch->unchanged && watch->unchanged[page] >= WATCH_HASH_STABLE_CHECKS &&
+		watch->frame - watch->hashed_frame[page] < WATCH_HASH_STABLE_FRAMES;
+}
+
+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 && !stable_for_now(watch, page))
+		{
+			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->unchanged)
+					watch->unchanged[page] = 0;
+			}
+			else if (watch->unchanged && watch->unchanged[page] < WATCH_HASH_STABLE_CHECKS)
+			{
+				watch->unchanged[page]++;
+			}
+		}
+		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);
+	}
+}
+
+void watch_hash_prepare_write(struct watch_hash *watch, uint32_t first, uint32_t last)
+{
+	uint32_t page;
+
+	if (!watch->unchanged || !clamp(watch, first, &last))
+		return;
+	for (page = first; page <= last; page++)
+		watch->unchanged[page] = 0;
+}
+
+/*
+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);
+}

port/android/host/host_watch_hash.h

@@ -0,0 +1,74 @@
+/*
+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.
+
+Hashing every page drawn from each frame is a large part of the frame on
+the web (port/web/src/web_memory_watch.c), where most of them never change
+once loaded. With the optional unchanged counts, a page whose hash stayed the
+same WATCH_HASH_STABLE_CHECKS times in a row is hashed only every
+WATCH_HASH_STABLE_FRAMES frames, until a write into it is announced
+(watch_hash_prepare_write: the file layer's reads, the Direct3D locks) or
+its hash changes. A write that is not announced into such a page is seen up
+to that many frames late.
+*/
+
+#ifndef HOST_WATCH_HASH_H
+#define HOST_WATCH_HASH_H
+
+#include <stdint.h>
+
+#define WATCH_HASH_PAGE_SIZE 0x1000u
+#define WATCH_HASH_STABLE_CHECKS 30u
+#define WATCH_HASH_STABLE_FRAMES 60u
+
+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;
+	/* NULL, or page_count entries: the checks in a row that found the page
+	unchanged (up to WATCH_HASH_STABLE_CHECKS) */
+	uint8_t *unchanged;
+};
+
+/* 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 stable one may wait,
+above); 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);
+
+/* The pages are about to be written: hash them every frame again. */
+void watch_hash_prepare_write(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

port/android/host_imports.list

@@ -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
@@ -31,6 +32,7 @@ host_sdl_set_clipboard_text
 host_sdl_get_clipboard_text
 host_sdl_show_toast
 host_sdl_show_simple_message_box
+host_sdl_show_message_box
 host_sdl_get_gamepads
 host_sdl_open_gamepad
 host_sdl_gamepad_from_id
@@ -38,12 +40,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
@@ -51,6 +59,14 @@ host_gl_fence_frame
 host_gl_wait_frame
 host_gl_counters_snapshot
 host_gl_counters_read
+host_gl_worker_start
+host_gl_program_request
+host_gl_program_hurry
+host_gl_program_poll
+host_gl_program_binary
+host_gl_program_release
+host_gl_worker_waiting
+host_gl_program_warm_up
 host_xr_initialize
 host_xr_begin_frame
 host_xr_copy_layer
@@ -59,6 +75,15 @@ 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_xr_gpu_time
 host_android_path
+host_gesture_insets
+host_touch_read
+host_touch_look_read
+host_touch_rumble
+host_touch_scene
+host_touch_bindings
 
 host_errno

port/android/include/halo_android_abi.h

@@ -29,13 +29,15 @@ This header is included by both halves.
 /* the guest image is linked to run here, just above the Xbox window: ART
 keeps its heaps low in the address space and fills it upwards */
 #define HALO_GUEST_IMAGE_BASE 0x88000000u
+/* the room the host reserves for the image there (port/android/host/host_memory.c) */
+#define HALO_GUEST_IMAGE_RESERVE 0x04000000u
 
 /* the Xbox contiguous memory window (port/linux/src/platform.h) */
 #define HALO_GUEST_WINDOW_BASE 0x80000000u
 #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 +51,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;
 };

port/android/include/halo_xr_abi.h

@@ -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

port/android/patches/sdl-relative-mouse.patch

@@ -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);

port/android/steam_frame_install.sh

@@ -0,0 +1,292 @@
+#!/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 build's number: the launcher updates from it, steam_frame_launch.sh;
+# an update fetched for an older build is dropped)
+cp "$BUNDLE/build.txt" "$GAME_DIR/build.txt" 2>/dev/null || rm -f "$GAME_DIR/build.txt"
+rm -rf "$GAME_DIR/update"
+
+# --- 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

port/android/steam_frame_installer.desktop

@@ -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"

port/android/steam_frame_launch.sh

@@ -0,0 +1,158 @@
+#!/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
+}
+
+# Updates (update.auto in config.toml; the game's own updater, the Quest's,
+# does nothing here: Lepton installs the APK in this folder each start).
+# While the game runs, the latest release is looked for; a newer one's
+# bundle is fetched into update/, checked, and put in place as the next
+# start begins, before Lepton runs the APK (it installs the newer one).
+# A build that knows no number of its own (build.txt: a local one) never
+# looks. Nothing changes without the internet, or when anything fails.
+REPOSITORY="@REPOSITORY@"
+UPDATE="$DATA/update"
+BUILD_FILE="$DATA/build.txt"
+SELF="$DATA/ringfall-mjolnir-vr.sh"
+
+update_apply()
+{
+    local new="$UPDATE/bundle" build
+    [ -f "$UPDATE/ready" ] || { rm -rf "$UPDATE"; return 0; }
+    build=$(cat "$new/build.txt" 2>/dev/null)
+    # (the launcher renamed over this one: bash goes on reading its own copy)
+    if cp "$new/ringfall-mjolnir-vr.sh" "$SELF.tmp" && chmod 755 "$SELF.tmp" &&
+        cp "$new/RingfallMjolnirVR.apk" "$APK.tmp" && chmod 666 "$APK.tmp" &&
+        mv -f "$SELF.tmp" "$SELF" && mv -f "$APK.tmp" "$APK" && touch "$APK" &&
+        cp "$new/build.txt" "$BUILD_FILE"
+    then
+        log "update: build $build put in place"
+    else
+        log "update: build $build could not be put in place"
+        rm -f "$SELF.tmp" "$APK.tmp"
+    fi
+    rm -rf "$UPDATE"
+}
+
+update_wanted()
+{
+    # (update.auto = false in config.toml's [update]: never)
+    ! awk '/^\[/ { section = $0 } section == "[update]" && /^[ \t]*auto[ \t]*=/ { print $3 }' \
+        "$DATA/config.toml" 2>/dev/null | grep -q false
+}
+
+update_check()
+{
+    local installed latest
+    installed=$(cat "$BUILD_FILE" 2>/dev/null)
+    [[ "$installed" =~ ^[0-9]+$ ]] && (( installed > 0 )) || return 0
+    update_wanted || return 0
+    latest=$(curl -fsSL --max-time 20 -H "Accept: application/vnd.github+json" \
+        "https://api.github.com/repos/$REPOSITORY/releases/latest" |
+        python3 -I -c 'import json, sys; print(json.load(sys.stdin)["tag_name"].rpartition("-")[2])' 2>/dev/null)
+    [[ "$latest" =~ ^[0-9]+$ ]] && (( latest > installed )) || return 0
+    log "update: build $latest found (this is $installed), fetching it"
+    rm -rf "$UPDATE" && mkdir -p "$UPDATE" || return 0
+    if curl -fsSL --retry 2 --max-time 900 -o "$UPDATE/bundle.zip" \
+            "https://github.com/$REPOSITORY/releases/download/build-$latest/ringfall-mjolnir-vr-steam-frame.zip" &&
+        python3 -I -m zipfile -e "$UPDATE/bundle.zip" "$UPDATE/bundle" &&
+        [ "$(cat "$UPDATE/bundle/build.txt" 2>/dev/null)" = "$latest" ] &&
+        [ -s "$UPDATE/bundle/RingfallMjolnirVR.apk" ] && [ -s "$UPDATE/bundle/ringfall-mjolnir-vr.sh" ]
+    then
+        rm -f "$UPDATE/bundle.zip"
+        touch "$UPDATE/ready"
+        log "update: build $latest fetched, put in place at the next start"
+    else
+        log "update: build $latest could not be fetched"
+        rm -rf "$UPDATE"
+    fi
+}
+
+update_apply
+update_check </dev/null >/dev/null 2>&1 &
+updater=$!
+
+# (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"
+# (a fetch still under way is given up: the next start looks again)
+pkill -P "$updater" 2>/dev/null
+kill "$updater" 2>/dev/null
+log "end"

port/android/steam_frame_xiso.py

@@ -0,0 +1,251 @@
+#!/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 maps_language(name):
+    """a language's maps folder's language ("maps_it": "it"), else None"""
+    if len(name) == 7 and name[:5].lower() == "maps_" and name[5:].isalpha():
+        return name[5:].lower()
+    return None
+
+
+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"]
+        # (a European disc in two languages, Spanish and Italian, has a maps
+        # folder for each, maps_es and maps_it: the one for the language
+        # asked for (RINGFALL_LANGUAGE, else the system's), else English's,
+        # else the first; its language goes into maps/language.txt, which the
+        # game takes as game.language's when that is unset)
+        language = None
+        if not maps:
+            languages = [(maps_language(entry[0]), entry) for entry in directories if maps_language(entry[0])]
+            wanted = (os.environ.get("RINGFALL_LANGUAGE") or os.environ.get("LC_ALL") or
+                os.environ.get("LC_MESSAGES") or os.environ.get("LANG") or "")[:2].lower()
+            for preferred in (wanted, "en"):
+                chosen = [pair for pair in languages if pair[0] == preferred]
+                if chosen:
+                    break
+            chosen = chosen or languages[:1]
+            if chosen:
+                language, entry = chosen[0]
+                maps = [entry]
+        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)
+        language_file = os.path.join(finished, "language.txt")
+        if os.path.exists(language_file):
+            os.remove(language_file)
+        if language:
+            with open(language_file, "w") as out:
+                out.write(language + "\n")
+    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())

port/android/tests/host_watch_hash_test.c

@@ -0,0 +1,272 @@
+/*
+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];
+	uint8_t unchanged[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);
+}
+
+/* a page unchanged for long: hashed every few frames, or at once again
+after a write is announced */
+static void test_stable_page_is_hashed_less_often(void)
+{
+	struct fixture f;
+	uint32_t before, check, frame;
+
+	setup(&f);
+	f.watch.unchanged = f.unchanged;
+	watch_hash_protect(&f.watch, 1, 1);
+	for (check = 0; check < WATCH_HASH_STABLE_CHECKS; check++)
+	{
+		watch_hash_begin_frame(&f.watch);
+		watch_hash_generation(&f.watch, 1, 1);
+	}
+	CHECK(f.unchanged[1] == WATCH_HASH_STABLE_CHECKS);
+	before = watch_hash_generation(&f.watch, 1, 1);
+	*byte_of(&f, 1, 40) ^= 1;
+	watch_hash_begin_frame(&f.watch);
+	CHECK(watch_hash_generation(&f.watch, 1, 1) == before);
+	/* seen within WATCH_HASH_STABLE_FRAMES frames all the same */
+	for (frame = 2; frame < WATCH_HASH_STABLE_FRAMES; frame++)
+	{
+		watch_hash_begin_frame(&f.watch);
+		watch_hash_generation(&f.watch, 1, 1);
+	}
+	watch_hash_begin_frame(&f.watch);
+	CHECK(watch_hash_generation(&f.watch, 1, 1) > before);
+	CHECK(f.unchanged[1] == 0);
+	teardown(&f);
+}
+
+static void test_announced_write_is_seen_next_frame(void)
+{
+	struct fixture f;
+	uint32_t before, check;
+
+	setup(&f);
+	f.watch.unchanged = f.unchanged;
+	watch_hash_protect(&f.watch, 2, 2);
+	for (check = 0; check < WATCH_HASH_STABLE_CHECKS; check++)
+	{
+		watch_hash_begin_frame(&f.watch);
+		watch_hash_generation(&f.watch, 2, 2);
+	}
+	before = watch_hash_generation(&f.watch, 2, 2);
+	watch_hash_prepare_write(&f.watch, 2, 2);
+	*byte_of(&f, 2, 4000) ^= 1;
+	watch_hash_begin_frame(&f.watch);
+	CHECK(watch_hash_generation(&f.watch, 2, 2) > before);
+	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();
+	test_stable_page_is_hashed_less_often();
+	test_announced_write_is_seen_next_frame();
+	if (failures)
+		printf("%d failures\n", failures);
+	else
+		printf("all tests passed\n");
+	return failures != 0;
+}

port/android/xr_layer/fdm_injection_stub.c

@@ -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;
+}

port/assets/buttons/buttons.json

@@ -0,0 +1,526 @@
+{
+ "assets": [
+  {
+   "name": "a_butn__0",
+   "tag": "ui\\shell\\bitmaps\\a_butn",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 1140253829,
+   "svg": "a_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "letter": [
+    -0.006,
+    0.0
+   ]
+  },
+  {
+   "name": "b_butn__0",
+   "tag": "ui\\shell\\bitmaps\\b_butn",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 2900806204,
+   "svg": "b_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "letter": [
+    0.001,
+    0.002
+   ]
+  },
+  {
+   "name": "x_butn__0",
+   "tag": "ui\\shell\\bitmaps\\x_butn",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 2247463469,
+   "svg": "x_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "letter": [
+    -0.002,
+    -0.008
+   ]
+  },
+  {
+   "name": "y_butn__0",
+   "tag": "ui\\shell\\bitmaps\\y_butn",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 783963872,
+   "svg": "y_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "letter": [
+    -0.009,
+    0.028
+   ]
+  },
+  {
+   "name": "a_butn_sm__0",
+   "tag": "ui\\shell\\bitmaps\\a_butn_sm",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 2356213272,
+   "svg": "a_butn.svg",
+   "place": [
+    0.7702,
+    -0.222,
+    -0.272
+   ],
+   "letter": [
+    0.014,
+    0.071
+   ]
+  },
+  {
+   "name": "b_butn_sm__0",
+   "tag": "ui\\shell\\bitmaps\\b_butn_sm",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 3999851658,
+   "svg": "b_butn.svg",
+   "place": [
+    0.7677,
+    -0.14,
+    -0.225
+   ],
+   "letter": [
+    -0.054,
+    0.062
+   ]
+  },
+  {
+   "name": "hud_msg_icons_sm__0",
+   "tag": "ui\\hud\\bitmaps\\hud_msg_icons_sm",
+   "bitmap": 0,
+   "width": 128,
+   "height": 128,
+   "format": "a8y8",
+   "scale": 8,
+   "crc": 2908635490,
+   "sprites": [
+    {
+     "sequence": 0,
+     "cell": [
+      68,
+      21,
+      84,
+      41
+     ],
+     "svg": "a_butn.svg",
+     "place": [
+      0.7063,
+      1.04,
+      1.026
+     ],
+     "letter": [
+      0.119,
+      0.079
+     ]
+    },
+    {
+     "sequence": 1,
+     "cell": [
+      103,
+      0,
+      119,
+      20
+     ],
+     "svg": "b_butn.svg",
+     "place": [
+      0.681,
+      1.667,
+      1.601
+     ],
+     "letter": [
+      0.474,
+      0.082
+     ]
+    },
+    {
+     "sequence": 2,
+     "cell": [
+      71,
+      0,
+      87,
+      20
+     ],
+     "svg": "x_butn.svg",
+     "place": [
+      0.6987,
+      1.023,
+      1.294
+     ],
+     "letter": [
+      0.235,
+      1.718
+     ]
+    },
+    {
+     "sequence": 3,
+     "cell": [
+      87,
+      0,
+      103,
+      20
+     ],
+     "svg": "y_butn.svg",
+     "place": [
+      0.6992,
+      1.071,
+      1.29
+     ],
+     "letter": [
+      -0.306,
+      1.601
+     ]
+    }
+   ]
+  },
+  {
+   "name": "black_butn__0",
+   "tag": "ui\\shell\\bitmaps\\black_butn",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "svg": "black_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ]
+  },
+  {
+   "name": "white_butn__0",
+   "tag": "ui\\shell\\bitmaps\\white_butn",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "svg": "white_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ]
+  },
+  {
+   "name": "classic_a__0",
+   "tag": "ui\\hud\\buttons\\classic_a",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "svg": "a_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "classic": "#40eb40",
+   "letter": [
+    0.1685,
+    0.1119
+   ]
+  },
+  {
+   "name": "classic_b__0",
+   "tag": "ui\\hud\\buttons\\classic_b",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "svg": "b_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "classic": "#fa5946",
+   "letter": [
+    0.696,
+    0.1204
+   ]
+  },
+  {
+   "name": "classic_x__0",
+   "tag": "ui\\hud\\buttons\\classic_x",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "svg": "x_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "classic": "#3998fa",
+   "letter": [
+    0.3363,
+    2.4589
+   ]
+  },
+  {
+   "name": "classic_y__0",
+   "tag": "ui\\hud\\buttons\\classic_y",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "svg": "y_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "classic": "#f9e928",
+   "letter": [
+    -0.4376,
+    2.2898
+   ]
+  },
+  {
+   "name": "classic_black__0",
+   "tag": "ui\\hud\\buttons\\classic_black",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "svg": "black_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "classic": "#000000"
+  },
+  {
+   "name": "classic_white__0",
+   "tag": "ui\\hud\\buttons\\classic_white",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "svg": "white_butn.svg",
+   "place": [
+    1,
+    0,
+    0
+   ],
+   "classic": "#ffffff"
+  },
+  {
+   "name": "gem_a__0",
+   "tag": "ui\\hud\\buttons\\gem_a",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/a_gem.png"
+  },
+  {
+   "name": "gem_b__0",
+   "tag": "ui\\hud\\buttons\\gem_b",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/b_gem.png"
+  },
+  {
+   "name": "gem_x__0",
+   "tag": "ui\\hud\\buttons\\gem_x",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/x_gem.png"
+  },
+  {
+   "name": "gem_y__0",
+   "tag": "ui\\hud\\buttons\\gem_y",
+   "bitmap": 0,
+   "width": 32,
+   "height": 32,
+   "format": "dxt3",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/y_gem.png"
+  },
+  {
+   "name": "trigger_left__0",
+   "tag": "ui\\hud\\buttons\\trigger_left",
+   "bitmap": 0,
+   "width": 64,
+   "height": 64,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/trigger_left.png",
+   "control_cell": [
+    50,
+    35
+   ]
+  },
+  {
+   "name": "trigger_right__0",
+   "tag": "ui\\hud\\buttons\\trigger_right",
+   "bitmap": 0,
+   "width": 64,
+   "height": 64,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/trigger_right.png",
+   "control_cell": [
+    50,
+    35
+   ]
+  },
+  {
+   "name": "thumbstick_left__0",
+   "tag": "ui\\hud\\buttons\\thumbstick_left",
+   "bitmap": 0,
+   "width": 64,
+   "height": 64,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/thumbstick_left.png",
+   "control_cell": [
+    36,
+    40
+   ]
+  },
+  {
+   "name": "thumbstick_right__0",
+   "tag": "ui\\hud\\buttons\\thumbstick_right",
+   "bitmap": 0,
+   "width": 64,
+   "height": 64,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/thumbstick_right.png",
+   "control_cell": [
+    36,
+    40
+   ]
+  },
+  {
+   "name": "thumbstick-halfway_left__0",
+   "tag": "ui\\hud\\buttons\\thumbstick-halfway_left",
+   "bitmap": 0,
+   "width": 64,
+   "height": 64,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/thumbstick-halfway_left.png",
+   "control_cell": [
+    36,
+    40
+   ]
+  },
+  {
+   "name": "thumbstick-halfway_right__0",
+   "tag": "ui\\hud\\buttons\\thumbstick-halfway_right",
+   "bitmap": 0,
+   "width": 64,
+   "height": 64,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/thumbstick-halfway_right.png",
+   "control_cell": [
+    36,
+    40
+   ]
+  },
+  {
+   "name": "thumbstick-full_left__0",
+   "tag": "ui\\hud\\buttons\\thumbstick-full_left",
+   "bitmap": 0,
+   "width": 64,
+   "height": 64,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/thumbstick-full_left.png",
+   "control_cell": [
+    36,
+    40
+   ]
+  },
+  {
+   "name": "thumbstick-full_right__0",
+   "tag": "ui\\hud\\buttons\\thumbstick-full_right",
+   "bitmap": 0,
+   "width": 64,
+   "height": 64,
+   "format": "a8r8g8b8",
+   "scale": 8,
+   "crc": 0,
+   "source_png": "source/thumbstick-full_right.png",
+   "control_cell": [
+    36,
+    40
+   ]
+  }
+ ]
+}

port/assets/buttons/svg/a_butn.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+<!-- The A button of the menus' button keys (ui\shell\bitmaps\a_butn), redrawn: drawn
+in the 32x32 bitmap's texels, where its art is (tools/button_assets.py). A tilted
+green oval, dark at the top and bright at the bottom, with a pale rim, and its
+letter in white, upright from its baseline and slanted. -->
+<defs>
+<!-- (along the oval's long axis, top to bottom) -->
+<linearGradient id="body" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#08370f"/>
+<stop offset="0.5" stop-color="#056a1c"/>
+<stop offset="1" stop-color="#0a9924"/>
+</linearGradient>
+<linearGradient id="rim" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#ffffff" stop-opacity="0.74"/>
+<stop offset="1" stop-color="#ffffff" stop-opacity="0.73"/>
+</linearGradient>
+</defs>
+<g transform="translate(10.341 12.879) rotate(-26.459)">
+<ellipse id="oval" rx="8.659" ry="12.932" fill="url(#body)"/>
+<ellipse rx="8.082" ry="12.355" fill="none" stroke="url(#rim)" stroke-width="1.154"/>
+</g>
+<path id="letter" transform="matrix(1 0 -0.185 1 9.644 16.929)" fill="#ffffff"
+d="M-1.508,-11.229 L0.746,-11.229 L-3.038,0.000 L-5.292,0.000 Z M5.292,0.000 L3.038,0.000 L-0.746,-11.229 L1.508,-11.229 Z M-2.739,-4.232 L2.739,-4.232 L3.285,-2.613 L-3.285,-2.613 Z"/>
+</svg>

port/assets/buttons/svg/b_butn.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+<!-- The B button of the menus' button keys (ui\shell\bitmaps\b_butn), redrawn: drawn
+in the 32x32 bitmap's texels, where its art is (tools/button_assets.py). A tilted
+red oval, dark at the top and bright at the bottom, with a pale rim, and its
+letter in white, upright from its baseline and slanted. -->
+<defs>
+<!-- (along the oval's long axis, top to bottom) -->
+<linearGradient id="body" gradientUnits="userSpaceOnUse" x1="0" y1="-13.053" x2="0" y2="13.053">
+<stop offset="0" stop-color="#660f13"/>
+<stop offset="0.5" stop-color="#b50000"/>
+<stop offset="1" stop-color="#ff0200"/>
+</linearGradient>
+<linearGradient id="rim" gradientUnits="userSpaceOnUse" x1="0" y1="-13.053" x2="0" y2="13.053">
+<stop offset="0" stop-color="#ffffff" stop-opacity="0.72"/>
+<stop offset="1" stop-color="#ffffff" stop-opacity="0.79"/>
+</linearGradient>
+</defs>
+<g transform="translate(10.193 12.921) rotate(-27.868)">
+<ellipse id="oval" rx="9.041" ry="13.053" fill="url(#body)"/>
+<ellipse rx="8.452" ry="12.464" fill="none" stroke="url(#rim)" stroke-width="1.178"/>
+</g>
+<path id="letter" transform="matrix(1 0 -0.185 1 3.807 16.894)" fill="#ffffff"
+d="M0.000,-11.283 L5.649,-11.283 A3.265,3.265 0 0 1 8.914,-8.018 A3.265,3.265 0 0 1 5.649,-4.753 L0.000,-4.753 Z M0.000,-6.538 L6.095,-6.538 A3.238,3.238 0 0 1 9.333,-3.300 L9.333,-3.238 A3.238,3.238 0 0 1 6.095,0.000 L0.000,0.000 Z M2.188,-9.498 L2.188,-6.538 L5.246,-6.538 A1.480,1.480 0 0 0 6.726,-8.018 A1.480,1.480 0 0 0 5.246,-9.498 Z M2.188,-4.753 L2.188,-1.785 L6.095,-1.785 A1.050,1.050 0 0 0 7.145,-2.835 L7.145,-3.704 A1.050,1.050 0 0 0 6.095,-4.753 Z"/>
+</svg>

port/assets/buttons/svg/black_butn.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+
+<!-- Original Xbox black button, derived from the OpenCE button redraw. -->
+<defs>
+
+<linearGradient id="body" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#050505"/>
+<stop offset="0.5" stop-color="#202020"/>
+<stop offset="1" stop-color="#454545"/>
+</linearGradient>
+<linearGradient id="rim" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#ffffff" stop-opacity="0.74"/>
+<stop offset="1" stop-color="#ffffff" stop-opacity="0.73"/>
+</linearGradient>
+</defs>
+<g transform="translate(10.341 12.879) rotate(-26.459)">
+<ellipse id="oval" rx="8.659" ry="12.932" fill="url(#body)"/>
+<ellipse rx="8.082" ry="12.355" fill="none" stroke="url(#rim)" stroke-width="1.154"/>
+</g>
+
+</svg>

port/assets/buttons/svg/white_butn.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+
+<!-- Original Xbox white button, derived from the OpenCE button redraw. -->
+<defs>
+
+<linearGradient id="body" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#999999"/>
+<stop offset="0.5" stop-color="#dddddd"/>
+<stop offset="1" stop-color="#ffffff"/>
+</linearGradient>
+<linearGradient id="rim" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#ffffff" stop-opacity="0.74"/>
+<stop offset="1" stop-color="#ffffff" stop-opacity="0.73"/>
+</linearGradient>
+</defs>
+<g transform="translate(10.341 12.879) rotate(-26.459)">
+<ellipse id="oval" rx="8.659" ry="12.932" fill="url(#body)"/>
+<ellipse rx="8.082" ry="12.355" fill="none" stroke="url(#rim)" stroke-width="1.154"/>
+</g>
+
+</svg>

port/assets/buttons/svg/x_butn.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+<!-- The X button of the menus' button keys (ui\shell\bitmaps\x_butn), redrawn: drawn
+in the 32x32 bitmap's texels, where its art is (tools/button_assets.py). A tilted
+blue oval, dark at the top and bright at the bottom, with a pale rim, and its
+letter in white, upright from its baseline and slanted. -->
+<defs>
+<!-- (along the oval's long axis, top to bottom) -->
+<linearGradient id="body" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#0d1c3d"/>
+<stop offset="0.5" stop-color="#08266c"/>
+<stop offset="1" stop-color="#05349d"/>
+</linearGradient>
+<linearGradient id="rim" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#ffffff" stop-opacity="0.75"/>
+<stop offset="1" stop-color="#ffffff" stop-opacity="0.74"/>
+</linearGradient>
+</defs>
+<g transform="translate(10.341 12.879) rotate(-26.459)">
+<ellipse id="oval" rx="8.659" ry="12.932" fill="url(#body)"/>
+<ellipse rx="8.082" ry="12.355" fill="none" stroke="url(#rim)" stroke-width="1.154"/>
+</g>
+<path id="letter" transform="matrix(1 0 -0.185 1 8.621 16.043)" fill="#ffffff"
+d="M-4.981,-10.970 L-2.302,-10.970 L5.237,0.000 L2.558,0.000 Z M2.302,-10.970 L4.981,-10.970 L-2.558,0.000 L-5.237,0.000 Z"/>
+</svg>

port/assets/buttons/svg/y_butn.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+<!-- The Y button of the menus' button keys (ui\shell\bitmaps\y_butn), redrawn: drawn
+in the 32x32 bitmap's texels, where its art is (tools/button_assets.py). A tilted
+yellow oval, dark at the top and bright at the bottom, with a pale rim, and its
+letter in white, upright from its baseline and slanted,
+casting a dark shadow down and to the right. -->
+<defs>
+<!-- (along the oval's long axis, top to bottom) -->
+<linearGradient id="body" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#504505"/>
+<stop offset="0.5" stop-color="#bb7c03"/>
+<stop offset="1" stop-color="#ffbc00"/>
+</linearGradient>
+<linearGradient id="rim" gradientUnits="userSpaceOnUse" x1="0" y1="-12.932" x2="0" y2="12.932">
+<stop offset="0" stop-color="#ffffff" stop-opacity="0.71"/>
+<stop offset="1" stop-color="#ffffff" stop-opacity="0.63"/>
+</linearGradient>
+</defs>
+<g transform="translate(10.341 12.879) rotate(-26.459)">
+<ellipse id="oval" rx="8.659" ry="12.932" fill="url(#body)"/>
+<ellipse rx="8.082" ry="12.355" fill="none" stroke="url(#rim)" stroke-width="1.154"/>
+</g>
+<path id="shadow" transform="matrix(1 0 -0.185 1 10.387 16.978)" fill="#3c1e00" fill-opacity="0.60"
+d="M-5.184,-11.167 L-2.927,-11.167 L1.047,-4.308 L-1.047,-4.308 Z M2.927,-11.167 L5.184,-11.167 L1.047,-4.308 L-1.047,-4.308 Z M-1.047,-4.908 L1.047,-4.908 L1.047,0.000 L-1.047,0.000 Z"/>
+<path id="letter" transform="matrix(1 0 -0.185 1 8.887 15.778)" fill="#ffffff"
+d="M-5.184,-11.167 L-2.927,-11.167 L1.047,-4.308 L-1.047,-4.308 Z M2.927,-11.167 L5.184,-11.167 L1.047,-4.308 L-1.047,-4.308 Z M-1.047,-4.908 L1.047,-4.908 L1.047,0.000 L-1.047,0.000 Z"/>
+</svg>