Merge branch 'main' into vr

fix(runtime): start a queued game after leaving the current one
docs(changelog): merge the two Changed sections under Unreleased
2026-10-17 19:00:48 +02:00 · 2026-10-16 01:22:27 -05:00 · 2026-10-16 01:19:29 -05:00 · 2026-10-16 01:14:12 -05:00 · 2026-10-16 01:13:49 -05:00 · 2026-10-16 01:12:21 -05:00
178 changed files with 34870 additions and 930 deletions
@@ -0,0 +1,119 @@
+name: Publish AUR packages
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish, such as v0.3.4
+        required: true
+        type: string
+  workflow_call:
+    inputs:
+      tag:
+        required: true
+        type: string
+    secrets:
+      AUR_SSH_PRIVATE_KEY:
+        required: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: aur-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish nightcap and nightcap-bin
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment: release
+    steps:
+      - name: Check out the release
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.tag }}
+          persist-credentials: false
+
+      - name: Render the recipes
+        shell: bash
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -Eeuo pipefail
+          [[ "$TAG" =~ ^v[0-9]+(\.[0-9]+)*$ ]]
+          version="${TAG#v}"
+          archive="nightcap-${version}-1-x86_64.pkg.tar.zst"
+          # nightcap-bin installs the pacman package from the release page, so
+          # its checksum is the one published beside that asset.
+          checksum="$(curl -fsSL \
+            "https://github.com/${GITHUB_REPOSITORY}/releases/download/${TAG}/${archive}.sha256" |
+            awk '{print $1}')"
+          [[ "$checksum" =~ ^[0-9a-f]{64}$ ]]
+
+          sed -i "s/^pkgver=.*/pkgver=${version}/" \
+            packaging/aur/nightcap/PKGBUILD packaging/aur/nightcap-bin/PKGBUILD
+          sed -i "s/^sha256sums=('SKIP')$/sha256sums=('${checksum}')/" \
+            packaging/aur/nightcap-bin/PKGBUILD
+          grep -Fqx "sha256sums=('${checksum}')" packaging/aur/nightcap-bin/PKGBUILD
+
+          docker run --rm \
+            --volume "$GITHUB_WORKSPACE/packaging/aur:/aur" \
+            ghcr.io/archlinux/archlinux:base-devel@sha256:c3953446016873a756fb7814f10087cac1634c127f7302e80c81c512da796d05 bash -Eeuo pipefail -c '
+              useradd --create-home builder
+              for package in nightcap nightcap-bin; do
+                install -d -o builder -g builder "/tmp/${package}"
+                install -o builder -g builder -m 0644 \
+                  "/aur/${package}/PKGBUILD" "/tmp/${package}/PKGBUILD"
+                runuser -u builder -- bash -c \
+                  "cd /tmp/${package} && makepkg --printsrcinfo" \
+                  > "/aur/${package}/.SRCINFO"
+              done
+            '
+
+          for package in nightcap nightcap-bin; do
+            grep -Fqx "pkgver=${version}" "packaging/aur/${package}/PKGBUILD"
+            grep -Fqx $'\tpkgver = '"${version}" "packaging/aur/${package}/.SRCINFO"
+          done
+          echo "VERSION=${version}" >> "$GITHUB_ENV"
+
+      - name: Push to the AUR
+        shell: bash
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          set -Eeuo pipefail
+          if [[ -z "${AUR_SSH_PRIVATE_KEY}" ]]; then
+            echo "::notice::AUR_SSH_PRIVATE_KEY is not set; nothing was pushed to the AUR"
+            exit 0
+          fi
+
+          ssh_dir="$(mktemp -d)"
+          trap 'rm -rf "$ssh_dir"' EXIT
+          install -m 0600 /dev/null "$ssh_dir/key"
+          printf '%s\n' "$AUR_SSH_PRIVATE_KEY" > "$ssh_dir/key"
+          # The AUR lists this key's fingerprint on its front page:
+          # SHA256:RFzBCUItH9LZS0cKB5UE6ceAYhBD5C8GeOBip8Z11+4
+          printf '%s\n' \
+            'aur.archlinux.org ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEuBKrPzbawxA/k2g6NcyV5jmqwJ2s+zpgZGZ7tpLIcN' \
+            > "$ssh_dir/known_hosts"
+          export GIT_SSH_COMMAND="ssh -i $ssh_dir/key -o IdentitiesOnly=yes -o UserKnownHostsFile=$ssh_dir/known_hosts -o StrictHostKeyChecking=yes"
+
+          for package in nightcap nightcap-bin; do
+            checkout="$ssh_dir/$package"
+            git clone "ssh://aur@aur.archlinux.org/${package}.git" "$checkout"
+            cp "packaging/aur/${package}/PKGBUILD" "packaging/aur/${package}/.SRCINFO" \
+              "$checkout/"
+            git -C "$checkout" add PKGBUILD .SRCINFO
+            if git -C "$checkout" diff --cached --quiet; then
+              echo "::notice::${package} is already at ${VERSION}"
+              continue
+            fi
+            git -C "$checkout" \
+              -c user.name='Nightcap release' \
+              -c user.email='CoderDayton@users.noreply.github.com' \
+              commit --quiet -m "Update to ${VERSION}"
+            # The AUR only accepts the master branch.
+            git -C "$checkout" push origin HEAD:master
+          done
@@ -77,7 +77,7 @@ jobs:
          bash tests/anylinux_dependencies_test.sh .

  native-build:
-    name: Native build (${{ matrix.arch }})
+    name: Native build (${{ matrix.arch }}, VR ${{ matrix.vr }})
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 60
    strategy:
@@ -86,8 +86,15 @@ jobs:
        include:
          - arch: x86_64
            runner: ubuntu-26.04
+            vr: 'ON'
          - arch: aarch64
            runner: ubuntu-26.04-arm
+            vr: 'ON'
+          # Packaging recipes build without the OpenXR submodule; keep the
+          # non-VR configuration compiling and passing on its own.
+          - arch: x86_64
+            runner: ubuntu-26.04
+            vr: 'OFF'
    steps:
      - name: Check out source
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -112,7 +119,8 @@ jobs:
        run: |
          test "$(uname -m)" = "${{ matrix.arch }}"
          cmake -S . -B build-ci -G Ninja \
-            -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON
+            -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON \
+            -DMOCKTAIL_ENABLE_VR=${{ matrix.vr }}
          cmake --build build-ci --parallel 4
          ./build-ci/mocktail --help
          ./build-ci/mocktail_updater status
@@ -38,6 +38,9 @@ jobs:
    name: Flatpak build
    runs-on: ubuntu-24.04
    timeout-minutes: 120
+    # The signing key lives in the release environment, which only main and
+    # v* tags may use. Builds that do not publish run without it.
+    environment: ${{ (startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')) && 'release' || '' }}
    env:
      # Publish on release tags and on manual runs from main. Pull requests
      # only verify that the manifest still builds.
@@ -336,3 +336,15 @@ jobs:
            --title "Nightcap $tag" --notes-file release/notes.md
          gh release upload "$tag" --repo "$GITHUB_REPOSITORY" --clobber \
            "${uploads[@]}"
+
+  # nightcap-bin downloads the pacman package from the release page, so this
+  # waits for the upload.
+  aur:
+    name: Publish AUR packages
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: publish
+    uses: ./.github/workflows/aur-publish.yml
+    with:
+      tag: ${{ github.ref_name }}
+    secrets:
+      AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
@@ -4,3 +4,9 @@
 [submodule "third_party/Vulkan-Headers"]
 	path = third_party/Vulkan-Headers
 	url = https://github.com/KhronosGroup/Vulkan-Headers.git
+[submodule "third_party/OpenXR-SDK"]
+	path = third_party/OpenXR-SDK
+	url = https://github.com/KhronosGroup/OpenXR-SDK.git
+[submodule "third_party/smaa"]
+	path = third_party/smaa
+	url = https://github.com/iryoku/smaa.git
@@ -5,6 +5,47 @@ Release notes on GitHub are taken from the matching section here.

 ## [Unreleased]

+### Added
+
+- An asset overlay folder, `~/.local/share/mocktail/asset_overlay`. A file there replaces the file Roblox
+  ships at the same path, such as a cursor, a font or a sky texture, and it stays in place when Roblox
+  updates. The layout matches Sober's `asset_overlay` folder. `MOCKTAIL_ASSET_OVERLAY_DIR` moves it. Thanks to
+  @dim-ghub.
+- The asset overlay folder now also replaces files Roblox downloads and no longer ships, such as the shift
+  lock and text cursors. Put the file under `content/`, at the path Roblox uses. Thanks to @dim-ghub for the
+  idea.
+- `MOCKTAIL_ASSET_TRACE=1` now also prints the files Roblox asks for and does not get, as `[asset] miss`.
+- Arch Linux: `nightcap-git` is on the AUR and builds the current `main` branch. Thanks to @dim-ghub, who
+  maintains it.
+- `vr.mode` in `config.yaml`: `off` starts on the desktop, `on` starts in VR, and `auto` starts in VR only
+  when SteamVR is already running with a connected headset. `auto` never starts SteamVR. `vr.enabled` still
+  works.
+- Anti-aliasing in VR. Roblox draws the VR eyes without it, so edges were jagged in the headset. Each eye is
+  now filtered on its way to the headset. `vr.anti_aliasing` picks `fxaa` (the default), `smaa`, which finds
+  edges more precisely and keeps text sharper for a little more GPU time, or `off`.
+- The log now names each Roblox Java call that Nightcap has no handler for, once per call, as
+  `[JNI] no handler for <class>.<method><signature>`. This shows what a new Roblox version needs.
+- `--profile` traces now show how much GPU memory decoded ETC2 textures take, as the `emulated texture (MB)`
+  and `compressed texture (MB)` counters. `scripts/summarize_profile_trace.py` prints the peak of each.
+
+### Fixed
+
+- Joining a game from a website link while already in a game no longer freezes Nightcap. It leaves the
+  current game and joins the new one, and leaving that game returns to the home screen.
+
+### Changed
+
+- The home screen and avatar editor have fewer long frames. PC profiles compile the app's menu scripts to
+  native code and turn this off while you are in a game, so games run as before. Set
+  `FFlagDebugLuauCodegenAll` in `fflags.json` to choose it yourself.
+- Nightcap answers Roblox's Java calls with less work per call, and the audio thread no longer allocates
+  memory for each block of sound it plays.
+- VR on Vulkan no longer makes the CPU wait for the GPU each frame. The eye copies, the desktop mirror and
+  the `MOCKTAIL_VR_MIRROR_SHM` readback are ordered on the GPU, so Roblox prepares the next frame while the
+  last one renders. On a simulated 120 Hz headset this removed 2 to 5 ms of waiting per frame and steadied
+  the frame rate. The shared-memory mirror now shows each frame one frame later.
+- `MOCKTAIL_VR_PERF` also reports `desktop_mirror`, `present_prepare` and `present_interval`.
+
 ## [0.3.4] - 2026-10-11

 ### Added
@@ -29,7 +70,7 @@ Release notes on GitHub are taken from the matching section here.
 - Fixed the old Roblox home screen showing instead of the new one with the Me tab and the "For you" and
  "Charts" tabs. Nightcap now runs the Roblox start-up step that loads the new interface for your account.
 - Fixed anti-aliasing being forced off at every graphics quality level. Roblox now picks it, and a
-  `FIntDebugForceMSAASamples` value in `fflags.json` still applies.
+  `FIntDebugForceMSAASamples` value in `fflags.json` still applies. Thanks to @qutad.
 - Fixed the voice chat microphone only working on Roblox 2.738. It no longer depends on one Roblox version.
 - Fixed other players not hearing you in voice chat after a Roblox update. The updater now rebuilds the
  audio device data when the previous version's profile has none.
@@ -126,6 +126,8 @@ set(VULKAN_HEADERS_ENABLE_INSTALL OFF CACHE BOOL
  "Install vendored Vulkan-Headers" FORCE)
 add_subdirectory(third_party/Vulkan-Headers EXCLUDE_FROM_ALL)

+include(${CMAKE_SOURCE_DIR}/cmake/MocktailVR.cmake)
+
 include(CTest)
 if(BUILD_TESTING)
  # Package builds disable tests and do not fetch Google Test.
@@ -252,6 +254,7 @@ add_library(mocktail_legacy_jnivm STATIC
  src/jnivm/jni_references.cc
  src/jnivm/jni_fields.cc
  src/jnivm/jni_strings.cc
+  src/jnivm/jni_method_names.cc
 )
 add_library(Mocktail::LegacyJni ALIAS mocktail_legacy_jnivm)
 target_include_directories(mocktail_legacy_jnivm PUBLIC include)
@@ -278,6 +281,7 @@ add_library(mocktail_runtime STATIC
  src/runtime/game_session_coordinator.cc
  src/runtime/graphics_launch_policy.cc
  src/runtime/http_client_policy.cc
+  src/runtime/luau_codegen_switch.cc
  src/runtime/memory_limit.cc
  src/runtime/owned_pthread.cc
  src/runtime/performance_policy.cc
@@ -295,9 +299,11 @@ add_library(mocktail_runtime STATIC
  src/runtime/roblox_account_bridge.cc
  src/runtime/roblox_message_bus_request_bridge.cc
  src/runtime/roblox_call_protocol_bridge.cc
+  src/runtime/roblox_haptic_protocol_bridge.cc
  src/runtime/payload_update_preflight.cc
  src/runtime/process_launch_policy.cc
  src/runtime/process_diagnostics.cc
+  src/runtime/asset_overlay_names.cc
  src/runtime/runtime_config.cc
  src/runtime/runtime_config_bootstrap.cc
  src/runtime/runtime_config_file.cc
@@ -597,6 +603,7 @@ target_compile_definitions(mocktail PRIVATE
  "MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST=\"${MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST}\""
 )
 target_link_libraries(mocktail PRIVATE
+  Mocktail::VR
  mocktail_legacy_runtime
  mocktail_auth_runtime_composition
  mocktail_failure_dialog_runtime
@@ -56,15 +56,14 @@ after Roblox added measures against running multiple clients.

 ## Can I play in VR?

-VR is experimental and lives on upstream's `vr` branch, which does not
-include the Nightcap changes. Install the
+Yes, as an experiment. VR lives on Nightcap's `vr` branch and is not in the
+releases yet. It works on Roblox builds 2998, 3092 and 3222. Install the
 [build dependencies](README.md#building), then switch to that branch and
 build:

 ```bash
-git remote add upstream https://github.com/komaruworld/mocktail.git
-git fetch upstream
-git switch -c vr upstream/vr
+git fetch origin
+git switch vr
 git submodule update --init --recursive
 cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DMOCKTAIL_ENABLE_VR=ON
 cmake --build build -j4
@@ -73,5 +72,8 @@ cmake --build build -j4
 Start WiVRn or SteamVR/ALVR, connect your headset, then run:

 ```bash
-./build/mocktail -vr
+./build/mocktail --vr
 ```
+
+The [README](README.md#experimental-vr) and [docs/VR.md](docs/VR.md) have the
+details, including how to try it without a headset.
@@ -11,10 +11,12 @@
  </h1>
 </div>

-Nightcap is Mocktail, tuned for playing on a real PC. It runs the Android
-`x86_64` Roblox client on Linux, including a Linux userspace hosted by
-FreeBSD's Linuxulator. It provides the Android ABI and JNI pieces the client
-expects, then connects them to SDL3 and Vulkan or OpenGL on the Linux side.
+Nightcap is Roblox on Linux, tuned for desktop play. It is a Mocktail fork
+that keeps up with Roblox updates, with extra bug fixes, custom assets and
+more. It runs the Android `x86_64` Roblox client on Linux, including a Linux
+userspace hosted by FreeBSD's Linuxulator. It provides the Android ABI and JNI
+pieces the client expects, then connects them to SDL3 and Vulkan or OpenGL on
+the Linux side.

 Nightcap is an independent community project. It is not affiliated with Roblox
 Corporation or VinegarHQ and does not distribute the Roblox client.
@@ -27,23 +29,25 @@ with extra fixes for playing on a PC. The program and config paths keep the
 `io.github.CoderDayton.nightcap`, so Nightcap and upstream can be installed
 side by side.

- **Lower input lag.** Frames are shown as soon as they are ready instead of
-  waiting in a queue.
- **Sharper textures.** Small textures are upscaled 4x by default, and you
-  can replace any texture with your own PNG in `~/.config/mocktail/textures`.
-  A ready-made crosshair is in [`textures/`](textures/README.md). Set
-  `MOCKTAIL_SMALL_TEXTURE_UPSCALE=1` to turn the upscale off.
- **ETC2 textures on any GPU.** Games that use compressed mobile textures now
-  render correctly on desktop GPUs, without stutter.
- **No more error 319 kicks.** Servers no longer drop you shortly after
-  joining.
- **Correct device info.** Roblox sees your real RAM and screen size.
- **Better desktop launcher.** Runs on Wayland and always finds the installed
-  binary.
+- **Keeps up with Roblox.** New Roblox versions work soon after they come out.
+- **Plays more games.** Nightcap answers a server check that some experiences
+  use, so you can join and stay in those too.
+- **Voice chat that keeps working.** Your microphone still works after a
+  Roblox update.
+- **Logging in works.** Verification checks and captchas finish instead of
+  hanging.
+- **The current Roblox look.** The new home screen and side menu, like on
+  Windows.
+- **Your own cursors, fonts and skies.** Drop files in
+  `~/.local/share/mocktail/asset_overlay` and Nightcap uses them. The layout
+  matches Sober's `asset_overlay` folder.
+- **Smoother mouse and a cooler PC.** Optional raw mouse input, and less CPU
+  use while idle.

-Everything else works the same as upstream. See the
-[roadmap](docs/ROADMAP.md) for what is coming next, the
-[changelog](CHANGELOG.md) for what each release changed,
+Everything else works the same as upstream. See
+[`textures/`](textures/README.md) for custom textures, a ready-made crosshair
+and the asset overlay folder, the [roadmap](docs/ROADMAP.md) for what is
+coming next, the [changelog](CHANGELOG.md) for what each release changed,
 [performance](docs/PERFORMANCE.md) for CPU load, heat and the knobs that change
 them, and the [FAQ](FAQ.md) for Discord RPC, logs, and VR.

@@ -80,8 +84,17 @@ sudo pacman -U nightcap-<version>-1-x86_64.pkg.tar.zst
 ```

 They install `/usr/bin/mocktail`, so they conflict with upstream's `mocktail`
-package. Nightcap is not in any distribution repository or the AUR; the
-recipes under `packaging/aur` are kept for local builds only.
+package.
+
+On Arch Linux, [`nightcap-git`](https://aur.archlinux.org/packages/nightcap-git)
+is on the AUR. It builds the current `main` branch and is maintained by
+[@dim-ghub](https://github.com/dim-ghub):
+
+```bash
+yay -S nightcap-git
+```
+
+Nightcap is in no other distribution repository.

 Or build and install from source using the steps under
 [Building](#building).
@@ -109,8 +122,6 @@ removing the marker.

 ![Roblox gameplay in Nightcap](assets/screenshots/flatpak-gameplay-tower.png)

-![Roblox experience in Nightcap](assets/screenshots/flatpak-gameplay-lobby.png)
-
 </details>

 ## FFlag overrides
@@ -125,6 +136,11 @@ caused by `Color3` errors in the newer SDUI page. An explicit
 PC profiles also set `FIntFlyoutTestVariantRollout12` to `2`, which shows the
 desktop side panel menu. An explicit override takes precedence.

+PC profiles compile the app's menus to native code with
+`FFlagDebugLuauCodegenAll`, and turn it off while you are in a game. Setting
+it yourself turns the switching off and your value applies everywhere. See
+[docs/PERFORMANCE.md](docs/PERFORMANCE.md#native-code-in-the-menus).
+
 ```json
 {
  "FFlagExample": "True",
@@ -137,6 +153,8 @@ Edit `~/.config/mocktail/config.yaml`. Useful options:

 - `graphics.frame_rate_limit: display` to unlock FPS to your monitor's rate.
 - `graphics.vsync: off` for the lowest lag, at the cost of tearing.
+- `vr.frame_rate_limit` sets the cap in VR. It defaults to `unlimited`, so the
+  headset's refresh rate paces frames; use `-1` for Roblox's 60 FPS cap.
 - `graphics.backend: opengl` if Vulkan does not work on your GPU.

 ## Building
@@ -219,6 +237,59 @@ To run the same checks as CI before each commit and push, install
 lefthook install
 ```

+## Experimental VR
+
+Experimental OpenXR VR support on Linux `x86_64` using WiVRn or SteamVR/ALVR.
+
+VR works on these Roblox builds. On any other build, `--vr` stops at start-up
+and names them:
+
+| Build | Roblox version |
+| --- | --- |
+| 2998 | 2.736.1408 |
+| 3092 | 2.738.1397 |
+| 3222 | 2.742.1059 |
+
+### Build with VR
+
+VR support is compiled in when the OpenXR SDK submodule is checked out
+(`MOCKTAIL_ENABLE_VR` defaults to `AUTO`). Without the submodule the build
+skips VR. Pass `-DMOCKTAIL_ENABLE_VR=ON` to make a missing submodule an error,
+or `OFF` to leave VR out:
+
+```bash
+git submodule update --init third_party/OpenXR-SDK
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j4
+```
+
+VR stays off at runtime until you pass `--vr` or set `vr.mode: on` in
+`config.yaml`. `vr.mode: auto` starts in VR only when SteamVR is running with a
+headset connected.
+
+### Run
+
+Start WiVRn or SteamVR/ALVR and connect your headset first:
+
+```bash
+./build/mocktail --vr
+```
+
+The OpenXR runtime is detected automatically. To pick one manually:
+
+```bash
+MOCKTAIL_VR_RUNTIME=wivrn ./build/mocktail --vr
+# or
+MOCKTAIL_VR_RUNTIME=alvr MOCKTAIL_GRAPHICS_BACKEND=direct-vulkan ./build/mocktail --vr
+```
+
+If you previously set `XR_RUNTIME_JSON`, unset it before switching runtimes.
+Use `--no-vr` for desktop mode.
+
+A keyboard opens in the headset when a text box takes focus. The rest is in
+[docs/VR.md](docs/VR.md): menus and typing, every VR environment variable,
+adding a Roblox build, and testing without a headset.
+
 ## Known limitations

 Nightcap does not currently work with `hardened_malloc`. Using
@@ -22,6 +22,7 @@ add_library(mocktail_input_runtime STATIC
  ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_text_font_resolver.cc
  ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_text_surface_overlay.cc
  ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_window_input_runtime.cc
+  ${MOCKTAIL_INPUT_ROOT}/src/runtime/roblox_xr_controller_input.cc
 )
 add_library(Mocktail::InputRuntime ALIAS mocktail_input_runtime)
 target_include_directories(mocktail_input_runtime PUBLIC
@@ -33,12 +34,14 @@ target_include_directories(mocktail_input_runtime PRIVATE
 target_link_libraries(mocktail_input_runtime PUBLIC
  Mocktail::PlatformSdl
  Mocktail::Runtime
+  Mocktail::VR
  mocktail_window
  PkgConfig::UTF8PROC
  PRIVATE
    PkgConfig::FONTCONFIG
    SDL3_ttf::SDL3_ttf
    nlohmann_json::nlohmann_json
+    ${CMAKE_DL_LIBS}
 )
 target_compile_features(mocktail_input_runtime PUBLIC cxx_std_17)
 mocktail_apply_compile_options(mocktail_input_runtime)
@@ -47,6 +50,7 @@ if(BUILD_TESTING AND TARGET GTest::gtest_main)
  add_executable(roblox_input_router_test
    ${MOCKTAIL_INPUT_ROOT}/tests/roblox_gamepad_input_test.cc
    ${MOCKTAIL_INPUT_ROOT}/tests/roblox_input_router_test.cc
+    ${MOCKTAIL_INPUT_ROOT}/tests/roblox_xr_controller_input_test.cc
  )
  target_link_libraries(roblox_input_router_test PRIVATE
    Mocktail::InputRuntime
@@ -0,0 +1,116 @@
+# Copyright 2026 Mocktail Project Authors
+# Licensed under the Apache License, Version 2.0.
+
+include_guard(GLOBAL)
+
+# AUTO builds OpenXR support when the third_party/OpenXR-SDK submodule is
+# checked out and skips it otherwise, so source packages that do not fetch
+# submodules still build. ON requires the submodule; OFF never builds it.
+set(MOCKTAIL_ENABLE_VR "AUTO" CACHE STRING
+  "Build experimental OpenXR support: AUTO, ON or OFF")
+set_property(CACHE MOCKTAIL_ENABLE_VR PROPERTY STRINGS AUTO ON OFF)
+set(_mocktail_openxr_sdk "${CMAKE_SOURCE_DIR}/third_party/OpenXR-SDK/CMakeLists.txt")
+string(TOUPPER "${MOCKTAIL_ENABLE_VR}" _mocktail_vr_request)
+if(_mocktail_vr_request STREQUAL "AUTO")
+  if(EXISTS "${_mocktail_openxr_sdk}" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    set(MOCKTAIL_ENABLE_VR ON)
+  else()
+    message(STATUS "OpenXR SDK submodule not found; building without VR "
+      "(git submodule update --init third_party/OpenXR-SDK to enable it)")
+    set(MOCKTAIL_ENABLE_VR OFF)
+  endif()
+elseif(MOCKTAIL_ENABLE_VR)
+  set(MOCKTAIL_ENABLE_VR ON)
+else()
+  set(MOCKTAIL_ENABLE_VR OFF)
+endif()
+
+add_library(mocktail_vr STATIC
+  src/vr/diagnostics.cc
+  src/vr/headset_detection.cc
+  src/vr/openxr_backend_mode.cc
+  src/vr/vr_perf.cc
+  src/vr/vr_mirror.cc
+  src/vr/xr_controller.cc
+  src/vr/roblox_vr_device_bridge.cc
+  src/vr/virtual_keyboard.cc)
+add_library(Mocktail::VR ALIAS mocktail_vr)
+target_include_directories(mocktail_vr PUBLIC "${CMAKE_SOURCE_DIR}/include")
+target_include_directories(mocktail_vr PRIVATE "${CMAKE_SOURCE_DIR}/src")
+target_link_libraries(mocktail_vr PUBLIC Vulkan::Headers PRIVATE nlohmann_json::nlohmann_json)
+# shm_open for the desktop eye mirror lives in librt on glibc.
+find_library(MOCKTAIL_RT_LIBRARY rt)
+if(MOCKTAIL_RT_LIBRARY)
+  target_link_libraries(mocktail_vr PUBLIC ${MOCKTAIL_RT_LIBRARY})
+endif()
+mocktail_apply_compile_options(mocktail_vr)
+
+if(MOCKTAIL_ENABLE_VR)
+  if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    message(FATAL_ERROR "Mocktail OpenXR support currently targets Linux")
+  endif()
+  if(NOT EXISTS "${_mocktail_openxr_sdk}")
+    message(FATAL_ERROR
+      "Initialize OpenXR: git submodule update --init third_party/OpenXR-SDK")
+  endif()
+
+  # Scope upstream's generic option names to this dependency. Static linking
+  # packages the pinned loader without requiring a matching system loader.
+  function(mocktail_add_openxr_sdk)
+    set(BUILD_LOADER ON)
+    set(DYNAMIC_LOADER OFF)
+    set(BUILD_WITH_SYSTEM_JSONCPP OFF)
+    set(BUILD_TESTS OFF)
+    set(BUILD_API_LAYERS OFF)
+    set(BUILD_CONFORMANCE_TESTS OFF)
+    set(BUILD_SDK_TESTS OFF)
+    set(BUILD_FORCE_GENERATION OFF)
+    add_subdirectory("${CMAKE_SOURCE_DIR}/third_party/OpenXR-SDK"
+      "${CMAKE_BINARY_DIR}/third_party/OpenXR-SDK" EXCLUDE_FROM_ALL)
+  endfunction()
+  mocktail_add_openxr_sdk()
+  target_sources(mocktail_vr PRIVATE src/vr/openxr_probe.cc src/vr/openxr_preview.cc
+    src/vr/openxr_backend.cc src/vr/gles_transport.cc src/vr/xr_actions.cc
+    src/vr/virtual_keyboard_raster.cc)
+  # The in-headset keyboard draws its labels with the same SDL3_ttf and
+  # fontconfig stack as the TextBox overlay.
+  find_package(SDL3 3.4 REQUIRED CONFIG)
+  find_package(SDL3_ttf REQUIRED CONFIG)
+  find_package(PkgConfig REQUIRED)
+  pkg_check_modules(FONTCONFIG REQUIRED IMPORTED_TARGET fontconfig)
+  target_link_libraries(mocktail_vr PRIVATE SDL3_ttf::SDL3_ttf SDL3::SDL3
+    PkgConfig::FONTCONFIG)
+  # Error unwinding is confined to these native session implementations; their
+  # public entry points catch errors before returning to the guest runtime.
+  set_source_files_properties(src/vr/openxr_preview.cc src/vr/openxr_backend.cc
+    src/vr/xr_actions.cc
+    PROPERTIES COMPILE_OPTIONS -fexceptions)
+  target_compile_definitions(mocktail_vr PRIVATE XR_USE_GRAPHICS_API_VULKAN)
+  option(MOCKTAIL_VR_DIAGNOSTICS
+    "Compile VR diagnostics: scripted head pose, eye evidence dumps" OFF)
+  if(MOCKTAIL_VR_DIAGNOSTICS)
+    target_compile_definitions(mocktail_vr PRIVATE MOCKTAIL_VR_DIAGNOSTICS=1)
+  endif()
+  set_source_files_properties(src/vr/openxr_backend.cc PROPERTIES COMPILE_DEFINITIONS "XR_USE_GRAPHICS_API_OPENGL_ES;XR_USE_PLATFORM_EGL")
+  target_include_directories(mocktail_vr PRIVATE ${MOCKTAIL_EGL_INCLUDE_DIR} ${MOCKTAIL_GLES3_INCLUDE_DIR})
+  # SMAA's area and search lookup textures for vr.anti_aliasing: smaa.
+  if(NOT EXISTS "${CMAKE_SOURCE_DIR}/third_party/smaa/Textures/AreaTex.h")
+    message(FATAL_ERROR
+      "Initialize SMAA: git submodule update --init third_party/smaa")
+  endif()
+  target_include_directories(mocktail_vr PRIVATE "${CMAKE_SOURCE_DIR}/third_party/smaa")
+  target_link_libraries(mocktail_vr PRIVATE OpenXR::openxr_loader Vulkan::Headers ${CMAKE_DL_LIBS})
+else()
+  target_sources(mocktail_vr PRIVATE src/vr/openxr_disabled.cc
+    src/vr/xr_actions_disabled.cc)
+endif()
+
+if(MOCKTAIL_ENABLE_VR)
+  add_executable(mocktail_vr_probe src/vr/probe_main.cc)
+  set_target_properties(mocktail_vr_probe PROPERTIES
+    OUTPUT_NAME mocktail-vr-probe)
+  target_link_libraries(mocktail_vr_probe PRIVATE Mocktail::VR)
+  mocktail_apply_compile_options(mocktail_vr_probe)
+  install(TARGETS mocktail_vr_probe
+    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}")
+endif()
@@ -52,6 +52,28 @@ graphics:
  # unless frame_rate_limit is unlimited.
  # vsync: off

+# vr:
+  # String (default: off): experimental VR through OpenXR on supported Roblox
+  # builds. off always starts on the desktop. on always starts in VR, like
+  # --vr. auto starts in VR when SteamVR is already running with a connected
+  # headset (ALVR included), and on the desktop otherwise. auto never starts
+  # SteamVR. --vr and --no-vr override this for one launch. The older
+  # enabled: true/false still works as on/off; set one or the other.
+  # Standalone OpenXR test scene: mocktail-vr-probe --scene.
+  # mode: off
+  # String (default: fxaa): smooth jagged edges in the headset. Roblox draws
+  # the VR eyes without anti-aliasing, so each eye is filtered on its way to
+  # the headset. fxaa is the cheapest. smaa finds edges more precisely and
+  # keeps text and fine detail sharper, at a little more GPU time. off sends
+  # the eyes as rendered.
+  # anti_aliasing: fxaa
+  # Optional string or integer: frame-rate limit used instead of
+  # graphics.frame_rate_limit while VR is active. Same values: -1 (Roblox's
+  # own cap, usually 60), display, unlimited, or any positive integer. The
+  # default, unlimited, lets the OpenXR runtime pace frames at the headset's
+  # refresh rate.
+  # frame_rate_limit: unlimited
+
 performance:
  # Boolean (default: false): size Roblox scheduler/render queues from every
  # physical CPU core. A place's Lua/main thread can still remain serial.
@@ -102,7 +102,46 @@
        "input_current_method_rva": "0x32d13a6",
        "input_select_method_rva": "0x32d0a56"
      },
-      "reason": "Verified 2026-09-06: exact Build-ID profile passed two isolated no-recovery Tier C Vulkan canaries and real game sessions, including fullscreen state synchronization and host FMOD output-device interposition; legacy executable patches and signal recovery remain disabled."
+      "vr_debug_device_bridge": {
+        "vtable_rva": "0x6c87b38",
+        "constructor_rva": "0x3810614",
+        "state_getter_rva": "0x38109f6",
+        "eye_getter_rva": "0x38109e6",
+        "eye_initializer_rva": "0x3810a18",
+        "emulator_flag_storage_rva": "0x7369920",
+        "device_create_framebuffer_vtable_offset": "0x180"
+      },
+      "reason": "Verified 2026-09-06: exact Build-ID profile passed two isolated no-recovery Tier C Vulkan canaries and real game sessions, including fullscreen state synchronization and host FMOD output-device interposition; legacy executable patches and signal recovery remain disabled. Experimental vr_debug_device_bridge metadata (DebugDeviceVR constructor/state/eye/initializer RVAs) is machine-validated at activation and gated behind --vr; native stereo output is not yet verified end-to-end."
+    },
+    {
+      "allow_host_abi_bridges": true,
+      "allow_host_constructor_replay": true,
+      "allow_legacy_binary_patches": false,
+      "default_allowed": true,
+      "elf_build_id": "5f0704edd9064f566ee3d6df2bd2fabbcc709f03",
+      "fmod_output_device_bridge": {
+        "count_method_rva": "0x320c676",
+        "current_method_rva": "0x320c6c6",
+        "info_method_rva": "0x320c716",
+        "select_method_rva": "0x320bf78",
+        "string_constructor_rva": "0x1d7a038",
+        "vtable_layout_version": 2,
+        "vtable_rva": "0x6cd3ce0"
+      },
+      "reason": "Exact-Build-ID host ABI promoted from the validated probation profile; native stereo, VR state/pointer/haptic contracts and FMOD output-device layout v2 were re-derived for 3092. Experimental: runs when selected explicitly (--roblox-lib) but is never an update target, so non-VR users stay on the default payload.",
+      "status": "experimental",
+      "user_game_settings_fullscreen_setter_rva": "0x45c5f42",
+      "version_code": 3092,
+      "version_name": "2.738.1397",
+      "vr_debug_device_bridge": {
+        "vtable_rva": "0x6d08108",
+        "constructor_rva": "0x37f9fe4",
+        "state_getter_rva": "0x37fa3c6",
+        "eye_getter_rva": "0x37fa3b6",
+        "eye_initializer_rva": "0x37fa3e8",
+        "emulator_flag_storage_rva": "0x73f4690",
+        "device_create_framebuffer_vtable_offset": "0x188"
+      }
    }
  ]
 }
@@ -68,6 +68,12 @@ the CPU time of every thread together, so dividing it by the frame interval
 gives the number of cores busy. A long frame with little present-thread CPU
 was spent waiting.

+`emulated texture (MB)` is the VRAM held by the decoded images that stand in
+for live ETC2/EAC textures, over every mip level and layer, upscaled where
+small-texture upscale applies. `compressed texture (MB)` is the size the same
+textures would take as ETC2/EAC. Both change only when such an image is
+created or destroyed. `summarize_profile_trace.py` prints each one's peak.
+
 ## The benchmark runs

 Run every scenario before and after the change, on the same build type
@@ -129,14 +129,23 @@ runs cooler for a few frames per second less; measure before keeping it.

 ## Small texture upscaling

-`MOCKTAIL_SMALL_TEXTURE_UPSCALE` (default `4`) redraws ETC2 textures of 64px or
+`MOCKTAIL_SMALL_TEXTURE_UPSCALE` (default `4`) stores ETC2 textures of 64px or
 smaller at N times their width and height. At the default that is 16 times the
 pixels per affected texture.

+Upscaling alone adds no detail. Each original pixel becomes an N×N block of the
+same colour, and the GPU's filtering already blends a small texture that much
+when it draws it. The extra size only shows when a replacement PNG in
+`~/.config/mocktail/textures` has more detail than the original.
+
 The cost lands in two places. Decoding and resampling is CPU work on up to 8
 threads while textures load, which shows up as a burst rather than a steady
 load. The enlarged textures then stay in GPU memory for the session and cost
-extra sampling bandwidth on every frame that uses them.
+extra sampling bandwidth on every frame that uses them. In Blade Ball the
+memory share is small: decoded textures came to 5.1 times their ETC2 size both
+with the default and with upscaling off. The `emulated texture (MB)` and
+`compressed texture (MB)` counters in a `--profile` trace give the figures for
+any game.

 That decode does not run on the thread that submits the frame. On a device
 with a timeline semaphore, uploads decode on a background dispatcher and the
@@ -151,12 +160,68 @@ Set it to `1` to turn upscaling off:
 MOCKTAIL_SMALL_TEXTURE_UPSCALE=1 mocktail
 ```

+## Native code in the menus
+
+The home screen and avatar editor run Roblox's Lua app in the Luau interpreter,
+and its long frames come from that thread. PC profiles set
+`FFlagDebugLuauCodegenAll`, which compiles every script to native code. That
+makes the menus' Lua about 2.5 times cheaper for about 56 MB of compiled code.
+
+In a game the same flag compiles every game script too: Blade Ball grew from 7
+MB to about 300 MB and hit Roblox's native code limit, which shows warnings in
+F9. So Nightcap turns the flag off when a game starts joining and back on when
+you return to the menus. Roblox reads the flag each time it compiles a script,
+and a game's compiled code is freed when you leave it. Games run with Roblox's
+own per-script choice, the same as without the flag.
+
+The log shows each switch:
+
+```text
+[luau-codegen] menus-only switch at +0x<offset in libroblox.so>
+[luau-codegen] native code for all scripts off
+[luau-codegen] native code for all scripts on
+```
+
+Setting `FFlagDebugLuauCodegenAll` in `fflags.json` turns the switching off
+and your value applies everywhere. To keep the interpreter in the menus too:
+
+```json
+{
+  "FFlagDebugLuauCodegenAll": false
+}
+```
+
 ## Frame rate and present mode

 `graphics.frame_rate_limit` (default `-1`) leaves Roblox's own in-game
 framerate cap in charge; Nightcap sets no `DFIntTaskSchedulerTargetFps`
 override. A fixed value forwards that number to the scheduler.

+In VR, `vr.frame_rate_limit` (`MOCKTAIL_VR_FRAME_RATE_LIMIT`) replaces
+`graphics.frame_rate_limit` and takes the same values. Its default is
+`unlimited`: the scheduler target goes to 240 and `xrWaitFrame` holds each
+frame to the headset's refresh rate. Set `-1` to restore Roblox's own cap, or a
+number such as `90` to pin it.
+
+`MOCKTAIL_VR_RENDER_SCALE` (default `1.0`, range `0.25`–`2.0`) scales each
+axis of the OpenXR runtime's recommended eye size. SteamVR's recommendation
+already includes its own supersampling, so on a Quest 2 at 90 Hz it is about
+2244x2352 per eye. If a frame misses the 11.1 ms budget, the runtime halves
+the rate to 45 FPS; `0.75` renders about 56% of the pixels.
+
+`MOCKTAIL_VR_UNPACED=1` is a benchmark mode. Roblox no longer waits for the
+headset between frames; each XR frame stays open across several Roblox frames
+and is submitted with the newest eyes once per display period. Pair it with a
+fixed scheduler target above 240 and `MOCKTAIL_VSYNC=off` to find the
+maximum rate:
+
+```bash
+MOCKTAIL_VR_UNPACED=1 MOCKTAIL_VR_FRAME_RATE_LIMIT=9999 MOCKTAIL_VSYNC=off mocktail --vr
+```
+
+Frames beyond the headset refresh are never displayed, and they all reuse the
+open frame's head pose, so expect judder. Do not play in this mode.
+
 `graphics.vsync` (default `auto`) selects the presentation mode. `auto` and
 `on` both pick the lowest-latency synchronized mode the driver offers, in
 order: `FIFO_LATEST_READY`, `MAILBOX`, `FIFO_RELAXED`, `FIFO`. The first two do
@@ -0,0 +1,135 @@
+# VR
+
+Experimental OpenXR VR is opt-in: launch with `--vr`, or set `vr.mode` in
+`config.yaml`:
+
+- `off` (default) always starts on the desktop.
+- `on` always starts in VR.
+- `auto` starts in VR when SteamVR is already running with a connected
+  headset, ALVR included, and on the desktop otherwise. It never starts
+  SteamVR, so start SteamVR and connect the headset first.
+
+`--vr` and `--no-vr` override `vr.mode` for one launch. The older
+`vr.enabled: true`/`false` still works as `on`/`off`. Everything here only
+applies while VR is active. The [README](../README.md#experimental-vr) covers
+building and running.
+
+## Menus and typing
+
+The home menu uses Roblox's `More` button. The desktop side panel is turned
+off in VR, because the VR pointer cannot click it.
+
+When a text box takes focus (chat, search), a keyboard opens in front of you,
+below eye level. It is a full US layout without the function row or
+Ctrl/Alt. Point at a key and pull the trigger. While you point at the keyboard,
+the trigger types and does not click the game behind it. Hold Backspace to
+delete repeatedly. Shift applies to the next key and selects its upper symbol;
+Caps Lock stays on until you tap it again. Close dismisses the keyboard and
+leaves the text box. Set `MOCKTAIL_VR_KEYBOARD=0` to turn the keyboard off.
+
+## Environment variables
+
+## Runtime and display
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MOCKTAIL_VR_ENABLED` | `0` | Same as `--vr` (`1`) or `--no-vr` (`0`). |
+| `MOCKTAIL_VR_RUNTIME` | `auto` | OpenXR runtime: `auto`, `system`, `wivrn`, `steamvr` or `alvr`. `XR_RUNTIME_JSON` overrides it. |
+| `MOCKTAIL_VR_BACKEND` | `xr` | `native` keeps Roblox's stereo rendering without an OpenXR runtime, for debugging. |
+| `MOCKTAIL_VR_FRAME_RATE_LIMIT` | `unlimited` | Frame-rate cap in VR, same values as `graphics.frame_rate_limit` (also `vr.frame_rate_limit`). With `unlimited` the headset's refresh rate paces frames. |
+| `MOCKTAIL_VR_ANTI_ALIASING` | `fxaa` | Same as `vr.anti_aliasing`. Roblox draws the VR eyes without anti-aliasing, so each eye is filtered on its way to the headset (Vulkan only). `fxaa` is the cheapest; `smaa` finds edges more precisely and keeps text sharper; `off` sends them as rendered. |
+| `MOCKTAIL_VR_RENDER_SCALE` | `1.0` | Scales each axis of the runtime's recommended eye size, `0.25` to `2.0`. |
+| `MOCKTAIL_VR_UNPACED` | `0` | `1` stops waiting for the headset between frames, to measure the maximum frame rate. Frames past the headset refresh are not shown. Not for playing. |
+| `MOCKTAIL_VR_DESKTOP_MIRROR` | `1` | `0` stops copying the left eye to the desktop window. |
+| `MOCKTAIL_VR_MIRROR_SHM` | unset | A shared-memory name such as `/nightcap-mirror` publishes both eyes for an external viewer. The segment is private to your user. |
+| `MOCKTAIL_VR_KEYBOARD` | `1` | `0` turns off the in-headset keyboard. |
+
+## Hands and scale
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MOCKTAIL_VR_HAND_POSE_SOURCE` | `aim` | `grip` orients hands from the controller grip pose instead of the aim pose. |
+| `MOCKTAIL_VR_HAND_PITCH_OFFSET` | `-20` | Degrees added to Roblox's own hand pitch. |
+| `MOCKTAIL_VR_HAND_PITCH` | unset | Replaces the total hand pitch, in degrees. |
+| `MOCKTAIL_VR_WORLD_SCALE` | `1.0` | Scales head, hand and eye offsets. `MOCKTAIL_VR_EYE_OFFSET_SCALE` is an older name for it. |
+
+## Performance tracing
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MOCKTAIL_VR_PERF` | unset | `1` logs per-stage frame timings and counters once a second. `present_interval` is the frame time; `desktop_mirror`, `copy_record` and `copy_fence_wait` show time the CPU spent on VR copies. |
+| `MOCKTAIL_VR_MEASURE_START_NS`, `MOCKTAIL_VR_MEASURE_END_NS` | unset | Limit `MOCKTAIL_VR_PERF` to a `CLOCK_MONOTONIC` window. |
+| `MOCKTAIL_VR_POSE_LOG_INTERVAL` | `240` | Frames between head-pose log lines. |
+
+## Diagnostics builds
+
+These only work in builds configured with `-DMOCKTAIL_VR_DIAGNOSTICS=ON`.
+Release builds ignore them.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `MOCKTAIL_VR_POSE_SOURCE` | `runtime` | `script` drives the head from a scripted motion instead of the headset, for testing without wearing it. |
+| `MOCKTAIL_VR_POSE_AMPLITUDE_POSITION`, `_YAW`, `_PITCH` | `0.25`, `0.5`, `0.17` | Scripted motion size, in metres and radians. |
+| `MOCKTAIL_VR_POSE_PERIOD_POSITION`, `_ROTATION` | `240`, `360` | Scripted motion period, in frames. |
+| `MOCKTAIL_VR_XR_EVIDENCE_DIR` | unset | Writes submitted eye images to this directory. |
+| `MOCKTAIL_VR_XR_EVIDENCE_INTERVAL` | `20` | Frames between evidence images. |
+
+## Adding a Roblox build
+
+VR needs addresses that are specific to each Roblox build. To use a supported
+build that is not the active one, point `--roblox-lib` at its `libroblox.so`.
+
+To add a build, run the offset finder on its library:
+
+```bash
+python3 scripts/find_roblox_vr_offsets.py --elf <libroblox.so> --output offsets.json
+```
+
+It needs the `capstone` Python package. Add its values to `kContracts` in
+`src/vr/roblox_vr_device_bridge.cc`. Nightcap checks those addresses against
+Roblox's code before it hooks anything, and leaves VR off if they do not
+match. To run the same checks on real libraries, set
+`MOCKTAIL_TEST_VR_PAYLOADS` to a folder of `<build>-<build id>/libroblox.so`
+payloads and run `ctest -R VrSupportedBuilds`.
+
+For a second opinion, solve the new build from the previous one and compare
+the two answers. It needs the previous build's HostAbi profile and
+compatibility manifest:
+
+```bash
+python3 scripts/roblox_abi_check.py --reference-lib <old libroblox.so> \
+  --reference-profile <old profile.json> \
+  --reference-compatibility config/roblox_compatibility.json \
+  --candidate-lib <new libroblox.so> --vr
+```
+
+It lists every field where the finder and the solver disagree and exits 0
+when they agree on all of them.
+
+## Testing without a headset
+
+[Monado](https://monado.freedesktop.org) can stand in for a headset. Its
+`qwerty` driver gives a head and two controllers that you move with the
+keyboard and mouse:
+
+```bash
+QWERTY_ENABLE=1 XRT_DEBUG_GUI=1 monado-service
+```
+
+Then, in another terminal:
+
+```bash
+XR_RUNTIME_JSON=/usr/share/openxr/1/openxr_monado.json ./build/mocktail --vr
+```
+
+The keys work while Monado's debug window has focus. The simulated display is
+small, so text in the headset view looks coarse.
+
+Two tests need an OpenXR runtime and skip without one. To run them, start
+Monado with no window and opt in:
+
+```bash
+XRT_COMPOSITOR_NULL=1 monado-service &
+XR_RUNTIME_JSON=/usr/share/openxr/1/openxr_monado.json MOCKTAIL_TEST_XR_GLES=1 \
+  ctest --test-dir build -R GlesVrTransportTest.OpenXr
+```
@@ -53,6 +53,19 @@ struct FmodOutputDeviceBridgeProfile {
  }
 };

+// Exact-build metadata for the experimental native VR bridge. The bridge
+// interposes DebugDeviceVR slots and a checked world-pointer trampoline.
+// All RVAs are validated against machine-code contracts before first use.
+struct VrDebugDeviceBridgeProfile {
+  std::uintptr_t vtable_rva = 0;
+  std::uintptr_t constructor_rva = 0;
+  std::uintptr_t state_getter_rva = 0;
+  std::uintptr_t eye_getter_rva = 0;
+  std::uintptr_t eye_initializer_rva = 0;
+  std::uintptr_t emulator_flag_storage_rva = 0;
+  std::uintptr_t device_create_framebuffer_vtable_offset = 0;
+};
+
 struct BuildProfile {
  std::string version_name;
  int version_code = 0;
@@ -70,6 +83,8 @@ struct BuildProfile {
  // output-device virtual slots and restores them during controlled teardown;
  // executable guest code is never modified.
  std::optional<FmodOutputDeviceBridgeProfile> fmod_output_device_bridge;
+  // Optional exact-build experimental VR capability; see the struct above.
+  std::optional<VrDebugDeviceBridgeProfile> vr_debug_device_bridge;
  std::string reason;
 };

@@ -30,6 +30,18 @@ bool Etc2UploadByteCounts(EtcFormat format, const VkExtent3D& extent,
                          std::uint32_t layer_count, VkDeviceSize* compressed,
                          VkDeviceSize* decoded);

+// Sums every mip level and layer; `scale` multiplies the host image's
+// level-0 width and height only.
+bool Etc2ImageByteCounts(EtcFormat format, const VkExtent3D& extent,
+                         std::uint32_t mip_levels, std::uint32_t layers,
+                         std::uint32_t scale, VkDeviceSize* compressed,
+                         VkDeviceSize* decoded);
+
+struct EmulatedTextureBytes {
+  VkDeviceSize compressed = 0;
+  VkDeviceSize decoded = 0;
+};
+
 // Whether emulated ETC2 is reported to the application as a supported
 // feature, from the MOCKTAIL_ADVERTISE_ETC2 value: "0" hides it, anything
 // else (or unset) reports it. Hidden ETC2 still decodes ETC2 images the
@@ -152,6 +164,10 @@ class VulkanEtc2Emulation final {
  // pending, after waiting for any decode still writing into them.
  void ReleaseCommandBuffer(VkCommandBuffer command_buffer);

+  // Traced as the "emulated texture (MB)" and "compressed texture (MB)"
+  // counters.
+  EmulatedTextureBytes TextureBytes() const;
+
  struct State;

 private:
@@ -0,0 +1,35 @@
+#ifndef MOCKTAIL_VR_HEADSET_DETECTION_H_
+#define MOCKTAIL_VR_HEADSET_DETECTION_H_
+
+#include <chrono>
+#include <string>
+
+namespace mocktail::vr {
+
+// Set on the child process that answers DetectSteamVrHeadset. main() checks
+// it first and returns RunHeadsetProbeChild() without starting Roblox.
+inline constexpr const char* kHeadsetProbeEnvironment =
+    "MOCKTAIL_VR_HEADSET_PROBE";
+
+struct HeadsetDetection {
+  bool headset = false;
+  std::string reason;
+};
+
+// vr.mode: auto. True only when this user's SteamVR is running and its OpenXR
+// runtime reports a head-mounted display. SteamVR is never started. The
+// runtime is asked from a child process (`self_executable` with
+// kHeadsetProbeEnvironment set) so its libraries never load into this one
+// before the VR backend arms.
+HeadsetDetection DetectSteamVrHeadset(
+    const std::string& self_executable,
+    std::chrono::milliseconds timeout = std::chrono::seconds(5),
+    const std::string& proc_root = "/proc");
+
+// The child side: probes the OpenXR runtime in XR_RUNTIME_JSON and returns
+// the probe's exit code (0 when a headset is available).
+int RunHeadsetProbeChild();
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_HEADSET_DETECTION_H_
@@ -0,0 +1,665 @@
+#ifndef MOCKTAIL_VR_OPENXR_BACKEND_H_
+#define MOCKTAIL_VR_OPENXR_BACKEND_H_
+
+#include <vulkan/vulkan.h>
+
+#include <array>
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include <memory>
+
+#include "mocktail/status.h"
+#include "mocktail/vr/virtual_keyboard.h"
+#include "mocktail/vr/vr_mirror.h"
+#include "mocktail/vr/xr_actions.h"
+#include "mocktail/vr/xr_controller.h"
+
+namespace mocktail::vr {
+
+namespace internal {
+// Swapchain format for guest eyes of `eye` given the runtime's formats:
+// `eye` itself, else its UNORM/SRGB sibling (a raw byte copy, since the guest
+// writes sRGB-encoded bytes either way), else the other channel order with
+// the same sRGB-ness (a blit that only swizzles). VK_FORMAT_UNDEFINED when
+// only a gamma-converting blit remains.
+VkFormat PreferredEyeSwapchainFormat(VkFormat eye,
+                                     const std::vector<std::int64_t>& available);
+// Consume binary present dependencies exactly once. On success a later present
+// must omit them. VK_NOT_READY means nothing was consumed and the guest's
+// present proceeds unchanged; any other failure consumed them (or lost the
+// device) and must be propagated, not retried.
+VkResult WaitForPresentDependencies(VkDevice device, VkQueue queue,
+                                    const VkPresentInfoKHR& present,
+                                    VkFence fence, PFN_vkResetFences reset,
+                                    PFN_vkQueueSubmit submit,
+                                    PFN_vkWaitForFences wait);
+// Hands binary present dependencies to the GPU instead: one empty batch on
+// `queue` waits on them and signals `signal`, which the present waits on
+// instead. Work submitted to `queue` afterwards is ordered after the waits.
+// The CPU never blocks. VK_NOT_READY means nothing was consumed.
+VkResult ChainPresentDependencies(VkDevice device, VkQueue queue,
+                                  const VkPresentInfoKHR& present,
+                                  VkSemaphore signal, PFN_vkQueueSubmit submit);
+// Makes the Vulkan adapter serialize queue calls for the rest of the process.
+// Called when a backend arms; the adapter library may load before or after.
+void RequestVulkanQueueSharing();
+}  // namespace internal
+
+// Resolved --vr output mode. kXrOutput drives the real Roblox stereo images
+// into an OpenXR projection layer; kNativeOnly keeps the diagnostic native
+// stereo prototype without any runtime requirement. Selected through
+// MOCKTAIL_VR_BACKEND ("xr" default, "native" diagnostic).
+enum class VrBackendMode {
+  kDisabled,
+  kNativeOnly,
+  kXrOutput,
+};
+
+// Explicit XR_RUNTIME_JSON wins. Runtime preference can select SteamVR (ALVR),
+// WiVRn, or the registered OpenXR runtime without changing system registration.
+std::string SelectVrRuntimeManifest(const std::string& explicit_manifest,
+                                   const std::vector<std::string>& candidates);
+std::vector<std::string> VrRuntimeManifestCandidates(
+    const std::string &preference, const std::string &home,
+    const std::string &config_home, const std::string &config_dirs);
+struct VrRuntimeDiscovery {
+  std::vector<std::string> candidates;
+  std::string reason;
+};
+VrRuntimeDiscovery DiscoverVrRuntime(
+    const std::string& preference, const std::string& home,
+    const std::string& config_home, const std::string& config_dirs,
+    const std::string& runtime_dir, const std::string& proc_root = "/proc");
+std::string VrRuntimeUnavailableHint(bool user_selected, const std::string& manifest);
+// SteamVR's OpenXR manifest when this user's vrserver is running, else empty.
+std::string RunningSteamVrManifest(const std::string& proc_root = "/proc");
+VrBackendMode ResolveVrBackendMode(bool vr_enabled);
+const char* VrBackendModeName(VrBackendMode mode);
+
+// One deterministic head pose sample. Position is metres, orientation is a
+// quaternion (x, y, z, w) in the OpenXR LOCAL reference space.
+// VrHandPose (tracked controller hands) is defined in xr_controller.h.
+struct ScriptedPoseSample {
+  float position[3] = {0.f, 0.f, 0.f};
+  float orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  float eye_offset[2][3] = {};  // metres in head space
+  float eye_fov[2][4] = {};  // left, right, up, down angles
+  // Index 0 = left, 1 = right (Roblox UserCFrame LeftHand/RightHand).
+  VrHandPose hands[2];
+  float floor_position[3] = {};
+  float floor_orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  bool floor_valid = false;
+  // Verified DebugDeviceVR input channels, published with the same pose.
+  float controller_channels[28] = {};
+  bool controllers_connected = false;
+  std::uint64_t frame = 0;
+  bool valid = false;
+};
+
+// Production OpenXR backend for the native stereo prototype.
+//
+// Lifecycle: main arms the backend before Roblox startup (xrCreateInstance
+// and xrGetSystem fail fast with a clear message when no runtime exists).
+// The Vulkan adapter delegates the guest's vkCreateInstance/vkCreateDevice
+// through xrCreateVulkanInstanceKHR/xrCreateVulkanDeviceKHR so the runtime's
+// extension and GPU requirements are satisfied by the very device Roblox
+// renders with. The session is created on that device; per-frame XR work runs
+// on the render thread from the adapter's host-present notification:
+//   xrEndFrame(N) with the two eye images of frame N copied into the
+//   projection swapchains, then xrWaitFrame/xrBeginFrame/xrLocateViews for
+//   frame N+1 and publishing the scripted/runtime head pose that the device
+//   bridge injects into Roblox before its eye passes run.
+//
+// EGL/OpenGL ES uses XR_MNDX_egl_enable on the guest SDL context and GPU
+// framebuffer blits into GLES swapchain textures. It shares the same frame
+// scheduling, tracking, pose application and session recovery below.
+//
+// Eye image provenance is recorded in the adapter during the guest eye
+// initializer (owner = DebugDeviceVR object) and bound to an eye index only
+// through the real per-frame eye-getter request plus the actual render-pass
+// attachment, mirroring the validated evidence-layer semantics. Creation
+// order or size alone never selects an eye.
+//
+// All public entry points are exception-free at their boundary; the
+// implementation is compiled with exceptions like openxr_preview.cc and
+// translates failures into Status/log outcomes.
+class GlesTransport;
+enum class VrGraphicsApi { kVulkan, kOpenGles };
+
+class OpenXrBackend final {
+ public:
+  OpenXrBackend() = default;
+  ~OpenXrBackend();
+  OpenXrBackend(const OpenXrBackend&) = delete;
+  OpenXrBackend& operator=(const OpenXrBackend&) = delete;
+
+  // Claims the process-wide backend slot and creates XrInstance/system.
+  Status Arm(VrGraphicsApi graphics_api = VrGraphicsApi::kVulkan);
+  // EGL context must be current on the calling thread. Resolver bypasses guest
+  // hooks.
+  Status AttachGlesContext(void *display, void *config, void *context,
+                           void *egl_get_proc, void *(*resolve)(const char *));
+  void DetachGlesContext(void *context);
+  void NoteGlesPresent();
+  void *WrapGlesProcAddress(const char *name, void *raw);
+  // Idempotent full teardown (XR resources first, then the instance).
+  void Disarm();
+  bool armed() const { return armed_.load(std::memory_order_acquire); }
+
+  // Adapter delegation. Return false when the backend does not own creation
+  // (caller falls back to the plain host loader path).
+  bool CreateVulkanInstance(const VkInstanceCreateInfo* create_info,
+                            const VkAllocationCallbacks* allocator,
+                            VkInstance* instance, VkResult* result);
+  bool CreateVulkanDevice(VkPhysicalDevice physical_device,
+                          const VkDeviceCreateInfo* create_info,
+                          const VkAllocationCallbacks* allocator,
+                          VkDevice* device, VkResult* result);
+  void NoteDeviceDestroyed(VkDevice device);
+  void NoteInstanceDestroyed(VkInstance instance);
+  void NoteQueue(VkDevice device, VkQueue queue, std::uint32_t family,
+                 std::uint32_t index);
+  std::vector<std::uint32_t> DesktopQueueFamilies(VkDevice device) const;
+  void RecordCommandPool(VkDevice device, VkCommandPool pool,
+                         std::uint32_t family);
+  void RecordCommandBuffers(VkDevice device, VkCommandPool pool,
+                            std::uint32_t count,
+                            const VkCommandBuffer* buffers);
+  void ForgetCommandBuffers(std::uint32_t count,
+                            const VkCommandBuffer* buffers);
+  void ForgetCommandPool(VkCommandPool pool);
+  void ResetCommandPool(VkCommandPool pool);
+  void ResetCommandBuffer(VkCommandBuffer buffer);
+  void NoteCommandBuffersSubmitted(VkQueue queue, std::uint32_t count,
+                                   const VkCommandBuffer* buffers);
+  VkImageLayout NormalizeDesktopBarrier(VkCommandBuffer command, VkImage image,
+                                        std::uint32_t* source,
+                                        std::uint32_t* destination,
+                                        VkImageLayout* old_layout,
+                                        VkImageLayout new_layout);
+
+  // Resource provenance recording (adapter wrappers).
+  bool WantsResourceRecords() const {
+    return recording_.load(std::memory_order_acquire);
+  }
+  void RecordImage(VkDevice device, VkImage image,
+                   const VkImageCreateInfo* info);
+  void RecordImageView(VkImageView view, VkImage image);
+  void RecordFramebuffer(VkFramebuffer framebuffer,
+                         const VkFramebufferCreateInfo* info);
+  void RecordRenderPass(VkRenderPass render_pass,
+                        const VkRenderPassCreateInfo* info);
+  void NoteDestroyImage(VkImage image);
+  void NoteDestroyImageView(VkImageView view);
+  void NoteDestroyFramebuffer(VkFramebuffer framebuffer);
+  void NoteRenderPassBegin(VkCommandBuffer command_buffer,
+                           const VkRenderPassBeginInfo* info);
+  bool EyeBindingComplete() const {
+    return eyes_bound_.load(std::memory_order_acquire);
+  }
+
+  // Render-thread frame cycle at host present begin.
+  void NoteHostPresent(VkQueue queue, VkDevice device);
+  // VK_NOT_READY leaves the present untouched until eye submission provenance
+  // is known. VK_SUCCESS means its waits were consumed on the graphics queue,
+  // so the eye copies that follow there are ordered after them. The present
+  // must then wait on *ready instead (none when it is VK_NULL_HANDLE).
+  VkResult PrepareHostPresent(VkQueue queue, VkDevice device,
+                              const VkPresentInfoKHR* info, VkSemaphore* ready);
+  void RecordDesktopSwapchain(VkDevice device, VkSwapchainKHR swapchain,
+                              const VkSwapchainCreateInfoKHR* info,
+                              const VkImage* images, unsigned count,
+                              bool converted_to_concurrent = false);
+  // On success the original present semaphores have been consumed by the
+  // mirror blit on the GPU. The caller must present waiting only on *ready,
+  // which the blit signals. The CPU never waits for the guest's frame here.
+  VkResult MirrorDesktop(VkQueue queue, const VkPresentInfoKHR* info,
+                         VkSemaphore* ready);
+
+  // Pose published for the frame that is about to render. The device bridge
+  // reads it once per frame on the render thread and injects it into the
+  // guest. valid=false until the XR session located a usable head pose.
+  // hands[0]=left, hands[1]=right carry this frame's tracked controller grip
+  // poses (metres, LOCAL space) when a controller layer is active.
+  ScriptedPoseSample PublishedHeadPose() const;
+  bool RecommendedEyeExtent(std::uint32_t* width, std::uint32_t* height) const;
+  void NotePoseApplied(void* owner, std::uint64_t frame);
+
+  // Controller input delivery, consumed by the window-thread input runtime
+  // through the C ABI in xr_controller_abi.h. TakeControllerDelivery pops one
+  // batch produced by the once-per-frame action sync; it returns false when
+  // no controller layer is active or nothing is queued. The snapshot exposes
+  // the current levels for overflow resync. Haptics requests are thread-safe.
+  bool TakeControllerDelivery(ControllerDelivery* out);
+  ControllerSnapshot ControllerSnapshotForFrame() const;
+  void RequestControllerHaptics(int hand, float amplitude,
+                                std::uint64_t duration_ns, float frequency_hz);
+
+  void StopControllerHaptics(int hand);
+
+  // Diagnostics.
+  std::uint64_t submitted_frames() const {
+    return submitted_frames_.load(std::memory_order_relaxed);
+  }
+  std::uint64_t skipped_frames() const {
+    return skipped_frames_.load(std::memory_order_relaxed);
+  }
+  bool session_running() const {
+    return session_running_.load(std::memory_order_relaxed);
+  }
+  std::string runtime_name() const;
+
+ private:
+  friend struct OpenXrBackendTestAccess;
+  struct ImageRecord {
+    VkImage image = VK_NULL_HANDLE;
+    VkDevice device = VK_NULL_HANDLE;
+    std::uint32_t width = 0;
+    std::uint32_t height = 0;
+    VkFormat format = VK_FORMAT_UNDEFINED;
+    VkImageUsageFlags usage = 0;
+    VkSampleCountFlagBits samples = VK_SAMPLE_COUNT_1_BIT;
+    void* owner = nullptr;
+    std::uint64_t order = 0;
+  };
+  struct EyeBinding {
+    bool valid = false;
+    std::uint64_t frame = 0;
+    VkImage image = VK_NULL_HANDLE;
+    VkFramebuffer framebuffer = VK_NULL_HANDLE;
+    VkImageLayout final_layout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL;
+    void* owner = nullptr;
+    std::uint32_t width = 0;
+    std::uint32_t height = 0;
+    VkFormat format = VK_FORMAT_UNDEFINED;
+  };
+  struct EyeSwapchain {
+    void* swapchain = nullptr;  // XrSwapchain (opaque to keep the header XR-free)
+    std::vector<VkImage> images;
+    std::vector<std::uint32_t> gl_images;
+    std::uint32_t acquired_index = 0;
+    bool image_acquired = false;
+    std::uint32_t width = 0;
+    std::uint32_t height = 0;
+    VkFormat format = VK_FORMAT_UNDEFINED;
+  };
+
+  bool InitializeSessionLocked(VkPhysicalDevice physical_device,
+                               VkDevice device,
+                               const VkDeviceCreateInfo* create_info,
+                               std::string* error);
+  // Session-owned controller action layer (poses, buttons, axes, haptics).
+  // Created at instance level, attached per session, detached on teardown so
+  // a replacement session never reuses stale spaces.
+  XrActions actions_;
+  bool actions_created_ = false;
+  // Shared by action sync, snapshots, haptics and lifecycle operations.
+  // Acquired after mutex_ on the render thread, but never held across
+  // xrWaitFrame; the input thread takes only this controller lock.
+  mutable std::mutex controller_mutex_;
+  // Syncs actions once per frame at the predicted display time and folds the
+  // resulting hand poses into published_pose_ before the guest renders.
+  void SyncControllersLocked(std::uint64_t predicted_display_time);
+  bool InitializeGlesSessionLocked(std::string *error);
+  bool InitializeSessionResourcesLocked(std::string *error);
+  bool CopyGlesEyesIntoSwapchains();
+  bool EnsureXrInstanceLocked(std::string* error = nullptr);
+  void DestroyXrInstanceLocked();
+  void DisarmLocked();
+  void* ResolveFunction(const char* name) const;
+  void SetupDeviceAfterCreationLocked(VkPhysicalDevice physical_device,
+                                      VkDevice device,
+                                      const VkDeviceCreateInfo* create_info);
+  void TeardownSessionLocked(const char* reason, bool preserve_device = false);
+  void HandleSessionState(int state);
+  void HandleReferenceSpaceChange(std::int64_t change_time);
+  bool RecoverSessionLocked(std::uint64_t now_ns);
+  // False only when the runtime names a GPU other than the guest device's.
+  bool RuntimeUsesGuestGpuLocked();
+  void PollSessionEvents();
+  bool SupportsPresentQueueLocked(VkQueue queue) const;
+  VkQueue GraphicsQueueForPresentLocked(VkQueue present) const;
+  bool unsupported_present_queue_logged_ = false;
+  // Drops the pose/images of the frame currently in flight without touching
+  // guest ownership, so the next xrEndFrame submits no layer instead of an
+  // image paired with a pose that no longer describes the same origin.
+  void InvalidateInFlightPose(const char* reason);
+  void RunFrameCycle(VkQueue queue, VkDevice device);
+  // Returns true when the backend owns this present but ran no XR frame, so
+  // the caller paces the guest itself.
+  bool NoteHostPresentLocked(VkQueue queue, VkDevice device);
+  bool CreateSwapchains(std::string* error);
+  // Recreates the eye swapchains once in the format that copies the guest's
+  // eye bytes without a gamma change (see PreferredEyeSwapchainFormat).
+  void MatchSwapchainFormatToEyesLocked();
+  void DestroySwapchains();
+  bool EnsureCopyResources(VkDevice device, std::uint32_t queue_family,
+                           std::string* error);
+  void DestroyCopyResources();
+  // Records both eye copies (and, when the mirror is enabled, both staging
+  // readbacks) into one command buffer and submits it once. Only the shared
+  // memory mirror waits for it; the headset path leaves it to the GPU.
+  bool CopyEyesIntoSwapchains(VkQueue queue);
+  void RecordEyeCopiesLocked(VkCommandBuffer command, const VkImage source[2],
+                             const VkImage destination[2]);
+  void RecordFilteredEyesLocked(VkCommandBuffer command, bool smaa);
+  // Per-frame GPU work (desktop mirror, eye copies) is submitted without a CPU
+  // wait. A slot is reused only after its fence signalled; its images let a
+  // guest destroy wait for the submissions that still read them.
+  struct AsyncSubmission {
+    VkCommandBuffer command = VK_NULL_HANDLE;
+    VkFence fence = VK_NULL_HANDLE;
+    bool pending = false;
+    std::uint64_t serial = 0;  // bumped per submission
+    std::vector<VkImage> images;
+  };
+  // The shared-memory mirror's readback from the previous frame copy. It is
+  // published at the next copy, when the GPU has long finished it, so neither
+  // the headset nor the mirror makes the CPU wait for the frame.
+  struct MirrorReadback {
+    AsyncSubmission* slot = nullptr;
+    std::uint64_t serial = 0;
+    std::uint64_t frame = 0;
+    VkFormat format = VK_FORMAT_UNDEFINED;
+    std::uint32_t width = 0;
+    std::uint32_t height = 0;
+  };
+  void PublishMirrorReadbackLocked();
+  // vr.anti_aliasing: fxaa. The eye copy becomes one FXAA draw per eye into
+  // the runtime's swapchain image. Anything it cannot set up falls back to
+  // the plain copy, which never loses headset output.
+  struct FxaaState {
+    VkFormat target_format = VK_FORMAT_UNDEFINED;
+    VkShaderModule vertex = VK_NULL_HANDLE;
+    VkShaderModule fragment = VK_NULL_HANDLE;
+    VkSampler sampler = VK_NULL_HANDLE;
+    VkDescriptorSetLayout set_layout = VK_NULL_HANDLE;
+    VkDescriptorPool pool = VK_NULL_HANDLE;
+    VkDescriptorSet sets[2] = {};
+    VkPipelineLayout layout = VK_NULL_HANDLE;
+    VkRenderPass render_pass = VK_NULL_HANDLE;
+    VkPipeline pipeline = VK_NULL_HANDLE;
+    // The eye image each set samples, and its view.
+    VkImage sources[2] = {};
+    VkImageView source_views[2] = {};
+    // Per eye, one view and framebuffer per runtime swapchain image.
+    std::vector<VkImageView> target_views[2];
+    std::vector<VkFramebuffer> framebuffers[2];
+    bool failed = false;
+  };
+  // vr.anti_aliasing. SMAA shares FXAA's final pass, targets and eye views.
+  enum class AntiAliasing { kOff, kFxaa, kSmaa };
+  AntiAliasing AntiAliasingMode() const;
+  // Pipeline, targets and eye bindings for this frame; false means copy.
+  bool PrepareFxaaLocked();
+  bool CreateFxaaPipelineLocked(VkFormat target_format);
+  bool CreateFullscreenPipelineLocked(VkShaderModule vertex,
+                                      VkShaderModule fragment,
+                                      VkPipelineLayout layout,
+                                      VkRenderPass render_pass,
+                                      VkPipeline* pipeline);
+  void DestroyFxaaTargetsLocked();
+  void ForgetFxaaSourceLocked(VkImage image);
+  void DestroyFxaaLocked();
+  // SMAA: edge detection and blending weights into per-eye images, then
+  // neighborhood blending into FXAA's swapchain targets.
+  struct SmaaPass {
+    VkDescriptorSetLayout set_layout = VK_NULL_HANDLE;
+    VkPipelineLayout layout = VK_NULL_HANDLE;
+    VkRenderPass render_pass = VK_NULL_HANDLE;
+    VkPipeline pipeline = VK_NULL_HANDLE;
+    VkDescriptorSet sets[2] = {};
+  };
+  struct SmaaImage {
+    VkImage image = VK_NULL_HANDLE;
+    VkDeviceMemory memory = VK_NULL_HANDLE;
+    VkImageView view = VK_NULL_HANDLE;
+  };
+  struct SmaaState {
+    std::vector<VkShaderModule> modules;
+    VkDescriptorPool pool = VK_NULL_HANDLE;
+    SmaaPass edges, weights, blend;
+    SmaaImage area, search;
+    // Per eye, at the eye's extent.
+    SmaaImage edge_images[2], weight_images[2];
+    VkFramebuffer edge_framebuffers[2] = {};
+    VkFramebuffer weight_framebuffers[2] = {};
+    std::uint32_t width = 0, height = 0;
+    VkFormat target_format = VK_FORMAT_UNDEFINED;
+    // The eye views the edge and blend sets were written with.
+    VkImageView bound_sources[2] = {};
+    bool failed = false;
+  };
+  bool PrepareSmaaLocked();
+  bool CreateSmaaPipelinesLocked();
+  bool CreateSmaaImageLocked(VkFormat format, std::uint32_t width,
+                             std::uint32_t height, VkImageUsageFlags usage,
+                             SmaaImage* out);
+  bool UploadSmaaLookupLocked(SmaaImage* image, std::uint32_t width,
+                              std::uint32_t height, const void* bytes,
+                              std::size_t size);
+  void DestroySmaaImageLocked(SmaaImage* image);
+  void DestroySmaaTargetsLocked();
+  void DestroySmaaLocked();
+  // The next slot, recorded-ready, or nullptr when its previous submission
+  // did not finish in time (the device is hung or lost).
+  AsyncSubmission* NextAsyncSubmissionLocked();
+  VkResult SubmitAsyncLocked(VkQueue queue, AsyncSubmission* slot,
+                             const VkSubmitInfo& submit);
+  // Waits for pending submissions reading `image`, or all of them for
+  // VK_NULL_HANDLE.
+  void WaitAsyncSubmissionsLocked(VkImage image);
+  // Semaphore the present of `image_index` waits on, created on first use.
+  enum class PresentStep { kMirror, kPrepare };
+  VkSemaphore PresentReadySemaphoreLocked(VkSwapchainKHR swapchain,
+                                          std::uint32_t image_index,
+                                          PresentStep step);
+  void DestroyRetiredSemaphoresLocked();
+  // In-headset keyboard: show/hide from the host's TextBox request, pointer
+  // input, and trigger masking. Runs inside the controller sync.
+  void UpdateVirtualKeyboardLocked();
+  // Rasterizes and uploads the panel when it changed. Returns true when the
+  // keyboard swapchain holds a released image ready for a quad layer.
+  bool PrepareVirtualKeyboardLayerLocked(VkQueue queue);
+  bool UploadVirtualKeyboardVulkan(VkQueue queue, VkImage image);
+  void DestroyVirtualKeyboardStaging();
+  void DestroyVirtualKeyboardResources();
+  bool CaptureEyeEvidence(VkQueue queue, int eye);
+  ScriptedPoseSample ComputeScriptedPose(std::uint64_t frame) const;
+  void EnsureMirrorForExtent(std::uint32_t width, std::uint32_t height);
+  MirrorVkProcs MirrorProcs() const;
+
+  VrGraphicsApi graphics_api_ = VrGraphicsApi::kVulkan;
+  GlesTransport *gles_ = nullptr;
+  std::uint64_t gl_min_version_ = 0;
+  std::uint64_t gl_max_version_ = 0;
+
+  // Held for a whole XR frame cycle and by every path that can destroy the
+  // session; always taken before mutex_.
+  std::mutex frame_mutex_;
+  mutable std::mutex mutex_;
+  // The frame cycle's hold on mutex_, so it can release it around
+  // xrWaitFrame. Only set while NoteHostPresent runs the cycle.
+  std::unique_lock<std::mutex>* state_lock_ = nullptr;
+  std::atomic<bool> armed_{false};
+  std::atomic<bool> recording_{false};
+  std::atomic<bool> eyes_bound_{false};
+  std::atomic<bool> session_running_{false};
+  std::atomic<std::uint64_t> submitted_frames_{0};
+  std::atomic<std::uint64_t> skipped_frames_{0};
+
+  // XR handles are stored as opaque pointers in the header; the implementation
+  // casts them back. This keeps vulkan-only consumers free of OpenXR headers.
+  void* xr_instance_ = nullptr;
+  std::uint64_t xr_system_ = 0;
+  void* xr_session_ = nullptr;
+  void* xr_local_space_ = nullptr;
+  void* xr_view_space_ = nullptr;
+  void* xr_stage_space_ = nullptr;
+  std::uint32_t xr_eye_width_[2] = {};
+  std::uint32_t xr_eye_height_[2] = {};
+  EyeSwapchain eye_swapchains_[2];
+  VirtualKeyboard keyboard_;
+  std::unique_ptr<VirtualKeyboardRasterizer> keyboard_raster_;
+  EyeSwapchain keyboard_swapchain_;
+  bool keyboard_swapchain_failed_ = false;
+  bool keyboard_image_ready_ = false;
+  std::uint64_t keyboard_uploaded_revision_ = 0;
+  // A new showKeyboard request may open the panel; Close disarms it until
+  // Roblox drops that request.
+  bool keyboard_armed_ = true;
+  pose::Pose keyboard_head_{};
+  bool keyboard_head_valid_ = false;
+  std::vector<std::uint8_t> keyboard_pixels_;
+  VkBuffer keyboard_staging_ = VK_NULL_HANDLE;
+  VkDeviceMemory keyboard_staging_memory_ = VK_NULL_HANDLE;
+  void* keyboard_staging_mapped_ = nullptr;
+  int xr_blend_mode_ = 0;
+  // Runtime name captured at xrCreateInstance so the bind-time diagnostics line
+  // can report it without re-entering runtime_name() under the held mutex.
+  std::string runtime_name_;
+  bool xr_instance_used_ = false;
+  // Libraries the runtime's first instance loaded; later instances load them
+  // with RTLD_DEEPBIND (see EnsureXrInstanceLocked).
+  std::vector<std::string> runtime_libraries_;
+  std::string user_manifest_;
+  std::string runtime_manifest_;
+
+  VkInstance vk_instance_ = VK_NULL_HANDLE;
+  VkDevice vk_device_ = VK_NULL_HANDLE;
+  VkPhysicalDevice vk_physical_device_ = VK_NULL_HANDLE;
+  std::uint32_t vk_queue_family_ = 0;
+  VkQueue vk_graphics_queue_ = VK_NULL_HANDLE;
+  std::vector<std::uint32_t> device_queue_families_;
+  void* vk_loader_ = nullptr;
+  struct VkProcs;
+  VkProcs* vk_ = nullptr;
+
+  VkCommandPool copy_pool_ = VK_NULL_HANDLE;
+  // Synchronous one-off work: keyboard uploads, evidence, present fallback.
+  VkCommandBuffer copy_command_ = VK_NULL_HANDLE;
+  VkFence copy_fence_ = VK_NULL_HANDLE;
+  // Two submissions per frame, so three frames may be in flight.
+  static constexpr std::size_t kAsyncSubmissions = 6;
+  std::array<AsyncSubmission, kAsyncSubmissions> async_{};
+  std::size_t next_async_ = 0;
+  MirrorReadback mirror_readback_{};
+  FxaaState fxaa_{};
+  SmaaState smaa_{};
+  // The mirror's signal for this present, which PrepareHostPresent passes on.
+  VkSemaphore mirror_ready_ = VK_NULL_HANDLE;
+  // Semaphores of destroyed desktop swapchains. A present may still wait on
+  // one, so they are destroyed only once the device is idle.
+  std::vector<VkSemaphore> retired_semaphores_;
+  std::unordered_map<VkFormat, VkFormatFeatureFlags> blit_features_;
+
+  // Optional desktop two-eye mirror (MOCKTAIL_VR_MIRROR_SHM). Publishes the
+  // latest complete pair through shared memory; inert when unset.
+  VrMirror mirror_;
+
+  std::unordered_map<VkImage, ImageRecord> images_;
+  struct DesktopSwapchain {
+    VkExtent2D extent;
+    VkFormat format;
+    std::vector<VkImage> images;
+    VkSharingMode sharing_mode = VK_SHARING_MODE_EXCLUSIVE;
+    std::vector<std::uint32_t> families;
+    bool converted_to_concurrent = false;
+    // Two per image, see PresentReadySemaphoreLocked.
+    std::vector<VkSemaphore> ready;
+  };
+  std::unordered_map<VkSwapchainKHR, DesktopSwapchain> desktop_swapchains_;
+  std::unordered_map<VkImageView, VkImage> image_views_;
+  std::unordered_map<VkFramebuffer, std::vector<VkImageView>> framebuffer_views_;
+  std::unordered_map<VkFramebuffer, VkRenderPass> framebuffer_render_pass_;
+  std::unordered_map<VkRenderPass, std::vector<VkImageLayout>> render_pass_final_layouts_;
+  std::unordered_map<VkQueue, std::uint32_t> queue_families_;
+  struct CommandRecord {
+    VkCommandPool pool = VK_NULL_HANDLE;
+    std::uint32_t family = UINT32_MAX;
+    std::vector<std::pair<VkImage, std::uint64_t>> eye_images;
+  };
+  std::unordered_map<VkCommandPool, std::uint32_t> command_pool_families_;
+  std::unordered_map<VkCommandBuffer, CommandRecord> command_records_;
+  std::unordered_map<VkImage, VkQueue> eye_render_queues_;
+  std::unordered_map<VkImage, std::uint64_t> eye_render_frames_;
+  std::uint64_t image_order_ = 0;
+  EyeBinding eyes_[2];
+
+  // Frame cycle state (render thread only).
+  bool frame_open_ = false;
+  bool frame_should_render_ = false;
+  // A running session is hidden in SYNCHRONIZED; shouldRender still governs rendering.
+  bool visibility_lost_ = false;
+  bool session_recovery_pending_ = false;
+  std::uint64_t next_session_retry_ns_ = 0;
+  // Consecutive failed session recoveries, for backoff and for deciding when
+  // the XrInstance itself must be recreated (e.g. after a runtime restart).
+  std::uint32_t session_recovery_failures_ = 0;
+  bool xr_instance_stale_ = false;
+  bool present_sync_failure_logged_ = false;
+  bool gles_attach_failed_ = false;
+  // Runtime swapchain formats, and the format chosen once the guest eye
+  // format is known (VK_FORMAT_UNDEFINED until then).
+  std::vector<std::int64_t> xr_swapchain_formats_;
+  VkFormat eye_swapchain_format_ = VK_FORMAT_UNDEFINED;
+  VkFormat eye_format_checked_ = VK_FORMAT_UNDEFINED;
+  std::uint64_t frame_display_time_ = 0;
+  // MOCKTAIL_VR_UNPACED benchmark mode: guest presents before this monotonic
+  // time leave the open XR frame alone instead of blocking in xrWaitFrame.
+  std::uint64_t frame_due_ns_ = 0;
+  struct ViewState {
+    float position[3];
+    float orientation[4];
+    float fov[4];  // angleLeft, angleRight, angleUp, angleDown (radians)
+    bool valid;
+  };
+  ViewState frame_views_[2] = {};
+  struct PoseStorage {
+    float position[3] = {0.f, 0.f, 0.f};
+    float orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  };
+  PoseStorage frame_view_poses_[2];
+  bool frame_views_valid_ = false;
+  // One-shot guard so a canted-view runtime reports the rejection reason once
+  // instead of once per frame per eye.
+  bool projection_rejection_logged_ = false;
+  mutable ScriptedPoseSample published_pose_;
+  std::uint64_t xr_frame_counter_ = 0;
+  std::unordered_map<void*, std::uint64_t> applied_poses_;
+};
+
+// Process-wide single backend owned by main. Adapter hooks resolve these
+// exported C symbols; they are inert while no backend is armed.
+OpenXrBackend* ActiveVrBackend();
+
+// Paths of the shared objects mapped into the process.
+std::vector<std::string> LoadedSharedObjects();
+// Paths mapped now that were not in `before`.
+std::vector<std::string> SharedObjectsLoadedSince(
+    const std::vector<std::string>& before);
+
+// Holds the runtime's libraries open with RTLD_DEEPBIND while the OpenXR
+// loader loads the runtime, so its Vulkan calls bind to its own libvulkan
+// dependency instead of the Vulkan adapter's exported hooks. Released after
+// the loader holds its own reference, so the runtime still unloads with its
+// instance.
+class DeepBoundLibraries {
+ public:
+  explicit DeepBoundLibraries(const std::vector<std::string>& paths);
+  ~DeepBoundLibraries();
+  DeepBoundLibraries(const DeepBoundLibraries&) = delete;
+  DeepBoundLibraries& operator=(const DeepBoundLibraries&) = delete;
+
+ private:
+  std::vector<void*> handles_;
+};
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_OPENXR_BACKEND_H_
@@ -0,0 +1,34 @@
+#ifndef MOCKTAIL_VR_OPENXR_PREVIEW_H_
+#define MOCKTAIL_VR_OPENXR_PREVIEW_H_
+
+#include <array>
+#include <cstdint>
+#include <string>
+
+namespace mocktail::vr {
+
+struct PreviewOptions {
+  // Zero keeps the scene open until the runtime or user requests exit.
+  std::uint32_t frame_limit = 0;
+};
+
+struct PreviewResult {
+  bool success = false;
+  std::string message;
+  std::uint64_t frames = 0;
+  std::uint64_t rendered_frames = 0;
+  std::uint64_t tracked_frames = 0;
+  std::array<float, 3> head_position{};
+  std::array<float, 4> head_orientation{0, 0, 0, 1};
+};
+
+// Runs a native Vulkan/OpenXR scene with a panel fixed in LOCAL space. The
+// compositor projects it into both eyes. Roblox images/input are not connected.
+// Call on the main thread: SIGINT/SIGTERM request a graceful session exit, and
+// their previous handlers are restored before returning.
+PreviewResult RunOpenXrPreview(const PreviewOptions& options = {});
+std::string FormatPreviewResult(const PreviewResult& result);
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_OPENXR_PREVIEW_H_
@@ -0,0 +1,52 @@
+#ifndef MOCKTAIL_VR_OPENXR_PROBE_H_
+#define MOCKTAIL_VR_OPENXR_PROBE_H_
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace mocktail::vr {
+
+enum class ProbeStatus {
+  kReady,
+  kBuildDisabled,
+  kRuntimeUnavailable,
+  kHeadsetUnavailable,
+  kIncompatibleRuntime,
+  kError,
+};
+
+struct ViewConfiguration {
+  std::uint32_t width = 0;
+  std::uint32_t height = 0;
+  std::uint32_t samples = 0;
+};
+
+struct ProbeReport {
+  ProbeStatus status = ProbeStatus::kError;
+  std::string message;
+  std::string sdk_version;
+  std::string runtime_name;
+  std::string runtime_version;
+  std::string system_name;
+  std::vector<std::string> extensions;
+  std::vector<ViewConfiguration> views;
+  bool orientation_tracking = false;
+  bool position_tracking = false;
+  std::string minimum_vulkan_version;
+  std::string maximum_vulkan_version;
+};
+
+// Native host discovery only. Does not load Roblox, change the active runtime,
+// create a graphics device/session, or claim that VR rendering is implemented.
+ProbeReport ProbeOpenXr();
+std::string FormatProbeReport(const ProbeReport& report);
+int ProbeExitCode(ProbeStatus status);
+
+// False in builds configured without MOCKTAIL_ENABLE_VR; --vr fails closed
+// early in that case instead of starting Roblox without VR support.
+bool IsOpenXrSupportCompiled();
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_OPENXR_PROBE_H_
@@ -0,0 +1,130 @@
+#ifndef MOCKTAIL_VR_ROBLOX_VR_DEVICE_BRIDGE_H_
+#define MOCKTAIL_VR_ROBLOX_VR_DEVICE_BRIDGE_H_
+
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <string_view>
+
+#include "compat/build_profile.h"
+#include "mocktail/status.h"
+
+namespace mocktail::vr {
+namespace internal {
+struct VrBridgeTestAccess;
+struct VrBuildContract;
+}
+
+const compat::VrDebugDeviceBridgeProfile* FindRobloxVrDeviceProfile(
+    std::string_view build_id);
+
+// Human-readable list of the Roblox builds VR supports, e.g.
+// "2998 (2.736.1408) and 3092 (2.738.1397)", for error messages.
+std::string DescribeSupportedVrBuilds();
+
+// Experimental native stereo bring-up for the exact Build-ID-scoped
+// RBX::Graphics::DebugDeviceVR object of the guest client.
+//
+// The bridge interposes the state and eye getters of the exact guest build.
+// Resource readiness is checked on the live object during each state call;
+// initialization never dereferences cached guest object/device pointers. The
+// guest owns resource destruction. Recreated objects and reused addresses
+// therefore need no cache invalidation. Initialization happens only on a thread
+// observed presenting.
+class RobloxVrDeviceBridge final {
+public:
+  using StateGetterFn = void *(*)(void *result_buffer, void *device_object);
+  using EyeGetterFn = void *(*)(void *device_object, int eye_index);
+  using EyeInitializerFn = void (*)(void *device_object, void *graphics_device);
+
+  RobloxVrDeviceBridge() = default;
+  ~RobloxVrDeviceBridge();
+
+  RobloxVrDeviceBridge(const RobloxVrDeviceBridge &) = delete;
+  RobloxVrDeviceBridge &operator=(const RobloxVrDeviceBridge &) = delete;
+
+  // Arms the bridge for an exact-build profile that carries
+  // vr_debug_device_bridge metadata. Claims the process-wide bridge slot.
+  Status Install(const compat::BuildProfile &profile);
+
+  // Validates machine contracts at the loaded image base and interposes the
+  // two DebugDeviceVR vtable slots. Called once, after libroblox relocations
+  // and before any guest startup code runs.
+  Status Activate(std::uintptr_t image_base);
+
+  // Restores the interposed vtable slots and disarms. Safe to call twice.
+  void Shutdown();
+
+  bool installed() const { return installed_; }
+  bool active() const { return active_.load(std::memory_order_acquire); }
+
+  // Render-thread notification from the Vulkan adapter's host present path.
+  void NoteHostPresent();
+
+  // Guest-side hooks invoked by the interposed vtable stubs.
+  void OnHapticsCall(void* device_object, int hand, float amplitude);
+  // HapticService:SetMotor on Gamepad1 LeftHand (0) / RightHand (1); the
+  // level holds until the game sets it again.
+  void OnSetMotorCall(int hand, float amplitude);
+  void OnPointerFrameCall(void* result, void* service);
+  void OnStateGetterCall(void *result_buffer, void *device_object);
+  void OnEyeGetterCall(void *device_object, int eye_index, void *framebuffer);
+
+  StateGetterFn original_state_getter() const {
+    return original_state_getter_.load(std::memory_order_acquire);
+  }
+  EyeGetterFn original_eye_getter() const {
+    return original_eye_getter_.load(std::memory_order_acquire);
+  }
+
+  // Cumulative initialization diagnostics (not a count of live devices).
+  std::uintptr_t image_base() const {
+    return image_base_.load(std::memory_order_acquire);
+  }
+  int captured_device_count() const;
+  int initialized_device_count() const;
+  std::uint64_t present_count() const {
+    return present_count_.load(std::memory_order_relaxed);
+  }
+  std::uint64_t eye_getter_call_count(int eye_index) const;
+
+private:
+  friend struct internal::VrBridgeTestAccess;
+  static constexpr std::uint64_t kEyeGetterSummaryInterval = 600;
+  bool ValidateObjectHeader(void *self) const;
+  void *ValidatedGraphicsDevice(void *self) const;
+  void TryInitializeEyes(void *self);
+  bool RestoreVtableLocked();
+
+  mutable std::mutex mutex_;
+  compat::VrDebugDeviceBridgeProfile profile_{};
+  const internal::VrBuildContract* contract_ = nullptr;
+  bool installed_ = false;
+  std::atomic<bool> active_{false};
+  std::atomic<std::uintptr_t> image_base_{0};
+  std::atomic<std::uintptr_t> image_size_{0};
+  std::uintptr_t *vtable_ = nullptr;
+  std::uintptr_t original_haptic_slot_ = 0;
+  std::uintptr_t original_state_slot_ = 0;
+  std::uintptr_t original_eye_slot_ = 0;
+  std::atomic<StateGetterFn> original_state_getter_{nullptr};
+  std::atomic<EyeGetterFn> original_eye_getter_{nullptr};
+  std::atomic<std::uint64_t> present_thread_{0};
+  std::atomic<std::uint64_t> present_count_{0};
+  std::atomic<bool> flag_warning_logged_{false};
+  std::atomic<int> captured_count_{0};
+  std::atomic<int> initialized_count_{0};
+  mutable std::atomic<std::uint64_t> eye_call_totals_[2] = {};
+};
+
+// Process-wide single active bridge, mirroring the audio output-device
+// bridge ownership model. Install claims the slot; the destructor releases
+// it. legacy_runtime forwards the loaded libroblox image base through
+// NotifyRobloxVrImageLoaded; it is a successful no-op while no bridge is
+// armed, and fail-closed once one is.
+Status NotifyRobloxVrImageLoaded(std::uintptr_t image_base);
+
+} // namespace mocktail::vr
+
+#endif // MOCKTAIL_VR_ROBLOX_VR_DEVICE_BRIDGE_H_
@@ -0,0 +1,191 @@
+#ifndef MOCKTAIL_VR_VIRTUAL_KEYBOARD_H_
+#define MOCKTAIL_VR_VIRTUAL_KEYBOARD_H_
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "mocktail/vr/vr_pose_math.h"
+
+namespace mocktail::vr {
+
+// Host side of the in-headset keyboard. The window module owns Roblox's
+// TextBox focus and the SDL event path; main wires these callbacks so the VR
+// library never links the window library. Every callback may be called from
+// the render thread and must be thread-safe.
+struct VirtualKeyboardHost {
+  void* context = nullptr;
+  // True while Roblox has asked for an on-screen keyboard (showKeyboard).
+  bool (*input_requested)(void* context) = nullptr;
+  // Commits UTF-8 text exactly like an SDL_EVENT_TEXT_INPUT.
+  void (*commit_text)(void* context, const char* utf8) = nullptr;
+  // Presses and releases one SDL scancode exactly like a physical key.
+  void (*press_key)(void* context, std::uint32_t scancode) = nullptr;
+};
+
+// Installs the process-wide host. Passing nullptr clears it.
+void SetVirtualKeyboardHost(const VirtualKeyboardHost* host);
+VirtualKeyboardHost CurrentVirtualKeyboardHost();
+
+// The focused TextBox's current contents, shown in the panel's text field.
+// The desktop draws TextBox text as a window overlay that never reaches the
+// eye images, so the headset would otherwise show an empty box. Safe from any
+// thread; the text is sensitive and is never logged.
+struct VirtualKeyboardText {
+  std::string utf8;
+  int cursor_utf16 = 0;
+  bool password = false;
+  std::uint64_t revision = 0;
+};
+void SetVirtualKeyboardText(const char* utf8, std::size_t size,
+                            int cursor_utf16, bool password);
+void ClearVirtualKeyboardText();
+VirtualKeyboardText CurrentVirtualKeyboardText();
+
+enum class VirtualKeyAction {
+  kText,       // commits text, or shift_text under Shift/Caps Lock
+  kBackspace,
+  kEnter,
+  kTab,
+  kShift,      // one-shot
+  kCapsLock,
+  kSpace,
+  kClose,      // Escape: leaves the TextBox and hides the panel
+};
+
+struct VirtualKey {
+  std::string label;
+  std::string text;        // committed text for kText
+  std::string shift_text;  // committed under Shift (Caps Lock for letters)
+  VirtualKeyAction action = VirtualKeyAction::kText;
+  // Panel UV rectangle, origin top-left, both axes 0..1.
+  float u0 = 0.f, v0 = 0.f, u1 = 0.f, v1 = 0.f;
+};
+
+// One controller's pointing state for a frame. Positions are metres in the
+// OpenXR LOCAL space; the ray points along the aim pose's -Z axis.
+struct VirtualKeyboardPointer {
+  bool valid = false;
+  pose::Pose aim{};
+  float trigger = 0.f;  // 0..1
+};
+
+// What the keyboard asks the host to do after an Update.
+struct VirtualKeyboardOutput {
+  std::vector<std::string> text;          // committed in order
+  std::vector<std::uint32_t> scancodes;   // pressed in order, after text
+};
+
+// Ray/quad intersection. The quad is centred on `quad` with its face along
+// +Z, `width` x `height` metres. Returns false when the ray misses or points
+// away. u/v are panel UVs (origin top-left).
+bool IntersectVirtualKeyboardPanel(const pose::Pose& quad, float width,
+                                   float height, const pose::Pose& aim,
+                                   float* u, float* v, float* distance);
+
+// Pure keyboard state machine: layout, paging, shift, hover, trigger edges and
+// backspace auto-repeat. No OpenXR, Vulkan or SDL types, so it is unit-tested
+// directly.
+class VirtualKeyboard {
+ public:
+  // A text field over 15 x 5 normal-key units, 4 cm per unit.
+  static constexpr float kPanelWidthMetres = 0.60f;
+  static constexpr float kPanelHeightMetres = 0.248f;
+  // Texture aspect matches the panel so keys are not stretched.
+  static constexpr int kTextureWidth = 1500;
+  static constexpr int kTextureHeight = 620;
+  // Top share of the panel holding the text field; keys fill the rest.
+  static constexpr float kFieldFraction = 120.f / 620.f;
+
+  VirtualKeyboard();
+
+  // Opens the panel in front of `head` (LOCAL space), below eye level and
+  // tilted up toward the viewer. Resets Shift and hover; keeps Caps Lock.
+  void Show(const pose::Pose& head);
+  void Hide();
+  bool visible() const { return visible_; }
+  const pose::Pose& panel_pose() const { return panel_; }
+
+  // Text shown in the field. Bumps the revision only when it changed.
+  void SetText(const VirtualKeyboardText& text);
+  const std::string& text() const { return text_.utf8; }
+  int text_cursor_utf16() const { return text_.cursor_utf16; }
+  bool text_password() const { return text_.password; }
+
+  // Processes one frame of both pointers. now_ns is monotonic.
+  VirtualKeyboardOutput Update(std::uint64_t now_ns,
+                               const VirtualKeyboardPointer (&pointers)[2]);
+
+  // True when this hand's trigger belongs to the keyboard this frame (aimed
+  // at the panel, or a press that began on it is still held, including after
+  // the panel hid mid-press). The backend withholds that trigger from Roblox
+  // so a key press is not also a click.
+  bool CapturesTrigger(int hand) const;
+
+  // Current layout, with Shift/Caps Lock applied to the labels.
+  const std::vector<VirtualKey>& keys() const;
+  // -1 when the hand is not over a key.
+  int hovered_key(int hand) const { return hands_[hand & 1].hovered; }
+  int pressed_key(int hand) const { return hands_[hand & 1].pressed; }
+  // Pointer position on the panel, when the hand is over it.
+  bool cursor(int hand, float* u, float* v) const;
+  bool shifted() const { return shift_; }
+  bool caps_lock() const { return caps_lock_; }
+
+  // Advances whenever anything visible changes; the backend re-rasterizes
+  // and re-uploads only when this moves.
+  std::uint64_t revision() const { return revision_; }
+
+ private:
+  struct Hand {
+    int hovered = -1;
+    int pressed = -1;   // key under an active press, -1 otherwise
+    bool trigger_down = false;
+    bool captured = false;
+    bool over_panel = false;
+    float u = 0.f, v = 0.f;
+    std::uint64_t repeat_at_ns = 0;
+  };
+
+  void RebuildLayout();
+  int KeyAt(float u, float v) const;
+  std::string Output(const VirtualKey& key) const;
+  void Activate(const VirtualKey& key, VirtualKeyboardOutput* output);
+  void Touch() { ++revision_; }
+
+  bool visible_ = false;
+  bool shift_ = false;
+  bool caps_lock_ = false;
+  pose::Pose panel_{};
+  VirtualKeyboardText text_;
+  Hand hands_[2];
+  // A press the keyboard owned when it hid; held until that trigger releases.
+  bool release_pending_[2] = {false, false};
+  std::uint64_t cursor_drawn_ns_ = 0;
+  std::vector<VirtualKey> keys_;
+  std::uint64_t revision_ = 1;
+};
+
+// Draws the keyboard into a tightly packed RGBA8 buffer
+// (VirtualKeyboard::kTextureWidth x kTextureHeight, sRGB-encoded, opaque).
+// Glyphs come from SDL3_ttf with fontconfig's sans fallback chain and are
+// cached per label, so redraws after the first are plain fills and blits.
+class VirtualKeyboardRasterizer {
+ public:
+  VirtualKeyboardRasterizer();
+  ~VirtualKeyboardRasterizer();
+  VirtualKeyboardRasterizer(const VirtualKeyboardRasterizer&) = delete;
+  VirtualKeyboardRasterizer& operator=(const VirtualKeyboardRasterizer&) =
+      delete;
+
+  // Returns false when no font could be opened; keys still draw, unlabelled.
+  bool Draw(const VirtualKeyboard& keyboard, std::vector<std::uint8_t>* rgba);
+
+ private:
+  struct Impl;
+  Impl* impl_ = nullptr;
+};
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_VIRTUAL_KEYBOARD_H_
@@ -0,0 +1,105 @@
+#ifndef MOCKTAIL_VR_MIRROR_H_
+#define MOCKTAIL_VR_MIRROR_H_
+
+#include <vulkan/vulkan.h>
+
+#include <cstdint>
+#include <string>
+
+#include "mocktail/vr/vr_mirror_shm.h"
+
+namespace mocktail::vr {
+
+// The subset of device/instance procs the mirror needs, supplied by the XR
+// backend from its already-resolved guest-device table. Keeping this explicit
+// avoids a second proc table and keeps the mirror independently testable.
+struct MirrorVkProcs {
+  PFN_vkCreateBuffer CreateBuffer = nullptr;
+  PFN_vkDestroyBuffer DestroyBuffer = nullptr;
+  PFN_vkGetBufferMemoryRequirements GetBufferMemoryRequirements = nullptr;
+  PFN_vkAllocateMemory AllocateMemory = nullptr;
+  PFN_vkFreeMemory FreeMemory = nullptr;
+  PFN_vkBindBufferMemory BindBufferMemory = nullptr;
+  PFN_vkMapMemory MapMemory = nullptr;
+  PFN_vkUnmapMemory UnmapMemory = nullptr;
+  PFN_vkCmdCopyImageToBuffer CmdCopyImageToBuffer = nullptr;
+  PFN_vkCmdPipelineBarrier CmdPipelineBarrier = nullptr;
+  PFN_vkGetPhysicalDeviceMemoryProperties GetPhysicalDeviceMemoryProperties =
+      nullptr;
+};
+
+// Producer side of the desktop two-eye mirror. Maps a POSIX shared-memory
+// segment (created with the name from MOCKTAIL_VR_MIRROR_SHM) and publishes
+// the latest complete eye pair under a seqlock. It owns two persistent,
+// bounded host-visible staging buffers reused across frames; the GPU->staging
+// copies are recorded into the caller's single batched command buffer so the
+// mirror adds no extra queue submission or fence wait.
+//
+// The mirror never touches the filesystem on the frame path and keeps only the
+// newest pair (one latest slot), so a slow consumer drops rather than queues
+// old frames.
+class VrMirror {
+ public:
+  VrMirror() = default;
+  ~VrMirror();
+  VrMirror(const VrMirror&) = delete;
+  VrMirror& operator=(const VrMirror&) = delete;
+
+  bool enabled() const { return mapping_ != nullptr; }
+
+  // Opens the shared segment. Returns false (and stays disabled) when the name
+  // is empty or mapping fails; the XR path then runs without a mirror.
+  bool Open(const std::string& shm_name, std::uint32_t width,
+            std::uint32_t height, std::string* error);
+  void Close();
+
+  // Ensures the two staging buffers match width*height*4 bytes on this device.
+  // Allocates once; a size/device change recreates them. Existing contents are
+  // discarded on resize.
+  bool EnsureStaging(const MirrorVkProcs& vk, VkDevice device,
+                     VkPhysicalDevice physical, std::uint32_t width,
+                     std::uint32_t height, std::string* error);
+  void DestroyStaging(const MirrorVkProcs& vk);
+
+  // Records a source-eye -> staging-buffer copy for one eye into cmd, adding
+  // the layout barriers around it. The source is returned to final_layout so
+  // the next guest render pass sees it unchanged.
+  void RecordEyeCopy(const MirrorVkProcs& vk, VkCommandBuffer cmd, int eye,
+                     VkImage source, VkImageLayout final_layout,
+                     std::uint32_t width, std::uint32_t height);
+
+  // After the batched fence wait completed, copies both staging buffers into
+  // the shared segment and bumps the seqlock with the frame id and a monotonic
+  // timestamp. No-op when staging does not cover width*height.
+  void Publish(std::uint64_t frame, VkFormat format, std::uint32_t width,
+               std::uint32_t height, std::uint64_t now_ns);
+
+  std::uint64_t published_pairs() const { return published_pairs_; }
+  std::uint32_t staging_width() const { return staging_width_; }
+  std::uint32_t staging_height() const { return staging_height_; }
+  const void* mapping() const { return mapping_; }
+
+  // Test seam: publish a pair from caller-supplied staging bytes without any
+  // Vulkan resources, exercising the same seqlock/segment write as the GPU
+  // path. Both buffers must hold width*height*4 bytes.
+  void PublishFromBytesForTest(std::uint64_t frame, VkFormat format,
+                               std::uint32_t width, std::uint32_t height,
+                               std::uint64_t now_ns, const void* eye0,
+                               const void* eye1);
+
+ private:
+  void* mapping_ = nullptr;
+  std::uint64_t mapping_bytes_ = 0;
+  std::string shm_name_;
+  VkBuffer staging_[2] = {VK_NULL_HANDLE, VK_NULL_HANDLE};
+  VkDeviceMemory staging_memory_[2] = {VK_NULL_HANDLE, VK_NULL_HANDLE};
+  void* staging_map_[2] = {nullptr, nullptr};
+  std::uint32_t staging_width_ = 0;
+  std::uint32_t staging_height_ = 0;
+  VkDevice staging_device_ = VK_NULL_HANDLE;
+  std::uint64_t published_pairs_ = 0;
+};
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_MIRROR_H_
@@ -0,0 +1,42 @@
+#ifndef MOCKTAIL_VR_MIRROR_SHM_H_
+#define MOCKTAIL_VR_MIRROR_SHM_H_
+
+#include <cstdint>
+
+namespace mocktail::vr {
+
+// Shared-memory transport for the desktop two-eye mirror. The producer (XR
+// backend, inside the client process) publishes the latest complete eye pair
+// under a seqlock; the consumer (desktop viewer) reads the newest pair without
+// any per-frame filesystem transport, image encode/decode, or allocation.
+//
+// Layout is fixed and little-endian.
+// sizeof(VrMirrorHeader) == kVrMirrorHeaderBytes.
+struct VrMirrorHeader {
+  std::uint32_t magic;          // kVrMirrorMagic
+  std::uint32_t header_bytes;   // kVrMirrorHeaderBytes (pixel area offset)
+  std::uint64_t seq;            // seqlock: odd while writing, even when stable
+  std::uint64_t frame;          // XR frame id the pair belongs to
+  std::uint32_t width;          // eye width in pixels
+  std::uint32_t height;         // eye height in pixels
+  std::uint32_t format;         // VkFormat of the source eye images
+  std::uint32_t flags;          // bit0: a complete, valid pair is present
+  std::uint64_t producer_ns;    // CLOCK_MONOTONIC publish timestamp
+  std::uint64_t published_pairs;
+  std::uint64_t reserved;
+};
+
+inline constexpr std::uint32_t kVrMirrorMagic = 0x3152564D;  // 'MVR1'
+inline constexpr std::uint32_t kVrMirrorHeaderBytes = 64;
+inline constexpr std::uint32_t kVrMirrorFlagValid = 1u << 0;
+
+// Total mapped bytes for a given eye extent (header + two RGBA/BGRA images).
+inline std::uint64_t VrMirrorBytes(std::uint32_t width, std::uint32_t height) {
+  return static_cast<std::uint64_t>(kVrMirrorHeaderBytes) +
+         2ull * static_cast<std::uint64_t>(width) *
+             static_cast<std::uint64_t>(height) * 4ull;
+}
+
+}  // namespace mocktail::vr
+
+#endif  // MOCKTAIL_VR_MIRROR_SHM_H_
@@ -0,0 +1,102 @@
+#ifndef MOCKTAIL_VR_PERF_H_
+#define MOCKTAIL_VR_PERF_H_
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace mocktail::vr::perf {
+
+// Opt-in, low-overhead stage timing and counter instrumentation. Collection is
+// compiled out at runtime unless MOCKTAIL_VR_PERF is set, so the steady-state
+// path only pays a single cached boolean test per record.
+bool Enabled();
+
+enum class Stage {
+  kFrameCycle,
+  kXrWaitFrame,
+  kXrBeginFrame,
+  kXrLocateViews,
+  kSwapchainAcquire,
+  kSwapchainWait,
+  kCopyRecord,
+  kCopySubmit,
+  kCopyFenceWait,
+  kMirrorPublish,
+  kEvidence,
+  kControllerSync,
+  kDesktopMirror,
+  kPresentPrepare,
+  kPresentInterval,
+  kStageCount,
+};
+
+enum class Counter {
+  kPresents,
+  kFramesBegun,
+  kFramesSubmitted,
+  kFramesSkipped,
+  kSkipShouldRender,
+  kSkipPoseInvalid,
+  kSkipEyesUnbound,
+  kSkipEyeFrameMismatch,
+  kSubmits,
+  kFenceWaits,
+  kMirrorPairs,
+  kMirrorDrops,
+  kSkipVisibilityLost,
+  kReferenceSpaceChanges,
+  kVisibilityLost,
+  kVisibilityGained,
+  kFramesInvalidated,
+  kControllerSyncs,
+  kCounterCount,
+};
+
+const char* StageName(Stage stage);
+const char* CounterName(Counter counter);
+
+// Bounded reservoir per stage: the most recent N samples are kept and ranked
+// only when a report is emitted (once per interval), never on the frame path.
+class Collector {
+ public:
+  static constexpr std::size_t kReservoir = 4096;
+  static constexpr std::uint64_t kIntervalNs = 1'000'000'000ULL;
+
+  void Record(Stage stage, std::uint64_t nanos);
+  void Count(Counter counter, std::uint64_t delta = 1);
+
+  // Emits one distribution line per active stage plus a counter line when at
+  // least kIntervalNs elapsed since the previous emission. Cheap no-op
+  // otherwise. now_ns is a CLOCK_MONOTONIC timestamp supplied by the caller so
+  // the collector stays clock-agnostic and testable.
+  void EmitIfDue(std::uint64_t now_ns, const char* context);
+
+  // Test/inspection accessors.
+  std::uint64_t counter(Counter counter_id) const;
+  std::vector<std::uint64_t> Percentiles(Stage stage) const;  // p50,p95,p99,max
+  std::size_t Samples(Stage stage) const;
+  void Reset();
+
+ private:
+  struct StageStat {
+    std::vector<std::uint64_t> samples;  // ring, bounded by kReservoir
+    std::size_t head = 0;
+    std::size_t count = 0;
+    std::uint64_t total_ns = 0;
+  };
+  StageStat stages_[static_cast<std::size_t>(Stage::kStageCount)]{};
+  std::uint64_t counters_[static_cast<std::size_t>(Counter::kCounterCount)]{};
+  std::uint64_t last_emit_ns_ = 0;
+  std::uint64_t window_start_ns_ = 0;
+};
+
+// Process-wide collector used by the XR backend frame cycle.
+Collector& ProcessCollector();
+
+// Monotonic nanoseconds (CLOCK_MONOTONIC), 0 on failure.
+std::uint64_t NowNs();
+
+}  // namespace mocktail::vr::perf
+
+#endif  // MOCKTAIL_VR_PERF_H_
@@ -0,0 +1,217 @@
+#ifndef MOCKTAIL_VR_POSE_MATH_H_
+#define MOCKTAIL_VR_POSE_MATH_H_
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+
+namespace mocktail::vr::pose {
+
+// Coordinate spaces and units used across the whole camera path, documented so
+// every stage is auditable:
+//
+//   OpenXR head/views  metres, right-handed, +Y up, -Z forward, LOCAL space
+//     -> published pose  metres, quaternion (x, y, z, w), unchanged units
+//     -> guest state     metres; the exact-build native helper converts metres
+//                        to studs itself (factor 10/3). This layer must never
+//                        pre-apply that scale.
+//     -> camera          engine composes
+//                        out.rotation = base.rotation * head.rotation
+//                        out.position = base.position
+//                                       + base.rotation * head.position * HeadScale
+//                        where HeadScale is an engine value distinct from the
+//                        metres-to-studs conversion factor.
+//     -> render          one pass per eye using the per-eye offset/FOV
+//     -> XR submission   metres again, the very pose used to render the pair.
+
+struct Vec3 {
+  float x = 0.f, y = 0.f, z = 0.f;
+};
+
+struct Quat {
+  float x = 0.f, y = 0.f, z = 0.f, w = 1.f;
+};
+
+struct Pose {
+  Vec3 position{};
+  Quat orientation{};
+};
+
+inline constexpr float kPi = 3.14159265358979323846f;
+
+inline Quat QuatMultiply(const Quat& a, const Quat& b) {
+  return Quat{
+      a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+      a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+      a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
+      a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
+  };
+}
+
+inline Quat QuatConjugate(const Quat& q) { return Quat{-q.x, -q.y, -q.z, q.w}; }
+
+inline float QuatNorm(const Quat& q) {
+  return std::sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w);
+}
+
+// Returns false for a non-finite or near-zero quaternion; the output is left
+// untouched in that case so callers never publish a fabricated rotation.
+inline bool QuatNormalize(const Quat& in, Quat* out) {
+  if (out == nullptr) {
+    return false;
+  }
+  if (!std::isfinite(in.x) || !std::isfinite(in.y) || !std::isfinite(in.z) ||
+      !std::isfinite(in.w)) {
+    return false;
+  }
+  const float norm = QuatNorm(in);
+  if (!(norm > 1e-6f) || !std::isfinite(norm)) {
+    return false;
+  }
+  const float inverse = 1.f / norm;
+  *out = Quat{in.x * inverse, in.y * inverse, in.z * inverse, in.w * inverse};
+  return true;
+}
+
+// q and -q denote the same rotation. Used to prove the path is sign-invariant.
+inline bool QuatSameRotation(const Quat& a, const Quat& b, float tolerance) {
+  const float dot = a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
+  return std::abs(std::abs(dot) - 1.f) <= tolerance;
+}
+
+inline Vec3 QuatRotate(const Quat& q, const Vec3& v) {
+  // t = 2 * cross(q.xyz, v); v' = v + q.w * t + cross(q.xyz, t)
+  const Vec3 u{q.x, q.y, q.z};
+  const Vec3 cross1{u.y * v.z - u.z * v.y, u.z * v.x - u.x * v.z,
+                    u.x * v.y - u.y * v.x};
+  const Vec3 t{2.f * cross1.x, 2.f * cross1.y, 2.f * cross1.z};
+  const Vec3 cross2{u.y * t.z - u.z * t.y, u.z * t.x - u.x * t.z,
+                    u.x * t.y - u.y * t.x};
+  return Vec3{v.x + q.w * t.x + cross2.x, v.y + q.w * t.y + cross2.y,
+              v.z + q.w * t.z + cross2.z};
+}
+
+// result = a * b in SE(3): apply b first, then a.
+inline Pose PoseMultiply(const Pose& a, const Pose& b) {
+  Pose result;
+  result.orientation = QuatMultiply(a.orientation, b.orientation);
+  const Vec3 rotated = QuatRotate(a.orientation, b.position);
+  result.position = Vec3{a.position.x + rotated.x, a.position.y + rotated.y,
+                         a.position.z + rotated.z};
+  return result;
+}
+
+inline Pose PoseInverse(const Pose& p) {
+  Pose result;
+  result.orientation = QuatConjugate(p.orientation);
+  const Vec3 neg{-p.position.x, -p.position.y, -p.position.z};
+  result.position = QuatRotate(result.orientation, neg);
+  return result;
+}
+
+// Rotation for a head turned by yaw about +Y then pitched about +X, matching
+// the scripted diagnostic motion. Quaternion order is (x, y, z, w).
+inline Quat QuatFromYawPitch(float yaw, float pitch) {
+  const float cy = std::cos(yaw * 0.5f), sy = std::sin(yaw * 0.5f);
+  const float cp = std::cos(pitch * 0.5f), sp = std::sin(pitch * 0.5f);
+  return Quat{cy * sp, sy * cp, -sy * sp, cy * cp};
+}
+
+inline Quat QuatFromAxisAngle(const Vec3& axis, float angle) {
+  const float half = angle * 0.5f;
+  const float s = std::sin(half);
+  return Quat{axis.x * s, axis.y * s, axis.z * s, std::cos(half)};
+}
+
+// Per-eye FOV as the runtime reports it: angleLeft, angleRight, angleUp,
+// angleDown in radians, each signed relative to the eye's forward axis.
+struct EyeFov {
+  float angle_left = 0.f;
+  float angle_right = 0.f;
+  float angle_up = 0.f;
+  float angle_down = 0.f;
+};
+
+// The guest state stores projection tangents, not angles. The 2998 layout is
+// up, down, left, right in that order; down/left are negated because the
+// guest's tangent space measures them in the opposite direction. Getting this
+// order or a sign wrong flips or shears the image, so it is pinned by test.
+struct ProjectionTangents {
+  float up = 0.f;
+  float down = 0.f;
+  float left = 0.f;
+  float right = 0.f;
+};
+
+inline ProjectionTangents FovToTangents(const EyeFov& fov) {
+  return ProjectionTangents{std::tan(fov.angle_up), std::tan(-fov.angle_down),
+                            std::tan(-fov.angle_left), std::tan(fov.angle_right)};
+}
+
+inline constexpr float kMaxEyeFovAngle = 1.56f;
+
+// Enclose the display frustum in a head-parallel camera for the guest renderer.
+// The compositor receives this rendered FOV and pose, not the canted display's.
+inline bool ParallelEyeFov(const Quat& eye_orientation, const EyeFov& display,
+                           EyeFov* rendered) {
+  Quat orientation;
+  if (!rendered || !QuatNormalize(eye_orientation, &orientation) ||
+      !(display.angle_left < display.angle_right) ||
+      !(display.angle_down < display.angle_up)) {
+    return false;
+  }
+  const float angles[] = {display.angle_left, display.angle_right,
+                          display.angle_up, display.angle_down};
+  for (float angle : angles) {
+    if (!std::isfinite(angle) || std::abs(angle) >= kMaxEyeFovAngle)
+      return false;
+  }
+  if (orientation.x == 0.f && orientation.y == 0.f && orientation.z == 0.f) {
+    *rendered = display;
+    return true;
+  }
+  const float xs[] = {std::tan(display.angle_left),
+                      std::tan(display.angle_right)};
+  const float ys[] = {std::tan(display.angle_down), std::tan(display.angle_up)};
+  float left = 0.f, right = 0.f, down = 0.f, up = 0.f;
+  bool first = true;
+  for (float x : xs) {
+    for (float y : ys) {
+      const Vec3 ray = QuatRotate(orientation, {x, y, -1.f});
+      if (!std::isfinite(ray.z) || ray.z >= -1e-6f) return false;
+      const float horizontal = ray.x / -ray.z;
+      const float vertical = ray.y / -ray.z;
+      if (!std::isfinite(horizontal) || !std::isfinite(vertical)) return false;
+      if (first) {
+        left = right = horizontal;
+        down = up = vertical;
+        first = false;
+      } else {
+        left = std::min(left, horizontal);
+        right = std::max(right, horizontal);
+        down = std::min(down, vertical);
+        up = std::max(up, vertical);
+      }
+    }
+  }
+  const EyeFov result{std::atan(left), std::atan(right), std::atan(up),
+                      std::atan(down)};
+  const float bounds[] = {result.angle_left, result.angle_right,
+                          result.angle_up, result.angle_down};
+  for (float angle : bounds) {
+    if (std::abs(angle) >= kMaxEyeFovAngle) return false;
+  }
+  *rendered = result;
+  return true;
+}
+
+// Metres-to-studs factor the exact-build native helper applies itself. Exposed
+// only so tests can prove this layer does NOT pre-apply it.
+inline constexpr float kMetresToStuds = 10.f / 3.f;
+
+// Expected stud value for a metre offset, for numerical unit checks.
+inline float MetresToStuds(float metres) { return metres * kMetresToStuds; }
+
+}  // namespace mocktail::vr::pose
+
+#endif  // MOCKTAIL_VR_POSE_MATH_H_
@@ -0,0 +1,101 @@
+#ifndef MOCKTAIL_VR_XR_ACTIONS_H_
+#define MOCKTAIL_VR_XR_ACTIONS_H_
+
+#include <cstdint>
+#include <string>
+
+#include "mocktail/status.h"
+#include "mocktail/vr/vr_pose_math.h"
+#include "mocktail/vr/xr_controller.h"
+
+namespace mocktail::vr {
+
+// Session-owned OpenXR action layer: one action set, left/right subactions,
+// grip+aim pose spaces, and interaction-profile bindings for Touch (primary),
+// Quest 2, Index, Vive wands and the simple controller. All XR handles stay
+// opaque here so non-OpenXR consumers (bridge, tests) need no XR headers.
+//
+// Frame contract: Sync() runs exactly once per frame from the backend frame
+// cycle, immediately after xrWaitFrame returned the predicted display time and
+// before the guest renders, so located hand poses share the head/eye frame.
+// There is no second frame wait and no polling from guest getters.
+class XrActions final {
+public:
+  XrActions() = default;
+  ~XrActions();
+  XrActions(const XrActions &) = delete;
+  XrActions &operator=(const XrActions &) = delete;
+
+  // Creates the action set/actions and suggests bindings. Instance-level:
+  // valid before any session exists. Failure is non-fatal for XR output; the
+  // backend logs and continues without controller input.
+  Status Create(void *xr_instance);
+
+  // Attaches to a session and creates the per-hand pose spaces. Must be
+  // called after xrCreateSession and before the first Sync; recreated on every
+  // session replacement (no stale handles survive).
+  Status Attach(void *xr_instance, void *xr_session, void *xr_local_space);
+
+  // Destroys spaces and detaches; the action set survives for reattach.
+  void Detach();
+  void Destroy();
+
+  bool attached() const { return attached_; }
+
+  // One per-frame sync at predicted_display_time. Locates grip and aim poses
+  // in the session's LOCAL space, reads analog/boolean states, refreshes
+  // connection state from the runtime's current interaction profile, and
+  // builds the coherent snapshot + delivery batch. Returns false when actions
+  // are unavailable (runtime refused sync); input is reset and a disconnect
+  // remains drainable even while the session is detached.
+  bool Sync(void *xr_session, std::uint64_t predicted_display_time,
+            std::uint64_t frame, std::uint64_t session_generation);
+
+  // Latest coherent snapshot (frame/session generation tagged).
+  const ControllerSnapshot &snapshot() const { return snapshot_; }
+  // Hand poses in metres/LOCAL space for the state-copy records.
+  const VrHandPose &hand(int index) const { return hands_[index & 1]; }
+
+  // Drains the next pending delivery batch built by Sync. Returns false when
+  // nothing is queued. Thread-safe: Sync runs on the render thread, the drain
+  // runs on the window thread. Backed by a bounded queue, so a slow consumer
+  // drops oldest frames and converges via resync rather than growing.
+  bool TakeDelivery(ControllerDelivery *out);
+
+  // Queues a vibration request for one hand. Safe from any thread; applied on
+  // the next Sync's XR call window. amplitude [0,1], duration in nanoseconds
+  // (0 = runtime default). A newer request for the same hand replaces the
+  // pending one. StopHaptics cancels.
+  void RequestHaptics(int hand, float amplitude, std::uint64_t duration_ns,
+                      float frequency_hz);
+
+  void StopHaptics(int hand);
+
+  // Interaction-profile diagnostics (refreshed on profile-change events and
+  // every Sync that observes a change).
+  std::string ActiveProfile(int hand) const;
+
+  // Test seam: publish an externally sourced profile name (event dispatch in
+  // the backend) without XR calls.
+  void NoteProfileChanged();
+
+  // Called by the backend on focus/session loss, under controller ownership.
+  void ResetInput();
+
+private:
+  struct Impl;
+  Impl *impl_ = nullptr;
+  bool created_ = false;
+  bool attached_ = false;
+  ControllerStateBuilder builder_;
+  ControllerSnapshot snapshot_;
+  VrHandPose hands_[2];
+  ControllerDeliveryQueue delivery_queue_;
+  std::uint64_t session_generation_ = 0;
+  // Last connection level handed to the consumer, to mark connection changes.
+  bool last_delivered_connected_[2] = {false, false};
+};
+
+} // namespace mocktail::vr
+
+#endif // MOCKTAIL_VR_XR_ACTIONS_H_
@@ -0,0 +1,236 @@
+#ifndef MOCKTAIL_VR_XR_CONTROLLER_H_
+#define MOCKTAIL_VR_XR_CONTROLLER_H_
+
+#include "mocktail/vr/xr_controller_abi.h"
+#include <array>
+#include <cstdint>
+#include <deque>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace mocktail::vr {
+
+// One tracked controller hand, located at the same predicted display time as
+// the head. Grip is the held-object pose; aim is the pointing pose. They are
+// not interchangeable: the guest consumes grip for hands/tools and aim for UI
+// rays. Position is metres, orientation a quaternion (x, y, z, w) in the
+// OpenXR LOCAL reference space. The guest applies its own metres-to-studs
+// conversion and hand pitch offset, so neither is pre-applied here.
+struct VrHandPose {
+  float grip_position[3] = {0.f, 0.f, 0.f};
+  float grip_orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  float aim_position[3] = {0.f, 0.f, 0.f};
+  float aim_orientation[4] = {0.f, 0.f, 0.f, 1.f};
+  // Pose validity, reported separately from button activity and connection so
+  // a controller can be connected with an untracked pose.
+  bool grip_valid = false;
+  bool aim_valid = false;
+};
+
+// Engine-facing controller capability, independent of which OpenXR
+// interaction profile supplied it. The guest receives buttons and analog axes
+// through its verified Android gamepad route, so this layer normalizes every
+// supported profile onto that one stable contract.
+enum class ControllerButton {
+  kTrigger,    // analog click semantics; value reported separately
+  kSqueeze,    // grip/squeeze
+  kThumbstick, // stick click
+  kFaceNorth,  // right B / left Y
+  kFaceSouth,  // right A / left X
+  kFaceEast,   // right B equivalent on layouts that have it
+  kFaceWest,   // left X equivalent
+  kMenu,       // application-accessible menu only; never a system button
+  kCount,
+};
+
+// Capacitive contacts are distinct from presses. Some runtimes/profiles do
+// not expose them; active=false means unavailable, not an inferred contact.
+enum class ControllerTouch {
+  kTrigger,
+  kThumbstick,
+  kThumbrest,
+  kA,
+  kB,
+  kX,
+  kY,
+  kCount
+};
+
+enum class ControllerAxis {
+  kTrigger,     // 0..1
+  kSqueeze,     // 0..1
+  kThumbstickX, // -1..1
+  kThumbstickY, // -1..1
+  kCount,
+};
+
+// Analog trigger/squeeze thresholds used only where the runtime exposes a
+// boolean click for an analog control. Hysteresis prevents edge chattering at
+// the boundary; native analog values are always preserved alongside it.
+struct AnalogClickThresholds {
+  float press = 0.75f;
+  float release = 0.6f;
+};
+
+// One coherent per-frame controller snapshot. Built once per frame by the
+// backend after a single xrSyncActions, then read by native getters without
+// re-polling. Button booleans are level state; edge detection happens once, at
+// publish time, so repeated native getters never emit duplicate edges.
+struct ControllerHandState {
+  bool connected = false;
+  bool pose_valid = false;
+  std::array<bool, static_cast<std::size_t>(ControllerTouch::kCount)> touches{};
+  std::array<bool, static_cast<std::size_t>(ControllerTouch::kCount)>
+      touch_active{};
+  std::array<bool, static_cast<std::size_t>(ControllerButton::kCount)>
+      buttons{};
+  std::array<float, static_cast<std::size_t>(ControllerAxis::kCount)> axes{};
+  // Interaction profile actually reported by the runtime for this hand, for
+  // diagnostics only (never used to gate input).
+  std::string profile;
+};
+
+struct ControllerSnapshot {
+  ControllerHandState hands[2]; // 0 = left, 1 = right
+  std::uint64_t frame = 0;
+  std::uint64_t session_generation = 0;
+};
+
+// Pure state machine: maps raw OpenXR action values onto the normalized
+// contract and derives edges exactly once per published frame. No OpenXR or
+// JNI types, so it is unit-testable with injected values.
+class ControllerStateBuilder {
+public:
+  explicit ControllerStateBuilder(AnalogClickThresholds thresholds = {});
+
+  // Records one raw action value for the given hand. Values not set by the
+  // runtime are neutral when explicitly marked inactive.
+  void SetTouch(int hand, ControllerTouch touch, bool value, bool active);
+  void SetButton(int hand, ControllerButton button, bool value, bool active);
+  void SetAxis(int hand, ControllerAxis axis, float value, bool active);
+  void SetConnected(int hand, bool connected);
+  void SetProfile(int hand, std::string profile);
+  void SetPoseValid(int hand, bool valid);
+
+  // Produces the snapshot for this frame and records which buttons changed so
+  // the caller can emit exactly one native edge per transition. frame must
+  // advance monotonically; publishing the same frame twice yields no edges.
+  struct Edge {
+    int hand = 0;
+    ControllerButton button = ControllerButton::kTrigger;
+    bool pressed = false;
+  };
+  ControllerSnapshot Publish(std::uint64_t frame, std::uint64_t generation,
+                             std::vector<Edge> *edges);
+
+  // Neutralizes all axes and releases held buttons once (focus loss,
+  // disconnect, session stop). Produces release edges for anything held so no
+  // button can stay stuck down.
+  void ReleaseAll(std::uint64_t frame, std::uint64_t generation,
+                  std::vector<Edge> *edges);
+
+  // Derives the click state for an analog control with hysteresis: latches on
+  // at `press`, off at `release`. Call after SetAxis for the same hand. Used
+  // for profiles that expose a trigger value without a click action; native
+  // analog values are always preserved regardless.
+  bool AnalogClick(int hand, ControllerAxis axis);
+
+  const ControllerSnapshot &snapshot() const { return snapshot_; }
+
+private:
+  AnalogClickThresholds thresholds_;
+  ControllerSnapshot snapshot_;
+  // Last published level per hand/button, used for edge detection.
+  std::array<
+      std::array<bool, static_cast<std::size_t>(ControllerButton::kCount)>, 2>
+      published_buttons_{};
+  // Hysteresis latch per (hand, analog control): [hand*2 + axis].
+  std::array<bool, 4> analog_latch_{};
+  bool have_published_ = false;
+};
+
+// Maps the normalized contract onto the guest's verified Android gamepad
+// identifiers, so XR controllers reuse the single authoritative input route
+// and cannot double-fire alongside a physical SDL gamepad. hand selects the
+// per-hand squeeze/thumbstick/trigger identifiers (0 = left, 1 = right).
+// Returns -1 when the control has no keycode (analog click).
+int32_t ControllerButtonToAndroidKey(int hand, ControllerButton button);
+// Returns the Android MotionEvent axis id for one axis of the given hand
+// (left/right trigger differ), or -1 when the control has no analog axis.
+int32_t ControllerAxisToAndroidAxis(int hand, ControllerAxis axis);
+// How many float components the guest expects for this axis (sticks 2, triggers
+// 1).
+int32_t ControllerAxisComponentCount(ControllerAxis axis);
+
+// SDL3 gamepad ordinals. XR controller delivery reuses the existing router
+// (RobloxInputRouter::HandleEvent) as the single authoritative event route:
+// the router performs the verified SDL->Android key/axis conversion, level
+// deduplication, focus gating and release-on-disconnect itself. Synthesized
+// platform events must therefore carry SDL ordinals, not Android codes.
+// hand selects the per-hand squeeze/thumbstick/trigger ordinals.
+int32_t ControllerButtonToSdlOrdinal(int hand, ControllerButton button);
+// SDL axis ordinal per hand for stick/trigger delivery; -1 when not an axis.
+// Left hand: LEFTX/LEFTY/TRIGGERLEFT; right: RIGHTX/RIGHTY/TRIGGERRIGHT.
+int32_t ControllerAxisToSdlOrdinal(int hand, ControllerAxis axis);
+
+// One drained delivery batch from the XR backend to the input route. Built
+// once per frame after xrSyncActions; edges appear exactly once. `resync`
+// requests full level re-delivery (recovery after queue overflow or an
+// unfocused drop) — the router deduplicates, so re-delivery is idempotent and
+// guarantees no button sticks down.
+struct ControllerDelivery {
+  std::uint64_t session_generation = 0;
+  bool button_levels[2][static_cast<std::size_t>(ControllerButton::kCount)] =
+      {};
+  bool connected[2] = {false, false};
+  bool connection_changed[2] = {false, false};
+  struct ButtonEdge {
+    int hand = 0;
+    ControllerButton button = ControllerButton::kTrigger;
+    bool pressed = false;
+  };
+  std::vector<ButtonEdge> edges;
+  // SDL ordinal order: LEFTX, LEFTY, RIGHTX, RIGHTY, TRIGGERLEFT, TRIGGERRIGHT.
+  float axes[6] = {0.f, 0.f, 0.f, 0.f, 0.f, 0.f};
+  bool axes_valid[2] = {false, false};
+  bool resync = false;
+  std::uint64_t frame = 0;
+
+  // Bounded growth guard: the backend caps the edge queue and sets resync
+  // instead of growing without limit.
+  static constexpr std::size_t kMaxEdges = 64;
+};
+
+bool EncodeNativeControllerChannels(const ControllerSnapshot &snapshot,
+                                    float (&channels)[28]);
+
+void EncodeControllerDelivery(const ControllerDelivery &delivery,
+                              MocktailVrControllerDelivery *out);
+
+// Thread-safe bounded queue between the XR render-thread producer (one push
+// per frame after xrSyncActions) and the window-thread consumer that drains
+// into the verified input route. Overflow drops the oldest frames and arms a
+// resync on the next delivered frame, so the consumer always converges to the
+// current levels and a full queue can never leave a button stuck down.
+class ControllerDeliveryQueue {
+public:
+  static constexpr std::size_t kCapacity = 8;
+
+  void Push(ControllerDelivery delivery);
+  bool Pop(ControllerDelivery *out);
+  std::size_t size() const;
+  bool overflowed() const { return overflowed_; }
+  std::uint64_t dropped_frames() const { return dropped_frames_; }
+  void Clear();
+
+private:
+  mutable std::mutex mutex_;
+  std::deque<ControllerDelivery> queue_;
+  bool overflowed_ = false;
+  std::uint64_t dropped_frames_ = 0;
+};
+
+} // namespace mocktail::vr
+
+#endif // MOCKTAIL_VR_XR_CONTROLLER_H_
@@ -0,0 +1,76 @@
+#ifndef MOCKTAIL_VR_XR_CONTROLLER_ABI_H_
+#define MOCKTAIL_VR_XR_CONTROLLER_ABI_H_
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* Plain-C mirror of mocktail::vr::ControllerDelivery for crossing the
+ * dlsym module boundary (XR backend -> input runtime) without exporting C++
+ * types or requiring the consumer to link OpenXR. Field order and types are
+ * the ABI; both sides include this header. Keep it POD: no constructors, no
+ * std, fixed arrays only. */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define MOCKTAIL_VR_CONTROLLER_MAX_EDGES 64
+#define MOCKTAIL_VR_CONTROLLER_BUTTON_COUNT 8
+#define MOCKTAIL_VR_CONTROLLER_AXIS_COUNT 6
+
+/* Button indices: mirror mocktail::vr::ControllerButton enum order. */
+enum {
+  MOCKTAIL_VR_BUTTON_TRIGGER = 0,
+  MOCKTAIL_VR_BUTTON_SQUEEZE = 1,
+  MOCKTAIL_VR_BUTTON_THUMBSTICK = 2,
+  MOCKTAIL_VR_BUTTON_FACE_NORTH = 3,
+  MOCKTAIL_VR_BUTTON_FACE_SOUTH = 4,
+  MOCKTAIL_VR_BUTTON_FACE_EAST = 5,
+  MOCKTAIL_VR_BUTTON_FACE_WEST = 6,
+  MOCKTAIL_VR_BUTTON_MENU = 7
+};
+
+typedef struct MocktailVrControllerEdge {
+  int32_t hand;    /* 0 = left, 1 = right */
+  int32_t button;  /* MOCKTAIL_VR_BUTTON_* */
+  int32_t pressed; /* 0/1 */
+} MocktailVrControllerEdge;
+
+typedef struct MocktailVrControllerDelivery {
+  uint64_t frame;
+  uint64_t session_generation;
+  int32_t connected[2];
+  int32_t connection_changed[2];
+  /* Current button levels per hand (MOCKTAIL_VR_BUTTON_* order). Used for
+   * resync after queue overflow: the consumer re-delivers every level and the
+   * router's deduplication makes it idempotent. */
+  int32_t button_levels[2][MOCKTAIL_VR_CONTROLLER_BUTTON_COUNT];
+  /* Analog levels in SDL gamepad axis order:
+   * 0=LEFTX 1=LEFTY 2=RIGHTX 3=RIGHTY 4=TRIGGERLEFT 5=TRIGGERRIGHT. */
+  float axes[MOCKTAIL_VR_CONTROLLER_AXIS_COUNT];
+  int32_t axes_valid[2];
+  int32_t resync;
+  int32_t edge_count;
+  MocktailVrControllerEdge edges[MOCKTAIL_VR_CONTROLLER_MAX_EDGES];
+} MocktailVrControllerDelivery;
+
+/* Pops the next delivery batch produced by the XR backend's once-per-frame
+ * action sync. Returns 1 and fills *out when a batch was queued, 0 when the
+ * queue is empty or no XR controller layer is active. Inert (returns 0) in
+ * non-VR builds and while no backend is armed. */
+typedef int32_t (*MocktailVrControllerPopFn)(MocktailVrControllerDelivery *out);
+
+/* Queues a vibration request for one hand (0=left, 1=right). amplitude is
+ * clamped to [0,1]; duration_ns 0 means the runtime default. Safe from any
+ * thread; applied on the next XR sync. No-op when no controller layer is
+ * active. */
+typedef void (*MocktailVrControllerHapticsFn)(int32_t hand, float amplitude,
+                                              uint64_t duration_ns,
+                                              float frequency_hz);
+typedef void (*MocktailVrControllerStopHapticsFn)(int32_t hand);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MOCKTAIL_VR_XR_CONTROLLER_ABI_H_ */
@@ -0,0 +1,27 @@
+#ifndef MOCKTAIL_RUNTIME_ASSET_OVERLAY_NAMES_H_
+#define MOCKTAIL_RUNTIME_ASSET_OVERLAY_NAMES_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <filesystem>
+#include <string>
+#include <vector>
+
+namespace mocktail {
+namespace runtime {
+
+// The rbxasset:// name of every regular file under <overlay_dir>/content, such
+// as rbxasset://textures/MouseLockedCursor.png. Sorted.
+std::vector<std::string> OverlayRbxAssetNames(
+    const std::filesystem::path& overlay_dir);
+
+// Roblox opens no local file for an rbxasset:// name it maps to a download.
+// Writes '!' over the first byte of each whole NUL-terminated copy of a name
+// in `data`, which unmaps it. Returns the number of copies changed.
+std::size_t DisableAssetNameMappings(std::uint8_t* data, std::size_t size,
+                                     const std::vector<std::string>& names);
+
+}
+}
+
+#endif
@@ -1,6 +1,7 @@
 #ifndef MOCKTAIL_RUNTIME_COMMAND_LINE_H_
 #define MOCKTAIL_RUNTIME_COMMAND_LINE_H_

+#include <optional>
 #include <string>
 #include <vector>

@@ -21,6 +22,7 @@ enum class WindowMode {
 struct CommandLineOptions {
  CommandMode mode = CommandMode::kRun;
  WindowMode window_mode = WindowMode::kUnspecified;
+  std::optional<bool> vr_enabled;
  std::string program_name = "mocktail";
  std::string roblox_library_path;
  std::string graphics_backend;
@@ -0,0 +1,68 @@
+#ifndef MOCKTAIL_RUNTIME_LUAU_CODEGEN_SWITCH_H_
+#define MOCKTAIL_RUNTIME_LUAU_CODEGEN_SWITCH_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <string_view>
+#include <vector>
+
+#include "runtime/roblox_experience_presence.h"
+
+namespace mocktail {
+namespace runtime {
+
+// Nightcap defaults this on and keeps it on only outside games; a user value
+// set in fflags.json or the overrides environment disables the switching.
+inline constexpr std::string_view kLuauCodegenAllClientSetting =
+    "FFlagDebugLuauCodegenAll";
+inline constexpr std::string_view kLuauCodegenAllFastFlagName =
+    "DebugLuauCodegenAll";
+
+struct LoadedImageSegment {
+  std::uintptr_t address = 0;
+  std::size_t size = 0;
+  bool writable = false;
+};
+
+std::vector<LoadedImageSegment> LoadedImageSegments(std::uintptr_t image_base);
+
+// Record layout: {u8 value; pad; const char* name; size_t length}, in a
+// writable segment filled by libroblox's static constructors. Returns null
+// unless exactly one record names a NUL-terminated copy of `name`.
+std::uint8_t* FindFastFlagValue(
+    const std::vector<LoadedImageSegment>& segments, std::string_view name);
+
+bool ClientSettingsSetLuauCodegenAll(std::string_view overrides_json);
+
+bool LuauCodegenAllForPhase(RobloxExperiencePresencePhase phase);
+
+// Locates the flag on the first notification; a byte that is not 0 or 1 is
+// left alone.
+class LuauCodegenMenuSwitch {
+ public:
+  using LocateFlagFn = std::function<std::uint8_t*()>;
+
+  LuauCodegenMenuSwitch(LocateFlagFn locate_flag,
+                        RobloxExperiencePresenceObserver next);
+
+  RobloxExperiencePresenceObserver observer();
+  void OnPhase(RobloxExperiencePresencePhase phase,
+               const RobloxExperienceLaunchRequest* request);
+
+ private:
+  static void Notify(void* context, RobloxExperiencePresencePhase phase,
+                     const RobloxExperienceLaunchRequest* request);
+
+  std::mutex mutex_;
+  LocateFlagFn locate_flag_;
+  bool located_ = false;
+  std::uint8_t* flag_ = nullptr;
+  const RobloxExperiencePresenceObserver next_;
+};
+
+}  // namespace runtime
+}  // namespace mocktail
+
+#endif  // MOCKTAIL_RUNTIME_LUAU_CODEGEN_SWITCH_H_
@@ -64,6 +64,11 @@ bool MergeRuntimeClientSettingsOverrides(
    std::string_view base_json, std::string* merged_json, std::string* error,
    std::vector<std::string>* kept_overrides = nullptr);

+// The resolved VR mode owns this flag in both client-settings channels.
+bool MergeVrClientSettingsOverrides(bool enabled, std::string_view base_json,
+                                    std::string* merged_json,
+                                    std::string* error);
+
 // Keeps the legacy test bypass disabled. The host PermissionsProtocol now
 // answers microphone authorization from capture configuration. No permission
 // query opens a recording device.
@@ -38,6 +38,16 @@ bool MergeDesktopAppPolicyClientSettingsOverride(std::string_view policy_json,
                                                 std::string* merged_json,
                                                 std::string* error);

+// Apply after desktop policy composition. Roblox 2998's Android payload is not
+// a VRAppBuild, so its LuaApp enables RunService's idle render throttle
+// even with DebugDeviceVR active. Preserve the effective app-policy (the later
+// fast-flags channel takes precedence) in both channels, changing only
+// ThrottleFramerate. This does not write the setting to appStorage.
+bool MergeVrAppPolicyClientSettingsOverrides(
+    bool enabled, std::string_view client_settings_json,
+    std::string_view fast_flags_json, std::string* merged_client_settings,
+    std::string* merged_fast_flags, std::string* error);
+
 }  // namespace runtime
 }  // namespace mocktail

@@ -19,6 +19,7 @@
 #include "runtime/roblox_experience_launch_bridge.h"
 #include "runtime/roblox_experience_presence.h"
 #include "runtime/roblox_fresh_game_launch_controller.h"
+#include "runtime/roblox_haptic_protocol_bridge.h"
 #include "runtime/roblox_account_bridge.h"
 #include "runtime/roblox_permissions_bridge.h"
 #include "runtime/roblox_web_view_bridge.h"
@@ -260,6 +261,7 @@ class RobloxExperienceComposition final {
  std::unique_ptr<RobloxBrowserServiceBridge> browser_service_bridge_;
  std::unique_ptr<RobloxPermissionsBridge> permissions_bridge_;
  std::unique_ptr<RobloxCallProtocolBridge> call_protocol_bridge_;
+  std::unique_ptr<RobloxHapticProtocolBridge> haptic_protocol_bridge_;
  // Optional: a payload without the AccountProtocol entrypoints still starts.
  std::unique_ptr<RobloxAccountBridge> account_bridge_;
  std::shared_ptr<WebViewHelperProcess> web_surface_process_;
@@ -0,0 +1,47 @@
+#ifndef MOCKTAIL_RUNTIME_ROBLOX_HAPTIC_PROTOCOL_BRIDGE_H_
+#define MOCKTAIL_RUNTIME_ROBLOX_HAPTIC_PROTOCOL_BRIDGE_H_
+
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+
+#include "runtime/roblox_message_bus_request_bridge.h"
+
+namespace mocktail {
+namespace runtime {
+
+using HapticSinkFn = std::function<void(int hand, float amplitude,
+                                        uint64_t duration_ns, float frequency_hz)>;
+using HapticStopFn = std::function<void(int hand)>;
+using HapticStateSyncFn = std::function<void(JNIEnv* env)>;
+
+class HapticWaveformPlayer;
+
+class RobloxHapticProtocolBridge final {
+ public:
+  RobloxHapticProtocolBridge(
+      JniEnvironmentProvider environment,
+      RobloxMessageBusSymbols symbols,
+      RobloxMessageBusObjects objects,
+      HapticSinkFn haptic_sink = nullptr,
+      HapticStopFn haptic_stop = nullptr,
+      HapticStateSyncFn haptic_state_sync = nullptr);
+  ~RobloxHapticProtocolBridge();
+
+  Status Initialize();
+  Status Shutdown();
+
+  static std::string GetMotorsJson();
+  // True during a VR session; main() sets MOCKTAIL_VR_ENABLED to 0 when VR
+  // cannot start, so the bridge stays off for desktop play.
+  static bool EnabledForThisSession();
+
+ private:
+  std::shared_ptr<HapticWaveformPlayer> player_;
+  std::unique_ptr<RobloxMessageBusRequestBridge> bridge_;
+};
+
+}  // namespace runtime
+}  // namespace mocktail
+#endif
@@ -89,6 +89,12 @@ struct RobloxTextDisplaySink {
  UpdateFn update = nullptr;
 };

+// Process-wide second observer of the focused TextBox display, called
+// synchronously after the surface overlay with the same sensitivity contract.
+// The VR keyboard uses it to show the text being typed in the headset, where
+// the desktop overlay is not visible. Passing an empty sink clears it.
+void SetRobloxTextDisplayMirror(RobloxTextDisplaySink sink);
+
 struct RobloxTextSink {
  using SyncFn = Status (*)(void* context, const char* utf8, std::size_t size,
                            int32_t cursor_utf16);
@@ -3,6 +3,7 @@

 #include <cstdint>
 #include <string>
+#include <vector>

 namespace mocktail {
 namespace runtime {
@@ -10,8 +11,10 @@ namespace runtime {
 // Android's RbxKeyboard resolves the Roblox Font enum through
 // assets/android/fonts/font-mappings.json. The selected file lives below
 // assets/content/fonts while legacy SourceSansPro faces live in assets/fonts.
+// Emoji come from the color fonts Roblox ships next to the mapped faces.
 struct RobloxTextFontSelection {
  std::string primary_file;
+  std::vector<std::string> emoji_files;
  float size_scale = 0.795F;
  bool exact_mapping = false;
 };
@@ -8,6 +8,7 @@
 #include "mocktail/status.h"
 #include "runtime/roblox_input_native_adapter.h"
 #include "runtime/roblox_text_surface_overlay.h"
+#include "runtime/roblox_xr_controller_input.h"

 namespace mocktail {
 namespace runtime {
@@ -35,20 +36,40 @@ class RobloxWindowInputRuntime final {
  Status QueryCurrentTextBoxInfo(RobloxNativeTextBoxInfoQueryResult* result);
  Status UpdateTextFocusProperties(uint64_t generation,
                                   const RobloxTextFocusProperties& properties);
+  // Feeds a synthetic platform event through the same authoritative router as
+  // real SDL events. Used by the XR controller delivery path so tracked
+  // controllers reuse the verified gamepad route (single event source, router
+  // deduplication and focus gating) instead of a second JNI input path.
+  void InjectPlatformEvent(const platform::PlatformEvent& event);
  RobloxInputSnapshot Snapshot() const;
  void SetRawMouseEnabled(bool enabled);

+  // Drains one batch of XR tracked-controller input into the same router.
+  // Called once per main-loop iteration on the input thread; inert in non-VR
+  // builds or while no OpenXR controller layer is active.
+  void DrainXrControllers();
+  // Routes an engine/experience vibration request to the active XR hand.
+  void RequestXrControllerHaptics(int hand, float amplitude,
+                                  std::uint64_t duration_ns, float frequency_hz);
+  void StopXrControllerHaptics(int hand);
+
 private:
  static void PlatformEventCallback(void* context,
                                    const platform::PlatformEvent& event);
  static bool MouseLockQueryCallback(void* context, bool* locked_center);
  static void GamepadEventCallback(void* context,
                                   const platform::PlatformEvent& event);
+  static void XrControllerEventCallback(void* context,
+                                        const platform::PlatformEvent& event);

  RobloxTextSurfaceOverlay text_surface_overlay_;
  std::unique_ptr<platform::TextClipboard> text_clipboard_;
  RobloxInputRuntime runtime_;
  platform::SdlGamepadManager gamepads_;
+  // XR tracked-controller producer. Feeds the same runtime_ router as SDL so
+  // there is exactly one authoritative input route.
+  RobloxXrControllerInput xr_controllers_;
+  bool xr_controllers_initialized_ = false;
  bool observer_registered_ = false;
  bool mouse_lock_query_registered_ = false;
  bool initialized_ = false;
@@ -0,0 +1,100 @@
+#ifndef MOCKTAIL_RUNTIME_ROBLOX_XR_CONTROLLER_INPUT_H_
+#define MOCKTAIL_RUNTIME_ROBLOX_XR_CONTROLLER_INPUT_H_
+
+#include <cstdint>
+
+#include "mocktail/platform/platform_runtime.h"
+#include "mocktail/status.h"
+#include "mocktail/vr/xr_controller_abi.h"
+
+namespace mocktail {
+namespace runtime {
+
+// Delivers OpenXR tracked-controller input through the one authoritative
+// Roblox input route (RobloxInputRouter::HandleEvent), the same verified path
+// physical SDL gamepads use. Because both sources converge on that single
+// route, the router's own level deduplication, focus gating and
+// release-on-disconnect logic apply unchanged and an XR controller can never
+// double-fire alongside a physical gamepad.
+//
+// Both hands are merged into ONE synthetic gamepad: the left hand supplies
+// LEFTX/LEFTY, the left shoulder (squeeze) and left stick click plus X/Y, the
+// right hand supplies RIGHTX/RIGHTY, the right shoulder, right stick click and
+// A/B. That matches how Roblox reads VR controller buttons through
+// GamepadService, and it means the guest sees a single normal controller
+// rather than two competing devices.
+//
+// The XR backend is resolved through dlsym so this module links and runs in
+// non-VR builds and while no OpenXR backend is armed; then every drain is a
+// no-op. No OpenXR headers are required here.
+class RobloxXrControllerInput final {
+public:
+  using EventSink = void (*)(void *context,
+                             const platform::PlatformEvent &event);
+
+  // Synthetic device identity. Deliberately far outside the SDL joystick id
+  // range so it can never collide with a physical controller.
+  static constexpr std::int64_t kInstanceLeft =
+      static_cast<std::int64_t>(0x7FFFFFFFFFFFFFF0LL);
+
+  RobloxXrControllerInput() = default;
+  ~RobloxXrControllerInput() = default;
+  RobloxXrControllerInput(const RobloxXrControllerInput &) = delete;
+  RobloxXrControllerInput &operator=(const RobloxXrControllerInput &) = delete;
+
+  // Resolves the XR controller ABI. Returns false (and stays inert) when the
+  // symbols are absent, which is the normal non-VR or no-backend case; that is
+  // not an error condition.
+  bool Initialize(EventSink sink, void *context);
+  // Test/injection seam: binds explicit ABI function pointers instead of
+  // resolving them through dlsym. A null pop makes the module inert, matching
+  // the non-VR case. Production callers use Initialize().
+  bool InitializeWithAbi(EventSink sink, void *context,
+                         MocktailVrControllerPopFn pop,
+                         MocktailVrControllerHapticsFn haptics,
+                         MocktailVrControllerStopHapticsFn stop_haptics);
+  void Shutdown();
+  bool active() const { return pop_ != nullptr; }
+
+  // Drains every queued delivery and forwards it as platform events. Call once
+  // per main-loop iteration, after window::PumpEvents(), on the same thread
+  // that delivers SDL input. Bounded: drains at most kMaxDrainPerPump batches.
+  void Drain();
+  void ResendState() { force_resync_ = true; }
+
+  // Forwards a vibration request to the XR hand output. hand: 0 left, 1 right.
+  // No-op when the XR layer is inactive. amplitude is clamped by the backend.
+  void RequestHaptics(int hand, float amplitude, std::uint64_t duration_ns,
+                      float frequency_hz);
+  void StopHaptics(int hand);
+
+  // Last observed state, for diagnostics/tests.
+  bool connected() const { return connected_; }
+  std::uint64_t delivered_events() const { return delivered_events_; }
+  std::uint64_t resyncs() const { return resyncs_; }
+
+private:
+  static constexpr int kMaxDrainPerPump = 4;
+  void EmitConnection(bool connected);
+  void EmitButton(int sdl_button, bool pressed);
+  void EmitAxis(int sdl_axis, std::int16_t value);
+
+  void *context_ = nullptr;
+  EventSink sink_ = nullptr;
+  void *pop_ = nullptr;
+  void *haptics_ = nullptr;
+  void *stop_haptics_ = nullptr;
+  bool force_resync_ = false;
+  std::uint64_t generation_ = 0;
+  bool connected_ = false;
+  bool initialized_ = false;
+  std::uint64_t delivered_events_ = 0;
+  std::uint64_t resyncs_ = 0;
+  // Last delivered button levels, for resync and to avoid redundant events.
+  bool last_buttons_[16] = {};
+};
+
+} // namespace runtime
+} // namespace mocktail
+
+#endif // MOCKTAIL_RUNTIME_ROBLOX_XR_CONTROLLER_INPUT_H_
@@ -16,6 +16,15 @@
 namespace mocktail {
 namespace runtime {

+// VR is opt-in in every build (--vr or vr.enabled: true). A VR-capable build
+// must not try to reach an OpenXR runtime on a normal desktop launch.
+inline constexpr bool kDefaultVrEnabled = false;
+
+// vr.mode: on and off force VR or the desktop. auto starts in VR only when
+// SteamVR is running with a headset, which main() checks before launch.
+enum class VrMode { kOff, kOn, kAuto };
+const char* VrModeName(VrMode mode);
+
 enum class GraphicsBackend {
  kAuto,
  kSystem,
@@ -96,6 +105,10 @@ class RuntimeConfig {
  static RuntimeConfig FromEnvironment(const Environment& environment);

  bool headless() const { return headless_; }
+  bool vr_enabled() const { return vr_enabled_; }
+  // MOCKTAIL_VR_ENABLED (--vr, --no-vr) wins over MOCKTAIL_VR_MODE.
+  VrMode vr_mode() const { return vr_mode_; }
+  bool vr_valid() const { return vr_valid_; }
  const std::filesystem::path& roblox_library_path() const {
    return roblox_library_path_;
  }
@@ -121,6 +134,15 @@ class RuntimeConfig {
    return roblox_http_user_agent_;
  }
  const FrameRatePolicy& frame_rate() const { return frame_rate_; }
+  // Replaces frame_rate() while VR is enabled. Defaults to unlimited so the
+  // OpenXR runtime's xrWaitFrame paces Roblox at the headset refresh rate.
+  const FrameRatePolicy& vr_frame_rate() const { return vr_frame_rate_; }
+  // vr.anti_aliasing: fxaa, smaa or off. The VR backend reads it from the
+  // exported MOCKTAIL_VR_ANTI_ALIASING.
+  const std::string& vr_anti_aliasing() const { return vr_anti_aliasing_; }
+  const FrameRatePolicy& active_frame_rate() const {
+    return vr_enabled_ ? vr_frame_rate_ : frame_rate_;
+  }
  const std::string& vsync_mode() const { return vsync_mode_; }
  const PerformancePolicy& performance() const { return performance_; }
  const std::string& audio_output_device() const {
@@ -161,6 +183,9 @@ class RuntimeConfig {

 private:
  bool headless_ = false;
+  bool vr_enabled_ = kDefaultVrEnabled;
+  VrMode vr_mode_ = kDefaultVrEnabled ? VrMode::kOn : VrMode::kOff;
+  bool vr_valid_ = true;
  std::filesystem::path roblox_library_path_ = "rbx_bin/libroblox.so";
  GraphicsBackend graphics_backend_ = GraphicsBackend::kVulkan;
  std::string graphics_backend_name_ = "direct-vulkan";
@@ -171,6 +196,8 @@ class RuntimeConfig {
  bool device_profile_valid_ = true;
  std::optional<std::string> roblox_http_user_agent_;
  FrameRatePolicy frame_rate_;
+  FrameRatePolicy vr_frame_rate_{FrameRateLimitMode::kUnlimited, 0};
+  std::string vr_anti_aliasing_ = "fxaa";
  std::string vsync_mode_ = "auto";
  PerformancePolicy performance_;
  std::string audio_output_device_ = "default";
@@ -67,6 +67,9 @@ class RuntimePaths {
    return active_payload_manifest_;
  }
  const std::filesystem::path& cookie_file() const { return cookie_file_; }
+  const std::filesystem::path& asset_overlay_dir() const {
+    return asset_overlay_dir_;
+  }
  bool use_real_sober_paths() const { return use_real_sober_paths_; }

  std::filesystem::path DefaultAssetPath() const;
@@ -99,6 +102,7 @@ class RuntimePaths {
  std::filesystem::path config_file_;
  std::filesystem::path active_payload_manifest_;
  std::filesystem::path cookie_file_;
+  std::filesystem::path asset_overlay_dir_;
  bool use_real_sober_paths_ = false;
 };

@@ -1,7 +1,7 @@
 # Maintainer: vii <coderdayton14@gmail.com>

 pkgname=nightcap
-pkgver=0.3.1
+pkgver=0.3.4
 pkgrel=1
 pkgdesc='Android x86-64 Roblox compatibility runtime for Linux'
 arch=('x86_64')
@@ -1,6 +1,6 @@
 pkgbase = nightcap-bin
 	pkgdesc = Android x86-64 Roblox compatibility runtime for Linux (prebuilt)
-	pkgver = 0.3.1
+	pkgver = 0.3.4
 	pkgrel = 1
 	url = https://github.com/CoderDayton/nightcap
 	arch = x86_64
@@ -34,10 +34,10 @@ pkgbase = nightcap-bin
 	conflicts = mocktail
 	conflicts = nightcap
 	conflicts = nightcap-git
-	noextract = nightcap-0.3.1-1-x86_64.pkg.tar.zst
+	noextract = nightcap-0.3.4-1-x86_64.pkg.tar.zst
 	options = !debug
 	options = !strip
-	source = nightcap-0.3.1-1-x86_64.pkg.tar.zst::https://github.com/CoderDayton/nightcap/releases/download/v0.3.1/nightcap-0.3.1-1-x86_64.pkg.tar.zst
+	source = nightcap-0.3.4-1-x86_64.pkg.tar.zst::https://github.com/CoderDayton/nightcap/releases/download/v0.3.4/nightcap-0.3.4-1-x86_64.pkg.tar.zst
 	sha256sums = SKIP

 pkgname = nightcap-bin
@@ -1,7 +1,7 @@
 # Maintainer: vii <coderdayton14 at gmail dot com>

 pkgname=nightcap-bin
-pkgver=0.3.1
+pkgver=0.3.4
 pkgrel=1
 pkgdesc='Android x86-64 Roblox compatibility runtime for Linux (prebuilt)'
 arch=('x86_64')
@@ -1,6 +1,6 @@
 pkgbase = nightcap
 	pkgdesc = Android x86-64 Roblox compatibility runtime for Linux
-	pkgver = 0.3.1
+	pkgver = 0.3.4
 	pkgrel = 1
 	url = https://github.com/CoderDayton/nightcap
 	arch = x86_64
@@ -42,7 +42,7 @@ pkgbase = nightcap
 	conflicts = nightcap-git
 	options = !debug
 	options = !lto
-	source = nightcap::git+https://github.com/CoderDayton/nightcap.git#tag=v0.3.1
+	source = nightcap::git+https://github.com/CoderDayton/nightcap.git#tag=v0.3.4
 	sha256sums = SKIP

 pkgname = nightcap
@@ -1,7 +1,7 @@
 # Maintainer: vii <coderdayton14 at gmail dot com>

 pkgname=nightcap
-pkgver=0.3.1
+pkgver=0.3.4
 pkgrel=1
 pkgdesc='Android x86-64 Roblox compatibility runtime for Linux'
 arch=('x86_64')
@@ -28,16 +28,12 @@
  </description>
  <screenshots>
    <screenshot type="default">
-      <image>https://raw.githubusercontent.com/komaruworld/mocktail/88b7382577aa138a2d16619b091f69abcdf7da15/assets/screenshots/flatpak-home.png</image>
+      <image>https://raw.githubusercontent.com/CoderDayton/nightcap/main/assets/screenshots/flatpak-home.png</image>
      <caption>Browse Roblox experiences</caption>
    </screenshot>
    <screenshot>
-      <image>https://raw.githubusercontent.com/komaruworld/mocktail/88b7382577aa138a2d16619b091f69abcdf7da15/assets/screenshots/flatpak-gameplay-tower.png</image>
-      <caption>Play Tower of Hell on Linux</caption>
-    </screenshot>
-    <screenshot>
-      <image>https://raw.githubusercontent.com/komaruworld/mocktail/88b7382577aa138a2d16619b091f69abcdf7da15/assets/screenshots/flatpak-gameplay-lobby.png</image>
-      <caption>Play DOORS on Linux</caption>
+      <image>https://raw.githubusercontent.com/CoderDayton/nightcap/main/assets/screenshots/flatpak-gameplay-tower.png</image>
+      <caption>Play Murder Mystery 2 on Linux</caption>
    </screenshot>
  </screenshots>
  <launchable type="desktop-id">io.github.CoderDayton.nightcap.desktop</launchable>
@@ -62,7 +62,7 @@ Branch=stable
 Url=${BASE_URL}/repo/
 RuntimeRepo=https://dl.flathub.org/repo/flathub.flatpakrepo
 Homepage=https://github.com/CoderDayton/nightcap
-Comment=Roblox on Linux, tuned for a real PC
+Comment=Roblox on Linux, tuned for desktop play
 Icon=${BASE_URL}/nightcap.svg
 GPGKey=${GPG_KEY}
 IsRuntime=false
@@ -72,3 +72,20 @@ install -m 0644 -- "${PROJECT_DIR}/site/index.html" "${OUTPUT}/index.html"
 install -m 0644 -- "${PROJECT_DIR}/site/styles.css" "${OUTPUT}/styles.css"
 install -m 0644 -- "${PROJECT_DIR}/site/terms.html" "${OUTPUT}/terms.html"
 install -m 0644 -- "${PROJECT_DIR}/site/privacy.html" "${OUTPUT}/privacy.html"
+install -m 0644 -- "${PROJECT_DIR}/site/preview.png" "${OUTPUT}/preview.png"
+
+cat >"${OUTPUT}/robots.txt" <<EOF
+User-agent: *
+Allow: /
+
+Sitemap: ${BASE_URL}/sitemap.xml
+EOF
+
+cat >"${OUTPUT}/sitemap.xml" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>${BASE_URL}/</loc></url>
+  <url><loc>${BASE_URL}/terms.html</loc></url>
+  <url><loc>${BASE_URL}/privacy.html</loc></url>
+</urlset>
+EOF
@@ -1356,6 +1356,35 @@ def has_fmod_device_lists_select_contract(image: ElfImage, rva: int) -> bool:
    )


+FMOD_OUTPUT_FIELDS = frozenset({
+    "vtable_rva",
+    "string_constructor_rva",
+    "count_method_rva",
+    "info_method_rva",
+    "current_method_rva",
+    "select_method_rva",
+})
+FMOD_INPUT_FIELDS = (
+    "input_count_method_rva",
+    "input_info_method_rva",
+    "input_current_method_rva",
+    "input_select_method_rva",
+)
+
+
+def fmod_vtable_slots(layout: int, with_input: bool) -> dict[str, int]:
+    """Vtable slot of each FMOD method field in vtable layout 1 or 2."""
+    slots = {
+        "count_method_rva": 5,
+        "info_method_rva": 6,
+        "current_method_rva": 8 if layout == 2 else 7,
+        "select_method_rva": 19 if layout == 2 else 17,
+    }
+    if with_input:
+        slots.update(zip(FMOD_INPUT_FIELDS, (9, 10, 12, 18) if layout == 2 else (8, 9, 10, 16)))
+    return slots
+
+
 def load_reference_runtime_profile(
    paths: Sequence[Path], reference_build_id: str
 ) -> dict[str, Any]:
@@ -1381,21 +1410,11 @@ def load_reference_runtime_profile(
                )
            if "fmod_output_device_bridge" in profile:
                bridge = profile["fmod_output_device_bridge"]
-                fields = {
-                    "vtable_rva",
-                    "string_constructor_rva",
-                    "count_method_rva",
-                    "info_method_rva",
-                    "current_method_rva",
-                    "select_method_rva",
-                }
                if (
                    not isinstance(bridge, dict)
-                    or not fields <= set(bridge)
-                    or set(bridge) - fields - {"vtable_layout_version"} - {
-                        "input_count_method_rva", "input_info_method_rva",
-                        "input_current_method_rva", "input_select_method_rva",
-                    }
+                    or not FMOD_OUTPUT_FIELDS <= set(bridge)
+                    or set(bridge) - FMOD_OUTPUT_FIELDS - {"vtable_layout_version"}
+                    - set(FMOD_INPUT_FIELDS)
                    or profile.get("allow_host_abi_bridges") is not True
                ):
                    raise AnalyzerError(
@@ -1415,10 +1434,7 @@ def load_reference_runtime_profile(
                if field in result:
                    previous = result[field]
                    if field == "fmod_output_device_bridge":
-                        input_fields = {
-                            "input_count_method_rva", "input_info_method_rva",
-                            "input_current_method_rva", "input_select_method_rva",
-                        }
+                        input_fields = set(FMOD_INPUT_FIELDS)
                        compatible = ((set(previous) ^ set(value)) <= input_fields and
                            all(previous[key] == value[key]
                                for key in previous.keys() & value.keys()))
@@ -1440,12 +1456,7 @@ def derive_fmod_output_device_bridge(
    source: dict[str, int],
 ) -> dict[str, Any]:
    source_layout = source.get("vtable_layout_version", 1)
-    indexes = {
-        "count_method_rva": 5,
-        "info_method_rva": 6,
-        "current_method_rva": 8 if source_layout == 2 else 7,
-        "select_method_rva": 19 if source_layout == 2 else 17,
-    }
+    indexes = fmod_vtable_slots(source_layout, False)
    source_vtable = source["vtable_rva"]
    reference.require_relro_rva(source_vtable, (max(indexes.values()) + 1) * 8)
    reference_relocations = relative_relocation_map(reference)
@@ -1530,7 +1541,10 @@ def derive_fmod_output_device_bridge(
            continue
        vtable = offset - indexes["info_method_rva"] * 8
        count_method = relocations.get(vtable + indexes["count_method_rva"] * 8)
-        for layout, current_index, select_index in ((1, 7, 17), (2, 8, 19)):
+        for layout in (1, 2):
+            layout_slots = fmod_vtable_slots(layout, False)
+            current_index = layout_slots["current_method_rva"]
+            select_index = layout_slots["select_method_rva"]
            current_method = relocations.get(vtable + current_index * 8)
            selected = relocations.get(vtable + select_index * 8)
            if (
@@ -1568,18 +1582,13 @@ def derive_fmod_output_device_bridge(
    }
    if layout != 1:
        result["vtable_layout_version"] = layout
-    input_fields = (
-        "input_count_method_rva", "input_info_method_rva",
-        "input_current_method_rva", "input_select_method_rva",
-    )
-    if any(field in source for field in input_fields):
-        if not all(field in source for field in input_fields):
+    if any(field in source for field in FMOD_INPUT_FIELDS):
+        if not all(field in source for field in FMOD_INPUT_FIELDS):
            raise AnalyzerError("reference FMOD input profile is incomplete")
-        source_slots = (9, 10, 12, 18) if source_layout == 2 else (8, 9, 10, 16)
-        target_slots = (9, 10, 12, 18) if layout == 2 else (8, 9, 10, 16)
-        for field, old_slot, new_slot, length in zip(
-            input_fields, source_slots, target_slots, (4, 16, 12, 16)
-        ):
+        source_slots = fmod_vtable_slots(source_layout, True)
+        target_slots = fmod_vtable_slots(layout, True)
+        for field, length in zip(FMOD_INPUT_FIELDS, (4, 16, 12, 16)):
+            old_slot, new_slot = source_slots[field], target_slots[field]
            if reference_relocations.get(source_vtable + old_slot * 8) != source[field]:
                raise AnalyzerError("reference FMOD input slot changed")
            target = relocations.get(vtable + new_slot * 8)
@@ -2247,12 +2256,12 @@ def remapped_constructor_ranges(
    return validated_ranges(result, "derived constructor ranges", candidate_count)


-def derive_profile(
+def check_derivation_inputs(
    reference: ElfImage,
    candidate: ElfImage,
    reference_sidecar: dict[str, Any],
-) -> tuple[dict[str, Any], dict[str, Any]]:
-    require_capstone()
+) -> tuple[tuple[int, ...], tuple[int, ...]]:
+    """Rejects inputs no derivation may use; returns both init-arrays."""
    if (
        reference.build_id != reference_sidecar["elf_build_id"]
        or reference.sha256 != reference_sidecar["payload_sha256"]
@@ -2270,17 +2279,28 @@ def derive_profile(
            "candidate is missing required JNI exports: "
            + ", ".join(sorted(missing_exports))
        )
-
-    reference_profile = reference_sidecar["profile"]
-    anchors = reference_sidecar["derivation_anchors"]
    reference_init = reference.init_array_relocations()
    candidate_init = candidate.init_array_relocations()
-    if len(reference_init) != reference_profile["init_array_count"]:
+    if len(reference_init) != reference_sidecar["profile"]["init_array_count"]:
        raise AnalyzerError(
            "reference sidecar init-array count differs from ELF metadata"
        )
    if len(candidate_init) < 8:
        raise AnalyzerError("candidate init-array is unexpectedly short")
+    return reference_init, candidate_init
+
+
+def derive_profile(
+    reference: ElfImage,
+    candidate: ElfImage,
+    reference_sidecar: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    require_capstone()
+    reference_init, candidate_init = check_derivation_inputs(
+        reference, candidate, reference_sidecar
+    )
+    reference_profile = reference_sidecar["profile"]
+    anchors = reference_sidecar["derivation_anchors"]
    matches = {}
    allocate_matches = ()
    for spec in create_signature_specs(reference_profile, anchors):
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Regenerate src/vr/vr_shaders_spirv.h from shaders/vr with glslc.
+
+The header is checked in so a build never needs a shader compiler. The SMAA
+passes include SMAA.hlsl from the third_party/smaa submodule. Run this
+after editing a shader; VrShaders.SpirvMatchesSources checks it when glslc is
+installed.
+"""
+
+import argparse
+import pathlib
+import struct
+import subprocess
+import sys
+import tempfile
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+SHADERS = [
+    ("kFullscreenVertexSpirv", "shaders/vr/fullscreen.vert"),
+    ("kFxaaFragmentSpirv", "shaders/vr/fxaa.frag"),
+    ("kSmaaEdgesVertexSpirv", "shaders/vr/smaa_edges.vert"),
+    ("kSmaaEdgesFragmentSpirv", "shaders/vr/smaa_edges.frag"),
+    ("kSmaaWeightsVertexSpirv", "shaders/vr/smaa_weights.vert"),
+    ("kSmaaWeightsFragmentSpirv", "shaders/vr/smaa_weights.frag"),
+    ("kSmaaBlendVertexSpirv", "shaders/vr/smaa_blend.vert"),
+    ("kSmaaBlendFragmentSpirv", "shaders/vr/smaa_blend.frag"),
+]
+# SMAA.hlsl comes from the third_party/smaa submodule.
+INCLUDES = [ROOT / "third_party/smaa"]
+OUTPUT = ROOT / "src/vr/vr_shaders_spirv.h"
+
+
+def compile_words(glslc, source):
+    with tempfile.TemporaryDirectory() as directory:
+        output = pathlib.Path(directory) / "shader.spv"
+        subprocess.run(
+            [glslc, "-O", "--target-env=vulkan1.0"] +
+            ["-I" + str(path) for path in INCLUDES] +
+            [str(ROOT / source), "-o", str(output)],
+            check=True)
+        data = output.read_bytes()
+    return struct.unpack("<%dI" % (len(data) // 4), data)
+
+
+def render(glslc):
+    lines = [
+        "// Generated by scripts/generate_vr_shaders.py from shaders/vr. Do not edit.",
+        "#ifndef MOCKTAIL_VR_VR_SHADERS_SPIRV_H_",
+        "#define MOCKTAIL_VR_VR_SHADERS_SPIRV_H_",
+        "",
+        "#include <cstdint>",
+        "",
+        "namespace mocktail::vr {",
+        "",
+    ]
+    for name, source in SHADERS:
+        words = compile_words(glslc, source)
+        lines.append("// %s" % source)
+        lines.append("inline constexpr std::uint32_t %s[] = {" % name)
+        for start in range(0, len(words), 6):
+            chunk = ", ".join("0x%08x" % word for word in words[start:start + 6])
+            lines.append("    %s," % chunk)
+        lines.append("};")
+        lines.append("")
+    lines += ["}  // namespace mocktail::vr", "",
+              "#endif  // MOCKTAIL_VR_VR_SHADERS_SPIRV_H_", ""]
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--glslc", default="glslc")
+    parser.add_argument("--check", action="store_true",
+                        help="exit 1 when the header is out of date")
+    arguments = parser.parse_args()
+    text = render(arguments.glslc)
+    if arguments.check:
+        current = OUTPUT.read_text() if OUTPUT.exists() else ""
+        if current != text:
+            print("%s is out of date; run %s" % (OUTPUT, __file__),
+                  file=sys.stderr)
+            return 1
+        return 0
+    OUTPUT.write_text(text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+# Copyright 2026 Mocktail Project Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Run the HostAbi deriver and the solver on one update and compare them.
+
+Usage:
+    python3 roblox_abi_check.py --reference-lib OLD.so \\
+        --reference-profile OLD_PROFILE.json \\
+        --reference-compatibility config/roblox_compatibility.json \\
+        --candidate-lib NEW.so
+
+Prints every field where the two disagree. Exit status: 0 agree, 1 differ or
+one side failed, 2 both failed.
+
+With --vr, the VR device bridge is compared too. `find_roblox_vr_offsets.py`
+finds it in each build on its own: its answer for the reference build is the
+solver's input, and its answer for the candidate joins the deriver's side.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+from pathlib import Path
+import sys
+from typing import Any, Sequence
+
+
+def _load_sibling(name: str, file_name: str):
+    if name in sys.modules:
+        return sys.modules[name]
+    path = Path(__file__).resolve().with_name(file_name)
+    specification = importlib.util.spec_from_file_location(name, path)
+    if specification is None or specification.loader is None:
+        raise RuntimeError(f"cannot load {file_name}")
+    module = importlib.util.module_from_spec(specification)
+    sys.modules[name] = module
+    specification.loader.exec_module(module)
+    return module
+
+
+SOLVER = _load_sibling("mocktail_roblox_abi_solver", "roblox_abi_solver.py")
+FINDER = _load_sibling("mocktail_find_roblox_vr_offsets", "find_roblox_vr_offsets.py")
+DERIVER = SOLVER.DERIVER
+AnalyzerError = SOLVER.AnalyzerError
+format_rva = SOLVER.format_rva
+
+# Where find_roblox_vr_offsets.py reports each VR bridge field.
+_FINDER_FIELDS = {
+    "vtable_rva": ("vr_debug_device_bridge", "vtable_rva"),
+    "constructor_rva": ("vr_debug_device_bridge", "constructor_rva"),
+    "state_getter_rva": ("vr_debug_device_bridge", "state_getter_rva"),
+    "eye_getter_rva": ("vr_debug_device_bridge", "eye_getter_rva"),
+    "eye_initializer_rva": ("vr_debug_device_bridge", "eye_initializer_rva"),
+    "emulator_flag_storage_rva": ("vr_debug_device_bridge", "emulator_flag_storage_rva"),
+    "device_create_framebuffer_vtable_offset": (
+        "vr_debug_device_bridge", "device_create_framebuffer_vtable_offset"
+    ),
+    "state_memcpy_rva": ("vr_bridge_supplement", "state_getter_memcpy_rva"),
+    "pointer_frame_rva": ("vr_bridge_supplement", "world_pointer_getter_rva"),
+    "workspace_getter_rva": ("vr_bridge_supplement", "workspace_getter_rva"),
+    "camera_vtable_offset": ("vr_bridge_supplement", "workspace_camera_vtable_offset"),
+    "hand_pitch_storage_rva": ("vr_bridge_supplement", "new_vr_system_hand_pitch_storage_rva"),
+    "haptic_sink_rva": ("vr_bridge_supplement", "haptic_sink_rva"),
+    "pointer_hand_selector_offset": ("vr_bridge_supplement", "usercframe_selector_offset"),
+    "camera_head_scale_offset": ("vr_bridge_supplement", "camera_head_scale_offset"),
+    "keep_haptics_flag_rva": ("vr_bridge_supplement", "keep_haptics_flag_rva"),
+    "vr_haptics_flag_rva": ("vr_bridge_supplement", "vr_haptics_flag_rva"),
+    "support_generic_haptics_flag_rva": (
+        "vr_bridge_supplement", "support_generic_haptics_flag_rva"
+    ),
+    "fix_register_motors_flag_rva": ("vr_bridge_supplement", "fix_register_motors_flag_rva"),
+}
+
+
+def vr_bridge_from_finder(
+    result: dict[str, Any], fields: Sequence[str] = SOLVER.VR.VR_FIELDS
+) -> dict[str, str]:
+    """The VR bridge fields from a find_roblox_vr_offsets.py result."""
+    bridge = {}
+    for field in fields:
+        section, key = _FINDER_FIELDS[field]
+        try:
+            bridge[field] = result[section][key]
+        except (KeyError, TypeError) as error:
+            raise AnalyzerError(f"VR offset finder result lacks {key}") from error
+    return bridge
+
+
+def _find_vr_bridge(library: Path) -> dict[str, str]:
+    try:
+        return vr_bridge_from_finder(FINDER.find_vr_offsets(library))
+    except FINDER.AnalyzerError as error:
+        raise AnalyzerError(f"VR offset finder: {error}") from error
+
+
+def compare_results(derived: Any, solved: Any, path: str = "") -> list[str]:
+    """Returns one line for every leaf value where the two results differ."""
+    if isinstance(derived, dict) and isinstance(solved, dict):
+        lines = []
+        for key in sorted(derived.keys() | solved.keys(), key=str):
+            child = f"{path}.{key}" if path else str(key)
+            if key not in solved:
+                lines.append(f"{child}: deriver {derived[key]}, solver missing")
+            elif key not in derived:
+                lines.append(f"{child}: deriver missing, solver {solved[key]}")
+            else:
+                lines.extend(compare_results(derived[key], solved[key], child))
+        return lines
+    if isinstance(derived, list) and isinstance(solved, list) and len(derived) == len(solved):
+        return [
+            line
+            for index, (left, right) in enumerate(zip(derived, solved))
+            for line in compare_results(left, right, f"{path}[{index}]")
+        ]
+    return [] if derived == solved else [f"{path}: deriver {derived}, solver {solved}"]
+
+
+def check_status(
+    derived: Any, solved: Any, deriver_error: str | None, solver_error: str | None
+) -> tuple[int, list[str]]:
+    """Exit status and report lines: 0 agree, 1 differ or one failed, 2 both failed."""
+    lines = []
+    if deriver_error is not None:
+        lines.append(f"deriver failed: {deriver_error}")
+    if solver_error is not None:
+        lines.append(f"solver failed: {solver_error}")
+    if deriver_error is not None and solver_error is not None:
+        return 2, lines
+    if deriver_error is not None or solver_error is not None:
+        return 1, lines
+    differences = compare_results(derived, solved)
+    if differences:
+        return 1, differences
+    return 0, ["deriver and solver agree on every field"]
+
+
+def _solver_runtime_source(source: dict[str, Any]) -> dict[str, Any]:
+    # The deriver's loader returns integers; the solver reads hex strings.
+    result: dict[str, Any] = {}
+    for key, value in source.items():
+        if isinstance(value, dict):
+            result[key] = {
+                field: item if field == "vtable_layout_version" else format_rva(item)
+                for field, item in value.items()
+            }
+        else:
+            result[key] = format_rva(value)
+    return result
+
+
+def _describe(error: Exception) -> str:
+    if isinstance(error, AnalyzerError):
+        return str(error)
+    return f"{type(error).__name__}: {error}"
+
+
+def check(arguments: argparse.Namespace) -> int:
+    """Runs the deriver and the solver on one update and compares them."""
+    sidecar = DERIVER.validated_sidecar(Path(arguments.reference_profile))
+    manifests = [Path(path) for path in arguments.reference_compatibility]
+    cache_dir = Path(arguments.cache_dir) if arguments.cache_dir else None
+    derived = solved = deriver_error = solver_error = None
+    reference_vr = _find_vr_bridge(Path(arguments.reference_lib)) if arguments.vr else None
+    with DERIVER.ElfImage(Path(arguments.reference_lib)) as reference, DERIVER.ElfImage(
+        Path(arguments.candidate_lib)
+    ) as candidate:
+        try:
+            profile, anchors = DERIVER.derive_profile(reference, candidate, sidecar)
+            runtime = DERIVER.derive_runtime_compatibility(reference, candidate, manifests)
+            derived = {"profile": profile, "derivation_anchors": anchors, "runtime": runtime}
+            if reference_vr is not None:
+                derived["vr_device_bridge"] = _find_vr_bridge(Path(arguments.candidate_lib))
+        except Exception as error:
+            deriver_error = _describe(error)
+        try:
+            # The input checks are cheap; indexing both libraries is not.
+            SOLVER.check_inputs(reference, candidate, sidecar)
+            solver = SOLVER.Solver(reference, candidate, cache_dir)
+            profile, anchors = solver.derive_profile(sidecar)
+            source = DERIVER.load_reference_runtime_profile(manifests, reference.build_id)
+            runtime = solver.derive_runtime_compatibility(_solver_runtime_source(source))
+            solved = {"profile": profile, "derivation_anchors": anchors, "runtime": runtime}
+            if reference_vr is not None:
+                solved["vr_device_bridge"] = solver.derive_vr(reference_vr)
+        except Exception as error:
+            solver_error = _describe(error)
+    status, lines = check_status(derived, solved, deriver_error, solver_error)
+    for line in lines:
+        print(line)
+    return status
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Run the HostAbi deriver and the solver on one update and compare them"
+    )
+    parser.add_argument("--reference-lib", required=True, metavar="REF")
+    parser.add_argument("--reference-profile", required=True, metavar="REFJSON")
+    parser.add_argument(
+        "--reference-compatibility", action="append", default=[], metavar="MANIFEST"
+    )
+    parser.add_argument("--candidate-lib", required=True, metavar="LIB")
+    parser.add_argument(
+        "--cache-dir",
+        default=str(Path.home() / ".cache" / "mocktail" / "function_index"),
+        help="where function indexes are kept; empty to disable",
+    )
+    parser.add_argument(
+        "--vr", action="store_true", help="also compare the VR device bridge"
+    )
+    arguments = parser.parse_args(sys.argv[1:] if argv is None else argv)
+    try:
+        return check(arguments)
+    except AnalyzerError as error:
+        print(f"roblox-abi-check: error: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,402 @@
+#!/usr/bin/env python3
+# Copyright 2026 Mocktail Project Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Evidence-scoring solver that finds HostAbi addresses in a new libroblox.
+
+Each function in both builds is indexed by `roblox_function_index.py`. A
+reference function is matched through independent clues:
+
+- the same instruction shape, unique in both builds
+- callers and callees that are already matched
+- the strings it references
+- its data references, shifted by the distance mapped for those addresses
+- its place between matched neighbours
+
+A match is accepted only with a score of at least ACCEPT_SCORE and a lead of
+at least ACCEPT_LEAD over the runner-up. `roblox_abi_targets.py` turns the
+matches into a profile with the same shape as the one
+`derive_roblox_host_abi_profile.py` writes, `roblox_abi_vr.py` into the VR
+device bridge, and `roblox_abi_check.py` compares the two on one update.
+"""
+
+from __future__ import annotations
+
+import bisect
+import collections
+from dataclasses import dataclass
+import difflib
+import importlib.util
+from pathlib import Path
+import sys
+from typing import Any, Callable, Sequence
+
+
+def _load_sibling(name: str, file_name: str):
+    if name in sys.modules:
+        return sys.modules[name]
+    path = Path(__file__).resolve().with_name(file_name)
+    specification = importlib.util.spec_from_file_location(name, path)
+    if specification is None or specification.loader is None:
+        raise RuntimeError(f"cannot load {file_name}")
+    module = importlib.util.module_from_spec(specification)
+    sys.modules[name] = module
+    specification.loader.exec_module(module)
+    return module
+
+
+INDEX = _load_sibling("mocktail_roblox_function_index", "roblox_function_index.py")
+TARGETS = _load_sibling("mocktail_roblox_abi_targets", "roblox_abi_targets.py")
+VR = _load_sibling("mocktail_roblox_abi_vr", "roblox_abi_vr.py")
+DERIVER = INDEX.DERIVER
+FunctionIndex = INDEX.FunctionIndex
+Instruction = INDEX.Instruction
+AnalyzerError = DERIVER.AnalyzerError
+format_rva = DERIVER.format_rva
+check_inputs = TARGETS.check_inputs
+validate_fmod_source = TARGETS.validate_fmod_source
+
+ACCEPT_SCORE = 0.6
+ACCEPT_LEAD = 0.2
+# Candidates that get the full, disassembling score after the cheap one.
+FULL_SCORE_LIMIT = 64
+# A data address used by more functions than this is too common to narrow
+# the candidates by itself.
+XREF_FANOUT_LIMIT = 64
+# Scores are float sums; a lead that equals ACCEPT_LEAD on paper may be
+# a few ulps short.
+_TOLERANCE = 1e-9
+
+
+def choose_candidate(
+    scored: Sequence[tuple[float, int]], tie_breaker: int | None = None
+) -> int | None:
+    """Returns the leading candidate, or None when no lead is clear.
+
+    `tie_breaker` picks among the candidates that clear ACCEPT_SCORE and sit
+    within ACCEPT_LEAD of the best; it cannot lift or overrule any other.
+    """
+    if not scored:
+        return None
+    ranked = sorted(scored, key=lambda item: item[0], reverse=True)
+    best_score, best = ranked[0]
+    runner_up = ranked[1][0] if len(ranked) > 1 else 0.0
+    if best_score >= ACCEPT_SCORE and best_score - runner_up >= ACCEPT_LEAD - _TOLERANCE:
+        return best
+    tied = {
+        rva for value, rva in ranked
+        if value >= ACCEPT_SCORE and best_score - value < ACCEPT_LEAD - _TOLERANCE
+    }
+    return tie_breaker if tie_breaker in tied else None
+
+
+def align_instructions(
+    reference_shapes: Sequence[str], candidate_shapes: Sequence[str]
+) -> dict[int, int]:
+    """Maps reference instruction indexes to candidate indexes of equal shape."""
+    matcher = difflib.SequenceMatcher(
+        None, reference_shapes, candidate_shapes, autojunk=False
+    )
+    mapping = {}
+    for block in matcher.get_matching_blocks():
+        for offset in range(block.size):
+            mapping[block.a + offset] = block.b + offset
+    return mapping
+
+
+@dataclass(frozen=True)
+class Match:
+    rva: int
+    score: float
+    lead: float
+    # "score" when the score alone decided, "vtable" when a slot broke a tie.
+    decided_by: str
+
+
+def _share(expected: Sequence[Any], present: set[Any]) -> float | None:
+    if not expected:
+        return None
+    return sum(1 for item in expected if item in present) / len(expected)
+
+
+def _weighted(parts: Sequence[tuple[float | None, float]]) -> float:
+    present = [(value, weight) for value, weight in parts if value is not None]
+    return sum(value * weight for value, weight in present) / sum(
+        weight for _, weight in present
+    )
+
+
+class Solver(TARGETS.TargetDerivation, VR.VrTargets):
+    def __init__(self, reference: Any, candidate: Any, cache_dir: Path | None = None):
+        self._start(FunctionIndex(reference, cache_dir), FunctionIndex(candidate, cache_dir))
+
+    @classmethod
+    def from_indexes(cls, reference: Any, candidate: Any) -> "Solver":
+        solver = cls.__new__(cls)
+        solver._start(reference, candidate)
+        return solver
+
+    def _start(self, reference: Any, candidate: Any) -> None:
+        self.reference = reference
+        self.candidate = candidate
+        self.pairs: dict[int, int] = {}
+        self._owners: dict[int, int] = {}
+        for start, other in self._shape_anchors().items():
+            self._pair(start, other)
+        self._propagate_calls()
+        self.data_map = self._map_data_references()
+        self.matches: dict[str, Match] = {}
+        self._claimed: dict[int, int] = {}
+
+    def _pair(self, start: int, other: int) -> None:
+        """Pairs two functions, dropping any pair that held either one."""
+        owner = self._owners.get(other)
+        if owner is not None and owner != start:
+            del self.pairs[owner]
+        previous = self.pairs.get(start)
+        if previous is not None and previous != other:
+            del self._owners[previous]
+        self.pairs[start] = other
+        self._owners[other] = start
+
+    def _shape_anchors(self) -> dict[int, int]:
+        reference_hashes = collections.defaultdict(list)
+        candidate_hashes = collections.defaultdict(list)
+        for start, info in self.reference.functions.items():
+            reference_hashes[info.shape_hash].append(start)
+        for start, info in self.candidate.functions.items():
+            candidate_hashes[info.shape_hash].append(start)
+        pairs = {}
+        for shape_hash, starts in reference_hashes.items():
+            others = candidate_hashes.get(shape_hash, ())
+            if len(starts) == 1 and len(others) == 1:
+                pairs[starts[0]] = others[0]
+        return pairs
+
+    def _propagate_calls(self) -> None:
+        # Matched functions with as many calls pair their callees in order.
+        reference, candidate = self.reference.functions, self.candidate.functions
+        pending = list(self.pairs.items())
+        while pending:
+            discovered = []
+            for reference_start, candidate_start in pending:
+                reference_calls = reference[reference_start].calls
+                candidate_calls = candidate[candidate_start].calls
+                if len(reference_calls) != len(candidate_calls):
+                    continue
+                for callee, other in zip(reference_calls, candidate_calls):
+                    if (
+                        callee in self.pairs
+                        or other in self._owners
+                        or callee not in reference
+                        or other not in candidate
+                    ):
+                        continue
+                    size = reference[callee].size
+                    if abs(size - candidate[other].size) <= max(16, size // 4):
+                        self._pair(callee, other)
+                        discovered.append((callee, other))
+            pending = discovered
+
+    def _map_data_references(self) -> dict[int, int]:
+        votes: dict[int, collections.Counter] = collections.defaultdict(collections.Counter)
+        for reference_start, candidate_start in self.pairs.items():
+            reference_refs = self.reference.functions[reference_start].refs
+            candidate_refs = self.candidate.functions[candidate_start].refs
+            if len(reference_refs) == len(candidate_refs):
+                for reference_target, candidate_target in zip(reference_refs, candidate_refs):
+                    votes[reference_target][candidate_target] += 1
+        return {target: counter.most_common(1)[0][0] for target, counter in votes.items()}
+
+    def _gap_candidates(self, start: int) -> list[int]:
+        starts = self.reference.starts
+        index = bisect.bisect_left(starts, start)
+        below = next(
+            (self.pairs[starts[i]] for i in range(index - 1, -1, -1) if starts[i] in self.pairs),
+            self.candidate.text.address,
+        )
+        above = next(
+            (self.pairs[starts[i]] for i in range(index + 1, len(starts)) if starts[i] in self.pairs),
+            self.candidate.text.address + self.candidate.text.size,
+        )
+        if above <= below:
+            return []
+        low = bisect.bisect_left(self.candidate.starts, below)
+        high = bisect.bisect_right(self.candidate.starts, above)
+        return self.candidate.starts[low:high]
+
+    def _neighbour_candidates(self, start: int) -> set[int]:
+        found = set()
+        for callee in self.reference.functions[start].calls:
+            if callee in self.pairs:
+                found.update(self.candidate.callers.get(self.pairs[callee], ()))
+        for caller in self.reference.callers.get(start, ()):
+            if caller in self.pairs:
+                found.update(
+                    target
+                    for target in self.candidate.functions[self.pairs[caller]].calls
+                    if target in self.candidate.functions
+                )
+        return found
+
+    def _pattern_candidates(self, start: int) -> set[int]:
+        # Data a function touches usually moves as one block, so its
+        # references shifted by a mapped distance find it in the candidate.
+        refs = set(self.reference.functions[start].refs)
+        distances = collections.Counter(
+            self.data_map[target] - target for target in refs if target in self.data_map
+        )
+        # A common address adds a vote but cannot bring in a candidate alone.
+        votes = collections.Counter()
+        found_by_rare = set()
+        for target in refs:
+            users = set()
+            for distance, _ in distances.most_common(3):
+                found = self.candidate.data_users.get(target + distance, ())
+                users.update(found)
+                if len(found) <= XREF_FANOUT_LIMIT:
+                    found_by_rare.update(found)
+            votes.update(users)
+        needed = max(1, len(refs) // 2)
+        return {user for user in found_by_rare if votes[user] >= needed}
+
+    def _graph_score(self, start: int, other: int) -> float:
+        reference = self.reference.functions[start]
+        candidate = self.candidate.functions[other]
+        size = min(reference.size, candidate.size) / max(reference.size, candidate.size)
+        calls = [self.pairs[c] for c in reference.calls if c in self.pairs]
+        callers = [self.pairs[c] for c in self.reference.callers.get(start, ()) if c in self.pairs]
+        data = [self.data_map[t] for t in reference.refs if t in self.data_map]
+        return _weighted(
+            (
+                (size, 1.0),
+                (_share(calls, set(candidate.calls)), 2.0),
+                (_share(callers, set(self.candidate.callers.get(other, ()))), 2.0),
+                (_share(data, set(candidate.refs)), 2.0),
+            )
+        )
+
+    def _full_score(self, start: int, other: int, graph: float) -> float:
+        similarity = difflib.SequenceMatcher(
+            None, self.reference.shapes(start), self.candidate.shapes(other), autojunk=False
+        ).ratio()
+        strings = [
+            text
+            for text in map(self.reference.string_at, self.reference.functions[start].refs)
+            if text is not None
+        ]
+        candidate_strings = set(
+            map(self.candidate.string_at, self.candidate.functions[other].refs)
+        )
+        return _weighted(
+            (
+                (similarity, 3.0),
+                (_share(strings, candidate_strings), 2.0),
+                (graph, 5.0),
+            )
+        )
+
+    def match_function(
+        self,
+        name: str,
+        start: int,
+        contract: Callable[[Any, int], bool] | None = None,
+        vtable_slot: int | None = None,
+    ) -> int:
+        """Matches one reference function.
+
+        A contract drops candidates outright. `vtable_slot` is the candidate
+        that sits in the matching slot of an already located vtable; it only
+        breaks a tie between candidates that pass on their own evidence.
+        """
+        if start not in self.reference.functions:
+            raise AnalyzerError(f"reference {name} is not a function start")
+        if name in self.matches:
+            return self.matches[name].rva
+        candidates = set(self._gap_candidates(start))
+        candidates |= self._neighbour_candidates(start)
+        candidates |= self._pattern_candidates(start)
+        if start in self.pairs:
+            candidates.add(self.pairs[start])
+        if vtable_slot in self.candidate.functions:
+            candidates.add(vtable_slot)
+        size = self.reference.functions[start].size
+        candidates = {
+            other
+            for other in candidates
+            if self._claimed.get(other, start) == start
+            and self.candidate.functions[other].size <= 8 * size + 64
+            and (contract is None or contract(self.candidate.image, other))
+        }
+        graph = {other: self._graph_score(start, other) for other in candidates}
+        shortlist = sorted(candidates, key=graph.__getitem__, reverse=True)[:FULL_SCORE_LIMIT]
+        if vtable_slot in candidates and vtable_slot not in shortlist:
+            shortlist.append(vtable_slot)
+        scored = [(self._full_score(start, other, graph[other]), other) for other in shortlist]
+        chosen = choose_candidate(scored)
+        decided_by = "score"
+        if chosen is None and vtable_slot is not None:
+            chosen = choose_candidate(scored, tie_breaker=vtable_slot)
+            decided_by = "vtable"
+        if chosen is None:
+            ranked = sorted(scored, reverse=True)[:2]
+            raise AnalyzerError(
+                f"{name} has no clear candidate: "
+                + ", ".join(f"{format_rva(rva)}={value:.2f}" for value, rva in ranked)
+            )
+        chosen_score = next(value for value, other in scored if other == chosen)
+        runner_up = max((value for value, other in scored if other != chosen), default=0.0)
+        self.matches[name] = Match(chosen, chosen_score, chosen_score - runner_up, decided_by)
+        self._claimed[chosen] = start
+        self._pair(start, chosen)
+        return chosen
+
+    def _aligned(self, name: str, start: int) -> tuple[list[Instruction], list[Instruction], dict[int, int]]:
+        other = self.match_function(name, start)
+        reference = self.reference.instructions(start)
+        candidate = self.candidate.instructions(other)
+        mapping = align_instructions(
+            [item.shape for item in reference], [item.shape for item in candidate]
+        )
+        return reference, candidate, mapping
+
+    def map_instruction(self, name: str, rva: int) -> int:
+        start = self.reference.containing(rva)
+        if start is None:
+            raise AnalyzerError(f"reference {name} is outside every function")
+        reference, candidate, mapping = self._aligned(f"{name} function", start)
+        index = next((i for i, item in enumerate(reference) if item.address == rva), None)
+        if index is None or index not in mapping:
+            raise AnalyzerError(f"{name} instruction has no counterpart")
+        return candidate[mapping[index]].address
+
+    def map_data(self, name: str, function_name: str, start: int, target: int) -> int:
+        reference, candidate, mapping = self._aligned(function_name, start)
+        found = set()
+        for index, item in enumerate(reference):
+            if target not in item.rip_targets:
+                continue
+            if index not in mapping:
+                raise AnalyzerError(f"{name} reference instruction has no counterpart")
+            other = candidate[mapping[index]]
+            if len(other.rip_targets) != len(item.rip_targets):
+                raise AnalyzerError(f"{name} RIP-relative operand count changed")
+            found.update(
+                other.rip_targets[position]
+                for position, value in enumerate(item.rip_targets)
+                if value == target
+            )
+        if len(found) != 1:
+            raise AnalyzerError(f"{name} has no unique mapped data address")
+        return found.pop()
@@ -0,0 +1,375 @@
+#!/usr/bin/env python3
+# Copyright 2026 Mocktail Project Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""HostAbi targets that `roblox_abi_solver.py` derives from its matches.
+
+`TargetDerivation` turns matched functions into the HostAbi profile, the
+derivation anchors and the runtime compatibility block, in the shape that
+`derive_roblox_host_abi_profile.py` writes. It reuses the deriver's input
+checks, contracts and post-processing.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+import sys
+from typing import Any, Callable
+
+
+def _load_index():
+    name = "mocktail_roblox_function_index"
+    if name in sys.modules:
+        return sys.modules[name]
+    path = Path(__file__).resolve().with_name("roblox_function_index.py")
+    specification = importlib.util.spec_from_file_location(name, path)
+    if specification is None or specification.loader is None:
+        raise RuntimeError("cannot load roblox_function_index.py")
+    module = importlib.util.module_from_spec(specification)
+    sys.modules[name] = module
+    specification.loader.exec_module(module)
+    return module
+
+
+DERIVER = _load_index().DERIVER
+AnalyzerError = DERIVER.AnalyzerError
+format_rva = DERIVER.format_rva
+FMOD_OUTPUT_FIELDS = DERIVER.FMOD_OUTPUT_FIELDS
+FMOD_INPUT_FIELDS = DERIVER.FMOD_INPUT_FIELDS
+fmod_slots = DERIVER.fmod_vtable_slots
+
+
+def check_inputs(reference: Any, candidate: Any, reference_sidecar: dict[str, Any]) -> None:
+    """Applies the deriver's identity and preflight checks to both builds."""
+    DERIVER.check_derivation_inputs(reference, candidate, reference_sidecar)
+
+
+def validate_fmod_source(source: Any) -> int:
+    """Checks a reference FMOD bridge the way the deriver does; returns its layout."""
+    if (
+        not isinstance(source, dict)
+        or not FMOD_OUTPUT_FIELDS <= source.keys()
+        or source.keys() - FMOD_OUTPUT_FIELDS - set(FMOD_INPUT_FIELDS) - {"vtable_layout_version"}
+    ):
+        raise AnalyzerError("reference FMOD output-device profile is incomplete")
+    present = [field for field in FMOD_INPUT_FIELDS if field in source]
+    if present and len(present) != len(FMOD_INPUT_FIELDS):
+        raise AnalyzerError("reference FMOD input profile is incomplete")
+    layout = source.get("vtable_layout_version", 1)
+    if type(layout) is not int or layout not in (1, 2):
+        raise AnalyzerError("reference FMOD vtable layout is unsupported")
+    return layout
+
+
+class TargetDerivation:
+    """Mixin for `Solver`: needs `reference`, `candidate`, `matches`,
+    `match_function`, `map_data` and `map_instruction`."""
+
+    def _check_registry_allocator(
+        self,
+        reference_registry: int,
+        candidate_registry: int,
+        reference_allocate: int,
+        candidate_allocate: int,
+    ) -> None:
+        # The registry initializer's tenth instruction calls the allocator bridge.
+        for index, start, allocate, side in (
+            (self.reference, reference_registry, reference_allocate, "reference"),
+            (self.candidate, candidate_registry, candidate_allocate, "candidate"),
+        ):
+            code = index.instructions(start)
+            if len(code) <= 9 or code[9].shape != "call" or code[9].branch_target != allocate:
+                raise AnalyzerError(
+                    f"{side} registry initializer does not call its allocator bridge"
+                )
+
+    def derive_profile(
+        self, reference_sidecar: dict[str, Any]
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        reference_profile = reference_sidecar["profile"]
+        anchors = reference_sidecar["derivation_anchors"]
+        DERIVER.validate_profile_shape(reference_profile, anchors)
+        reference_image = self.reference.image
+        candidate_image = self.candidate.image
+        check_inputs(reference_image, candidate_image, reference_sidecar)
+        parse = DERIVER.parse_rva
+        bridges = []
+        found = {}
+        for entry in reference_profile["bridge_entries"]:
+            rva = self.match_function(entry["label"], parse(entry["rva"], entry["label"]))
+            found[entry["label"]] = rva
+            bridges.append({"rva": format_rva(rva), "kind": entry["kind"], "label": entry["label"]})
+
+        seeds = reference_profile["data_seeds"]
+        arena_initializer = parse(seeds["arena_initializer"], "arena initializer")
+        thread_initializer = parse(seeds["allocator_thread_initializer"], "thread initializer")
+        self.match_function("arena-initializer", arena_initializer)
+        self.match_function("allocator-thread-initializer", thread_initializer)
+
+        bootstrap = reference_profile["native_pre_jni_bootstrap"]
+        DERIVER.validate_reference_registry_slot(reference_image, bootstrap)
+        registry = self.match_function(
+            "registry-initializer", parse(bootstrap["registry_initializer"], "registry")
+        )
+        reference_allocate = parse(
+            DERIVER.bridge_map(reference_profile)["allocate"]["rva"], "reference allocate"
+        )
+        self._check_registry_allocator(
+            parse(bootstrap["registry_initializer"], "registry"),
+            registry, reference_allocate, found["allocate"],
+        )
+        registry_slot = DERIVER.derive_registry_slot(candidate_image, registry)
+
+        reference_init = reference_image.init_array_relocations()
+        candidate_init = candidate_image.init_array_relocations()
+        begin = DERIVER.LEADING_CONSTRUCTOR_BEGIN
+        count = DERIVER.LEADING_CONSTRUCTOR_COUNT
+        leading = candidate_init[begin : begin + count]
+        offsets = []
+        for index in range(begin, begin + count):
+            expected = parse(anchors["constructor_rvas"][str(index)], f"constructor {index}")
+            if reference_init[index] != expected:
+                raise AnalyzerError(f"reference constructor {index} differs from its anchor")
+            rva = self.match_function(f"constructor-{index}", expected)
+            if leading.count(rva) != 1:
+                raise AnalyzerError(f"constructor {index} left the leading constructors")
+            offsets.append(leading.index(rva))
+        if sorted(offsets) != list(range(count)):
+            raise AnalyzerError("leading constructors do not map one to one")
+
+        singleton = parse(anchors["jni_singleton_initializer_rva"], "JNI singleton")
+        jni_singleton = self.match_function("jni-singleton-initializer", singleton)
+        allocator_anchor = parse(anchors["allocator_object_initializer_rva"], "allocator anchor")
+        empty_anchor = parse(anchors["empty_string_initializer_rva"], "empty string anchor")
+        allocator_function = self.reference.containing(allocator_anchor)
+        empty_function = self.reference.containing(empty_anchor)
+        if allocator_function is None or empty_function is None:
+            raise AnalyzerError("reference anchor is outside every function")
+
+        slots = {
+            "allocator_object_slot": self.map_data(
+                "allocator object slot", "allocator-object-initializer function",
+                allocator_function, parse(seeds["allocator_object_slot"], "allocator slot"),
+            ),
+            "empty_string_slot": self.map_data(
+                "empty string slot", "empty-string-initializer function",
+                empty_function, parse(seeds["empty_string_slot"], "empty string slot"),
+            ),
+            "jni_singleton_slot": self.map_data(
+                "JNI singleton slot", "jni-singleton-initializer",
+                singleton, parse(seeds["jni_singleton_slot"], "JNI singleton slot"),
+            ),
+            "arena_guard_slot": self.map_data(
+                "arena guard slot", "arena-initializer",
+                arena_initializer, parse(seeds["arena_guard_slot"], "arena guard slot"),
+            ),
+            "arena_table_slot": self.map_data(
+                "arena table slot", "usable-size",
+                parse(DERIVER.bridge_map(reference_profile)["usable-size"]["rva"], "usable size"),
+                parse(seeds["arena_table_slot"], "arena table slot"),
+            ),
+        }
+        for slot in slots.values():
+            candidate_image.require_writable_rva(slot, 8)
+
+        candidate_count = len(candidate_init)
+        reference_count = reference_profile["init_array_count"]
+        boundary = reference_profile["native_mimalloc_thread_initializer_after_constructor"]
+        if not begin <= boundary < begin + count:
+            raise AnalyzerError("native allocator TLS boundary is no longer verified")
+        thread_boundary = begin + offsets[boundary - begin]
+        native_ranges = DERIVER.remapped_constructor_ranges(
+            reference_profile["native_mimalloc_constructor_run_ranges"],
+            offsets, reference_count, candidate_count,
+        )
+        if not any(item["begin"] <= thread_boundary < item["end_exclusive"] for item in native_ranges):
+            raise AnalyzerError("native allocator TLS boundary is no longer verified")
+        profile = {
+            "elf_build_id": candidate_image.build_id,
+            "bridge_entries": bridges,
+            "data_seeds": {
+                "allocator_object_slot": format_rva(slots["allocator_object_slot"]),
+                "empty_string_slot": format_rva(slots["empty_string_slot"]),
+                "jni_singleton_slot": format_rva(slots["jni_singleton_slot"]),
+                "jni_singleton_bytes": seeds["jni_singleton_bytes"],
+                "arena_initializer": format_rva(self.matches["arena-initializer"].rva),
+                "allocator_thread_initializer": format_rva(
+                    self.matches["allocator-thread-initializer"].rva
+                ),
+                "arena_guard_slot": format_rva(slots["arena_guard_slot"]),
+                "arena_table_slot": format_rva(slots["arena_table_slot"]),
+                "arena_table_slot_count": seeds["arena_table_slot_count"],
+            },
+            "native_allocator": {
+                "allocate": format_rva(found["allocate"]),
+                "deallocate": format_rva(found["free"]),
+            },
+            "init_array_offset": format_rva(candidate_image.sections[".init_array"].address),
+            "init_array_count": candidate_count,
+            "constructor_run_ranges": DERIVER.remapped_constructor_ranges(
+                reference_profile["constructor_run_ranges"],
+                offsets, reference_count, candidate_count,
+            ),
+            "native_mimalloc_constructor_run_ranges": native_ranges,
+            "native_mimalloc_thread_initializer_after_constructor": thread_boundary,
+            "native_pre_jni_bootstrap": {
+                "registry_initializer": format_rva(registry),
+                "registry_slot": format_rva(registry_slot),
+            },
+            "default_allocator_strategy": "native_mimalloc",
+        }
+        derived_anchors = {
+            "signature_version": 1,
+            "allocator_object_initializer_rva": format_rva(
+                self.map_instruction("allocator-object-initializer", allocator_anchor)
+            ),
+            "empty_string_initializer_rva": format_rva(
+                self.map_instruction("empty-string-initializer", empty_anchor)
+            ),
+            "jni_singleton_initializer_rva": format_rva(jni_singleton),
+            "constructor_rvas": {
+                str(index): format_rva(candidate_init[index])
+                for index in range(begin, begin + count)
+            },
+        }
+        DERIVER.validate_profile_shape(profile, derived_anchors)
+        return profile, derived_anchors
+
+    def derive_runtime_compatibility(self, source: dict[str, Any]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        fullscreen = source.get("user_game_settings_fullscreen_setter_rva")
+        if fullscreen is not None:
+            reference_setter = DERIVER.parse_rva(fullscreen, "fullscreen setter")
+            if not DERIVER.has_fullscreen_setter_contract(self.reference.image, reference_setter):
+                raise AnalyzerError("reference fullscreen setter contract changed")
+            setter = self.match_function(
+                "fullscreen-setter", reference_setter, DERIVER.has_fullscreen_setter_contract
+            )
+            result["user_game_settings_fullscreen_setter_rva"] = format_rva(setter)
+        fmod = source.get("fmod_output_device_bridge")
+        if fmod is not None:
+            result["fmod_output_device_bridge"] = self._derive_fmod_bridge(fmod)
+        return result
+
+    def _derive_fmod_bridge(self, source: dict[str, Any]) -> dict[str, Any]:
+        layout = validate_fmod_source(source)
+        has_input = FMOD_INPUT_FIELDS[0] in source
+        slots = fmod_slots(layout, has_input)
+        parse = DERIVER.parse_rva
+        vtable = parse(source["vtable_rva"], "FMOD vtable")
+        reference_relocations = DERIVER.relative_relocation_map(self.reference.image)
+        methods = {}
+        unresolved = []
+        for field, slot in slots.items():
+            method = parse(source[field], field)
+            if reference_relocations.get(vtable + slot * 8) != method:
+                raise AnalyzerError("reference FMOD vtable does not match its methods")
+            try:
+                methods[field] = self.match_function(
+                    f"fmod-{field}", method, self._fmod_contract(layout, field)
+                )
+            except AnalyzerError:
+                unresolved.append(field)
+        string_constructor = parse(source["string_constructor_rva"], "FMOD string constructor")
+        if not DERIVER.has_fmod_string_constructor_contract(self.reference.image, string_constructor):
+            raise AnalyzerError("reference FMOD string constructor contract changed")
+        candidate_string_constructor = self.match_function(
+            "fmod-string-constructor",
+            string_constructor,
+            DERIVER.has_fmod_string_constructor_contract,
+        )
+
+        relocations = DERIVER.relative_relocation_map(self.candidate.image)
+        located = self._locate_fmod_vtables(relocations, methods)
+        vtables = sorted({vtable for vtable, _ in located})
+        if len(vtables) != 1:
+            raise AnalyzerError(f"FMOD output vtable matched {len(vtables)} candidate locations")
+        # The located vtable breaks ties for the methods that did not resolve.
+        # Count and info share slots 5 and 6 in both layouts, so the vtable can
+        # fit both; exactly one layout must then hold every method.
+        solutions = []
+        for located_vtable, target_layout in located:
+            target_slots = fmod_slots(target_layout, has_input)
+            resolved = dict(methods)
+            try:
+                for field in unresolved:
+                    resolved[field] = self.match_function(
+                        f"fmod-{field}",
+                        parse(source[field], field),
+                        self._fmod_contract(target_layout, field),
+                        relocations.get(located_vtable + target_slots[field] * 8),
+                    )
+            except AnalyzerError:
+                continue
+            if self._locate_fmod_vtables(relocations, resolved) != [
+                (located_vtable, target_layout)
+            ]:
+                continue
+            if target_layout == 2 and not DERIVER.has_fmod_device_lists_select_contract(
+                self.candidate.image, resolved["select_method_rva"]
+            ):
+                continue
+            solutions.append((located_vtable, target_layout, target_slots, resolved))
+        if len(solutions) != 1:
+            raise AnalyzerError(f"FMOD output vtable holds every method in {len(solutions)} layouts")
+        located_vtable, target_layout, target_slots, methods = solutions[0]
+        self.candidate.image.require_relro_rva(
+            located_vtable, (max(target_slots.values()) + 1) * 8
+        )
+        result = {"vtable_rva": format_rva(located_vtable)}
+        result["string_constructor_rva"] = format_rva(candidate_string_constructor)
+        result.update((field, format_rva(rva)) for field, rva in methods.items())
+        if target_layout != 1:
+            result["vtable_layout_version"] = target_layout
+        return result
+
+    @staticmethod
+    def _fmod_contract(layout: int, field: str) -> Callable[[Any, int], bool] | None:
+        if layout == 2 and field == "select_method_rva":
+            return DERIVER.has_fmod_device_lists_select_contract
+        return None
+
+    @staticmethod
+    def _locate_fmod_vtables(
+        relocations: dict[int, int], methods: dict[str, int]
+    ) -> list[tuple[int, int]]:
+        """Returns (vtable, layout) for each vtable holding every method."""
+        located = []
+        for layout in (1, 2):
+            slots = fmod_slots(layout, True)
+            held = {slots[field]: rva for field, rva in methods.items()}
+            located.extend(
+                (vtable, layout)
+                for vtable in TargetDerivation._vtables_holding(relocations, held)
+            )
+        return sorted(located)
+
+    @staticmethod
+    def _vtables_holding(relocations: dict[int, int], methods: dict[int, int]) -> list[int]:
+        """Returns every vtable whose slots hold all of `methods`."""
+        if not methods:
+            raise AnalyzerError("no vtable method was matched")
+        slot, method = next(iter(methods.items()))
+        return sorted(
+            offset - slot * 8
+            for offset, value in relocations.items()
+            if value == method
+            and offset >= slot * 8
+            and (offset - slot * 8) % 8 == 0
+            and all(
+                relocations.get(offset - slot * 8 + index * 8) == rva
+                for index, rva in methods.items()
+            )
+        )
@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+# Copyright 2026 Mocktail Project Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""VR device bridge targets that `roblox_abi_solver.py` derives.
+
+`VrTargets.derive_vr` takes one build's VR bridge (the `VrBuildContract`
+fields in `src/vr/roblox_vr_device_bridge.cc`, as hex strings) and returns
+the same fields for the candidate build.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+import re
+import sys
+from typing import Any
+
+
+def _load_index():
+    name = "mocktail_roblox_function_index"
+    if name in sys.modules:
+        return sys.modules[name]
+    path = Path(__file__).resolve().with_name("roblox_function_index.py")
+    specification = importlib.util.spec_from_file_location(name, path)
+    if specification is None or specification.loader is None:
+        raise RuntimeError("cannot load roblox_function_index.py")
+    module = importlib.util.module_from_spec(specification)
+    sys.modules[name] = module
+    specification.loader.exec_module(module)
+    return module
+
+
+DERIVER = _load_index().DERIVER
+AnalyzerError = DERIVER.AnalyzerError
+format_rva = DERIVER.format_rva
+
+VR_FIELDS = (
+    "vtable_rva",
+    "constructor_rva",
+    "state_getter_rva",
+    "eye_getter_rva",
+    "eye_initializer_rva",
+    "emulator_flag_storage_rva",
+    "device_create_framebuffer_vtable_offset",
+    "state_memcpy_rva",
+    "pointer_frame_rva",
+    "workspace_getter_rva",
+    "camera_vtable_offset",
+    "hand_pitch_storage_rva",
+    "haptic_sink_rva",
+    "pointer_hand_selector_offset",
+    "camera_head_scale_offset",
+    "keep_haptics_flag_rva",
+    "vr_haptics_flag_rva",
+    "support_generic_haptics_flag_rva",
+    "fix_register_motors_flag_rva",
+)
+# Fast flag and setting storage, found through the functions that use it.
+_STORAGE_FIELDS = (
+    "emulator_flag_storage_rva",
+    "hand_pitch_storage_rva",
+    "keep_haptics_flag_rva",
+    "vr_haptics_flag_rva",
+    "support_generic_haptics_flag_rva",
+    "fix_register_motors_flag_rva",
+)
+# Storage users tried, smallest first; registration functions are small.
+_STORAGE_USER_LIMIT = 8
+_VTABLE_SLOT_LIMIT = 0x400
+# The constructor stores the vtable address plus the Itanium header.
+_VTABLE_REFERENCE_SPAN = 0x40
+_NUMBER = r"(0x[0-9a-f]+|\d+)"
+_SLOT_LOAD = re.compile(r"^mov (\w+), qword ptr \[\1 \+ ")
+# How far back the load of the vtable pointer itself may sit.
+_VTABLE_LOAD_WINDOW = 6
+
+
+def _vtable_call(instructions: list[Any], index: int) -> bool:
+    """A call through a vtable slot, or a load of the slot from a vtable
+    pointer loaded just before into the same register."""
+    shape = instructions[index].shape
+    if shape.startswith("call qword ptr ["):
+        return True
+    load = _SLOT_LOAD.match(shape)
+    if load is None:
+        return False
+    vtable_load = re.compile(rf"^mov {load.group(1)}, qword ptr \[\w+\]$")
+    return any(
+        vtable_load.match(previous.shape)
+        for previous in instructions[max(0, index - _VTABLE_LOAD_WINDOW) : index]
+    )
+
+
+class VrTargets:
+    """Mixin for `Solver`: needs `reference`, `candidate`, `matches`,
+    `match_function`, `map_data` and `_aligned`."""
+
+    def map_operand(
+        self, name: str, function_name: str, start: int, value: int, vtable_call: bool = False
+    ) -> int:
+        """Maps a field offset that a matched function uses as a displacement.
+
+        Stack-relative uses are ignored; with `vtable_call`, so is every use
+        that is not a virtual call. An instruction whose shape changed is
+        looked for between its nearest aligned neighbours.
+        """
+        reference, candidate, mapping = self._aligned(function_name, start)
+        token = re.compile(rf"(?<![0-9a-fx]){re.escape(hex(value))}(?![0-9a-f])")
+        found = set()
+        for index, item in enumerate(reference):
+            if not token.search(item.shape) or "rsp" in item.shape or "rbp" in item.shape:
+                continue
+            if vtable_call and not _vtable_call(reference, index):
+                continue
+            pattern = re.compile(
+                "^" + token.sub(lambda _: _NUMBER, re.escape(item.shape)) + "$"
+            )
+            if index in mapping:
+                window = range(mapping[index], mapping[index] + 1)
+            else:
+                below = max((k for k in mapping if k < index), default=None)
+                above = min((k for k in mapping if k > index), default=None)
+                low = 0 if below is None else mapping[below] + 1
+                high = len(candidate) if above is None else mapping[above]
+                window = range(low, high)
+            values = []
+            for position in window:
+                if vtable_call and not _vtable_call(candidate, position):
+                    continue
+                matched = pattern.match(candidate[position].shape)
+                if matched is not None and len({*matched.groups()}) == 1:
+                    values.append(int(matched.group(1), 0))
+            if len(values) != 1:
+                raise AnalyzerError(f"{name} has {len(values)} candidate offsets")
+            found.add(values[0])
+        if len(found) != 1:
+            raise AnalyzerError(f"{name} maps to {len(found)} offsets")
+        return found.pop()
+
+    def map_call_target(self, name: str, function_name: str, start: int, target: int) -> int:
+        """Maps the target of a direct call inside a matched function."""
+        reference, candidate, mapping = self._aligned(function_name, start)
+        found = set()
+        for index, item in enumerate(reference):
+            if item.shape != "call" or item.branch_target != target:
+                continue
+            if index not in mapping:
+                raise AnalyzerError(f"{name} call has no counterpart")
+            found.add(candidate[mapping[index]].branch_target)
+        if len(found) != 1 or None in found:
+            raise AnalyzerError(f"{name} has no unique call target")
+        return found.pop()
+
+    def _map_storage(self, name: str, target: int) -> int:
+        users = sorted(
+            self.reference.data_users.get(target, ()),
+            key=lambda start: self.reference.functions[start].size,
+        )[:_STORAGE_USER_LIMIT]
+        found = set()
+        for user in users:
+            user_name = f"{name} user {format_rva(user)}"
+            try:
+                self.match_function(user_name, user)
+                found.add(self.map_data(name, user_name, user, target))
+            except AnalyzerError:
+                continue
+        if len(found) != 1:
+            raise AnalyzerError(f"{name} maps to {len(found)} addresses")
+        return found.pop()
+
+    def _map_vtable(self, constructor: int, vtable: int) -> int:
+        found = set()
+        for item in self.reference.instructions(constructor):
+            for target in item.rip_targets:
+                if 0 <= target - vtable < _VTABLE_REFERENCE_SPAN:
+                    mapped = self.map_data("VR vtable", "vr-constructor", constructor, target)
+                    found.add(mapped - (target - vtable))
+        if len(found) != 1:
+            raise AnalyzerError(f"VR vtable maps to {len(found)} addresses")
+        return found.pop()
+
+    @staticmethod
+    def _slot(relocations: dict[int, int], vtable: int, method: int) -> int:
+        slots = [
+            offset
+            for offset in range(0, _VTABLE_SLOT_LIMIT, 8)
+            if relocations.get(vtable + offset) == method
+        ]
+        if not slots:
+            raise AnalyzerError(f"reference VR vtable does not hold {format_rva(method)}")
+        return slots[0]
+
+    def derive_vr(self, source: dict[str, str]) -> dict[str, str]:
+        missing = [field for field in VR_FIELDS if field not in source]
+        if missing:
+            raise AnalyzerError("reference VR bridge lacks " + ", ".join(missing))
+        value = {field: DERIVER.parse_rva(source[field], field) for field in VR_FIELDS}
+        result = {}
+        constructor = self.match_function("vr-constructor", value["constructor_rva"])
+        result["constructor_rva"] = constructor
+        vtable = self._map_vtable(value["constructor_rva"], value["vtable_rva"])
+        result["vtable_rva"] = vtable
+        reference_relocations = DERIVER.relative_relocation_map(self.reference.image)
+        relocations = DERIVER.relative_relocation_map(self.candidate.image)
+        slots = {
+            field: self._slot(reference_relocations, value["vtable_rva"], value[field])
+            for field in (
+                "state_getter_rva", "eye_getter_rva", "eye_initializer_rva", "haptic_sink_rva"
+            )
+        }
+        self.candidate.image.require_relro_rva(vtable, max(slots.values()) + 8)
+        for field in ("state_getter_rva", "eye_getter_rva", "eye_initializer_rva"):
+            result[field] = self.match_function(
+                f"vr-{field}", value[field], vtable_slot=relocations.get(vtable + slots[field])
+            )
+        # The haptic sink is a one-byte ret stub, so only its slot identifies it.
+        sink = relocations.get(vtable + slots["haptic_sink_rva"])
+        if sink is None or sink not in self.candidate.functions or (
+            self.candidate.functions[sink].size != 1
+        ):
+            raise AnalyzerError("VR haptic sink slot does not hold a ret stub")
+        result["haptic_sink_rva"] = sink
+        result["state_memcpy_rva"] = self.map_call_target(
+            "VR state memcpy", "vr-state_getter_rva",
+            value["state_getter_rva"], value["state_memcpy_rva"],
+        )
+        result["device_create_framebuffer_vtable_offset"] = self.map_operand(
+            "VR framebuffer slot", "vr-eye_initializer_rva",
+            value["eye_initializer_rva"], value["device_create_framebuffer_vtable_offset"],
+            vtable_call=True,
+        )
+        result["pointer_frame_rva"] = self.match_function(
+            "vr-pointer-frame", value["pointer_frame_rva"]
+        )
+        result["workspace_getter_rva"] = self.map_call_target(
+            "VR workspace getter", "vr-pointer-frame",
+            value["pointer_frame_rva"], value["workspace_getter_rva"],
+        )
+        for field in (
+            "camera_vtable_offset", "pointer_hand_selector_offset", "camera_head_scale_offset"
+        ):
+            result[field] = self.map_operand(
+                field, "vr-pointer-frame", value["pointer_frame_rva"], value[field],
+                vtable_call=field == "camera_vtable_offset",
+            )
+        for field in _STORAGE_FIELDS:
+            result[field] = self._map_storage(field, value[field])
+            self.candidate.image.require_writable_rva(result[field], 1)
+        return {field: format_rva(result[field]) for field in VR_FIELDS}
@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+# Copyright 2026 Mocktail Project Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Function index of one libroblox image for `roblox_abi_solver.py`.
+
+Every function listed in `.eh_frame_hdr` is decoded once and reduced to a
+normalized instruction shape, its direct calls and its RIP-relative data
+references. Shapes drop branch targets, RIP displacements and immediates of
+0x1000 and above, so a function moved by the linker keeps its shape.
+"""
+
+from __future__ import annotations
+
+import bisect
+import collections
+from dataclasses import dataclass
+import gzip
+import hashlib
+import importlib.util
+import json
+import os
+from pathlib import Path
+import re
+import struct
+import sys
+import tempfile
+from typing import Any
+
+
+def _load_deriver():
+    name = "mocktail_host_abi_deriver_for_solver"
+    if name in sys.modules:
+        return sys.modules[name]
+    path = Path(__file__).resolve().with_name("derive_roblox_host_abi_profile.py")
+    specification = importlib.util.spec_from_file_location(name, path)
+    if specification is None or specification.loader is None:
+        raise RuntimeError("cannot load the HostAbi deriver")
+    module = importlib.util.module_from_spec(specification)
+    sys.modules[name] = module
+    specification.loader.exec_module(module)
+    return module
+
+
+DERIVER = _load_deriver()
+AnalyzerError = DERIVER.AnalyzerError
+
+_RIP_OPERAND = re.compile(r"\[rip ([+-]) (0x[0-9a-f]+|\d+)\]")
+_IMMEDIATE = re.compile(r"0x[0-9a-f]+|\b\d+\b")
+# Smaller immediates are offsets and flags that stay put between builds.
+# Larger ones are addresses and sizes that move.
+_STABLE_IMMEDIATE_LIMIT = 0x1000
+
+
+def _stable_immediate(match: re.Match) -> str:
+    return "I" if int(match.group(0), 0) >= _STABLE_IMMEDIATE_LIMIT else match.group(0)
+
+
+@dataclass(frozen=True)
+class Instruction:
+    address: int
+    shape: str
+    rip_targets: tuple[int, ...]
+    branch_target: int | None
+
+
+def decode_function(
+    decoder: Any, code: bytes, start: int
+) -> list[Instruction]:
+    end = start + len(code)
+    instructions = []
+    for address, size, mnemonic, operands in decoder.disasm_lite(code, start):
+        if (mnemonic == "call" or mnemonic.startswith("j")) and operands.startswith("0x"):
+            target = int(operands, 16)
+            if mnemonic == "call":
+                shape = "call"
+            else:
+                shape = mnemonic + (" in" if start <= target < end else " out")
+            instructions.append(Instruction(address, shape, (), target))
+            continue
+        rip_targets = []
+        for match in _RIP_OPERAND.finditer(operands):
+            displacement = int(match.group(2), 0)
+            rip_targets.append(
+                address + size + (-displacement if match.group(1) == "-" else displacement)
+            )
+        operands = _IMMEDIATE.sub(_stable_immediate, _RIP_OPERAND.sub("[rip]", operands))
+        instructions.append(
+            Instruction(address, f"{mnemonic} {operands}", tuple(rip_targets), None)
+        )
+    return instructions
+
+
+@dataclass(frozen=True)
+class FunctionInfo:
+    size: int
+    shape_hash: bytes
+    calls: tuple[int, ...]
+    refs: tuple[int, ...]
+
+
+def function_table(image: Any) -> list[tuple[int, int]]:
+    """Returns (start, size) for every FDE indexed by `.eh_frame_hdr`."""
+    header = image.sections.get(".eh_frame_hdr")
+    if header is None:
+        raise AnalyzerError("libroblox has no .eh_frame_hdr")
+    raw = image.section_bytes(header)
+    # Version 1, a 4-byte eh_frame_ptr, udata4 count, datarel sdata4 table.
+    if len(raw) < 12 or raw[0] != 1 or raw[2] != 0x03 or raw[3] != 0x3B:
+        raise AnalyzerError(".eh_frame_hdr uses an unsupported encoding")
+    if raw[1] == 0xFF or raw[1] & 0x0F not in (0x03, 0x0B):
+        raise AnalyzerError(".eh_frame_hdr eh_frame_ptr encoding is not 4 bytes")
+    count = struct.unpack_from("<I", raw, 8)[0]
+    if 12 + count * 8 > len(raw):
+        raise AnalyzerError(".eh_frame_hdr table exceeds its section")
+    table = []
+    for index in range(count):
+        location, fde = struct.unpack_from("<ii", raw, 12 + index * 8)
+        start = header.address + location
+        fde_rva = header.address + fde
+        offset = image.rva_to_offset(fde_rva, 16)
+        length, _, begin, size = struct.unpack_from("<IIiI", image.data, offset)
+        # An FDE starts with its length, CIE pointer, then a pcrel sdata4
+        # pc_begin and its udata4 range.
+        if length == 0xFFFFFFFF or fde_rva + 8 + begin != start:
+            raise AnalyzerError(".eh_frame FDE does not match its index entry")
+        table.append((start, size))
+    table.sort()
+    return table
+
+
+_SOURCE_DIGEST = hashlib.sha256(Path(__file__).read_bytes()).hexdigest()[:16]
+
+
+def cache_path(cache_dir: Path, library_sha256: str) -> Path:
+    """Cache file for one library; shapes depend on this code and capstone."""
+    version = getattr(DERIVER.capstone, "__version__", "unknown")
+    return cache_dir / f"{library_sha256}-{_SOURCE_DIGEST}-capstone{version}.json.gz"
+
+
+def link_functions(
+    functions: dict[int, FunctionInfo],
+) -> tuple[dict[int, list[int]], dict[int, list[int]]]:
+    """Returns each function's callers and each data address's users, once each."""
+    callers: dict[int, list[int]] = collections.defaultdict(list)
+    data_users: dict[int, list[int]] = collections.defaultdict(list)
+    for start, info in functions.items():
+        for target in dict.fromkeys(info.calls):
+            if target in functions:
+                callers[target].append(start)
+        for target in dict.fromkeys(info.refs):
+            data_users[target].append(start)
+    return callers, data_users
+
+
+def _int_list(value: Any) -> tuple[int, ...]:
+    if not isinstance(value, list) or not all(type(item) is int for item in value):
+        raise ValueError("cached index entry is malformed")
+    return tuple(value)
+
+
+def _read_cache(path: Path) -> dict[int, FunctionInfo] | None:
+    """Returns the cached functions, or None when the file is missing or bad."""
+    try:
+        with gzip.open(path, "rt", encoding="utf-8") as stream:
+            entries = json.load(stream)
+        if not isinstance(entries, list) or not entries:
+            raise ValueError("cached index is empty")
+        functions = {}
+        for entry in entries:
+            start, size, shape_hash, calls, refs = entry
+            if type(start) is not int or type(size) is not int:
+                raise ValueError("cached index entry is malformed")
+            functions[start] = FunctionInfo(
+                size, bytes.fromhex(shape_hash), _int_list(calls), _int_list(refs)
+            )
+        return functions
+    except (OSError, EOFError, ValueError, TypeError):
+        return None
+
+
+def _write_cache(path: Path, functions: dict[int, FunctionInfo]) -> None:
+    # A cache that cannot be written only costs the next run a rebuild.
+    entries = [
+        [start, info.size, info.shape_hash.hex(), list(info.calls), list(info.refs)]
+        for start, info in functions.items()
+    ]
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    except OSError:
+        return
+    try:
+        with os.fdopen(descriptor, "wb") as raw, gzip.open(raw, "wt", encoding="utf-8") as stream:
+            json.dump(entries, stream, separators=(",", ":"))
+        os.replace(temporary, path)
+    except OSError:
+        Path(temporary).unlink(missing_ok=True)
+
+
+class FunctionIndex:
+    """Normalized shapes, calls and data references of every function.
+
+    With `cache_dir`, the per-function data is kept in a file named after the
+    library's SHA-256, this module's source and the capstone version, and read
+    back instead of decoding the library again.
+    """
+
+    def __init__(self, image: Any, cache_dir: Path | None = None):
+        DERIVER.require_capstone()
+        self.image = image
+        self.decoder = DERIVER.capstone.Cs(
+            DERIVER.capstone.CS_ARCH_X86, DERIVER.capstone.CS_MODE_64
+        )
+        self.text = image.sections[".text"]
+        self._decoded: dict[int, list[Instruction]] = {}
+        path = None if cache_dir is None else cache_path(Path(cache_dir), image.sha256)
+        functions = None if path is None else _read_cache(path)
+        if functions is None:
+            functions = self._decode_all()
+            if path is not None:
+                _write_cache(path, functions)
+        self.functions = functions
+        self.starts = sorted(self.functions)
+        self.callers, self.data_users = link_functions(self.functions)
+
+    def _decode_all(self) -> dict[int, FunctionInfo]:
+        text_end = self.text.address + self.text.size
+        functions = {}
+        for start, size in function_table(self.image):
+            if size == 0 or not self.text.address <= start < text_end:
+                continue
+            instructions = self.instructions(start, size, cache=False)
+            shape_hash = hashlib.blake2b(
+                "\n".join(item.shape for item in instructions).encode(), digest_size=8
+            ).digest()
+            calls = tuple(
+                item.branch_target
+                for item in instructions
+                if item.branch_target is not None
+                and (item.shape == "call" or item.shape.endswith(" out"))
+            )
+            refs = tuple(target for item in instructions for target in item.rip_targets)
+            functions[start] = FunctionInfo(size, shape_hash, calls, refs)
+        return functions
+
+    def instructions(
+        self, start: int, size: int | None = None, cache: bool = True
+    ) -> list[Instruction]:
+        if cache and start in self._decoded:
+            return self._decoded[start]
+        if size is None:
+            size = self.functions[start].size
+        offset = self.text.offset + start - self.text.address
+        decoded = decode_function(self.decoder, self.image.data[offset : offset + size], start)
+        if cache:
+            self._decoded[start] = decoded
+        return decoded
+
+    def shapes(self, start: int) -> list[str]:
+        # Scoring reads each candidate once; only aligned functions stay cached.
+        return [item.shape for item in self.instructions(start, cache=start in self._decoded)]
+
+    def containing(self, rva: int) -> int | None:
+        index = bisect.bisect_right(self.starts, rva) - 1
+        if index < 0:
+            return None
+        start = self.starts[index]
+        return start if rva < start + self.functions[start].size else None
+
+    def string_at(self, rva: int) -> bytes | None:
+        segment = self.image.segment_for_rva(rva)
+        if segment is None or not segment.contains_file_data(rva):
+            return None
+        offset = self.image.rva_to_offset(rva)
+        raw = self.image.data[offset : offset + 96]
+        end = raw.find(b"\0")
+        if end < 4 or not all(32 <= byte < 127 for byte in raw[:end]):
+            return None
+        return raw[:end]
@@ -6,8 +6,9 @@
 Usage: summarize_profile_trace.py TRACE [TRACE ...]

 Each trace gets its own column, so `before.json after.json` compares them.
-Frame times come from the "frame interval (ms)" counter; every other row is
-a slice name recorded by the Vulkan adapter.
+Frame times come from the "frame interval (ms)" counter, peaks from the
+texture counters; every other row is a slice name recorded by the Vulkan
+adapter.
 """

 from __future__ import annotations
@@ -20,6 +21,7 @@ import sys
 from typing import Iterable

 FRAME_COUNTER = "frame interval (ms)"
+PEAK_COUNTERS = ("emulated texture (MB)", "compressed texture (MB)")


@dataclass(frozen=True)
@@ -37,6 +39,7 @@ class Distribution:
 class Summary:
    frames: Distribution | None
    slices: dict[str, Distribution]
+    peaks: dict[str, float]


 def _nearest_rank(ordered: list[float], percent: float) -> float:
@@ -57,16 +60,21 @@ def _distribution(values: list[float]) -> Distribution:
 def summarize(events: Iterable[dict]) -> Summary:
    frames: list[float] = []
    slices: dict[str, list[float]] = {}
+    peaks: dict[str, float] = {}
    for event in events:
        phase = event.get("ph")
        if phase == "C" and event.get("name") == FRAME_COUNTER:
            frames.append(float(event["args"]["value"]))
+        elif phase == "C" and event.get("name") in PEAK_COUNTERS:
+            value = float(event["args"]["value"])
+            peaks[event["name"]] = max(peaks.get(event["name"], value), value)
        elif phase == "X":
            slices.setdefault(event["name"], []).append(event["dur"] / 1000)
    return Summary(
        frames=_distribution(frames) if frames else None,
        slices={name: _distribution(values)
-                for name, values in slices.items()})
+                for name, values in slices.items()},
+        peaks=peaks)


 def _row(label: str, cells: list[str]) -> str:
@@ -96,6 +104,11 @@ def to_markdown(traces: list[tuple[str, Summary]]) -> str:
    if any(frames):
        lines += [_metric_row(f"frame interval {field} (ms)", frames, field)
                  for field in ("mean", "p50", "p95", "p99", "max")]
+    for name in PEAK_COUNTERS:
+        if any(name in summary.peaks for summary in summaries):
+            lines.append(_row(f"{name} peak", [
+                f"{summary.peaks[name]:.2f}" if name in summary.peaks else "-"
+                for summary in summaries]))

    # Largest total time first, taken from whichever trace spent the most.
    totals: dict[str, float] = {}
@@ -0,0 +1,8 @@
+#version 450
+// One triangle that covers the viewport; uv spans 0..1 over the target.
+layout(location = 0) out vec2 uv;
+
+void main() {
+  uv = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+  gl_Position = vec4(uv * 2.0 - 1.0, 0.0, 1.0);
+}
@@ -0,0 +1,59 @@
+#version 450
+// FXAA for one VR eye, after Timothy Lottes' FXAA (console variant). The eye
+// holds sRGB-encoded bytes, so luma is computed on perceptual values, which
+// is what FXAA expects.
+layout(set = 0, binding = 0) uniform sampler2D source;
+layout(push_constant) uniform Push {
+  vec2 texel;          // 1 / source extent
+  uint linearize;      // 1 when the target view re-encodes to sRGB
+} push;
+layout(location = 0) in vec2 uv;
+layout(location = 0) out vec4 color;
+
+const float kEdgeThreshold = 1.0 / 8.0;
+const float kEdgeThresholdMin = 1.0 / 24.0;
+const float kReduceMul = 1.0 / 8.0;
+const float kReduceMin = 1.0 / 128.0;
+const float kSpanMax = 8.0;
+
+float Luma(vec3 rgb) { return dot(rgb, vec3(0.299, 0.587, 0.114)); }
+
+vec3 Sample(vec2 at) { return textureLod(source, at, 0.0).rgb; }
+
+// The target encodes linear values back to sRGB, which restores these bytes.
+vec3 Linearize(vec3 c) {
+  return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)),
+             step(vec3(0.04045), c));
+}
+
+void main() {
+  const vec4 center = textureLod(source, uv, 0.0);
+  const float lumaM = Luma(center.rgb);
+  const float lumaNW = Luma(Sample(uv + vec2(-1.0, -1.0) * push.texel));
+  const float lumaNE = Luma(Sample(uv + vec2(1.0, -1.0) * push.texel));
+  const float lumaSW = Luma(Sample(uv + vec2(-1.0, 1.0) * push.texel));
+  const float lumaSE = Luma(Sample(uv + vec2(1.0, 1.0) * push.texel));
+  const float lumaMin =
+      min(lumaM, min(min(lumaNW, lumaNE), min(lumaSW, lumaSE)));
+  const float lumaMax =
+      max(lumaM, max(max(lumaNW, lumaNE), max(lumaSW, lumaSE)));
+
+  vec3 rgb = center.rgb;
+  // Flat areas, where nothing aliases, keep their exact pixels.
+  if (lumaMax - lumaMin >= max(kEdgeThresholdMin, lumaMax * kEdgeThreshold)) {
+    vec2 dir = vec2(-((lumaNW + lumaNE) - (lumaSW + lumaSE)),
+                    (lumaNW + lumaSW) - (lumaNE + lumaSE));
+    const float reduce = max((lumaNW + lumaNE + lumaSW + lumaSE) *
+                                 (0.25 * kReduceMul),
+                             kReduceMin);
+    const float rcpDirMin = 1.0 / (min(abs(dir.x), abs(dir.y)) + reduce);
+    dir = clamp(dir * rcpDirMin, vec2(-kSpanMax), vec2(kSpanMax)) * push.texel;
+    const vec3 rgbA = 0.5 * (Sample(uv + dir * (1.0 / 3.0 - 0.5)) +
+                             Sample(uv + dir * (2.0 / 3.0 - 0.5)));
+    const vec3 rgbB =
+        rgbA * 0.5 + 0.25 * (Sample(uv + dir * -0.5) + Sample(uv + dir * 0.5));
+    const float lumaB = Luma(rgbB);
+    rgb = (lumaB < lumaMin || lumaB > lumaMax) ? rgbA : rgbB;
+  }
+  color = vec4(push.linearize != 0u ? Linearize(rgb) : rgb, center.a);
+}
@@ -0,0 +1,21 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#include "smaa_common.glsl"
+#define SMAA_INCLUDE_VS 0
+#include "SMAA.hlsl"
+layout(set = 0, binding = 0) uniform sampler2D colorTex;
+layout(set = 0, binding = 1) uniform sampler2D blendTex;
+layout(location = 0) in vec2 texcoord;
+layout(location = 1) in vec4 offset;
+layout(location = 0) out vec4 color;
+
+// The target encodes linear values back to sRGB, which restores these bytes.
+vec3 Linearize(vec3 c) {
+  return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)),
+             step(vec3(0.04045), c));
+}
+
+void main() {
+  color = SMAANeighborhoodBlendingPS(texcoord, offset, colorTex, blendTex);
+  if (push.linearize != 0u) color.rgb = Linearize(color.rgb);
+}
@@ -0,0 +1,13 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#include "smaa_common.glsl"
+#define SMAA_INCLUDE_PS 0
+#include "SMAA.hlsl"
+layout(location = 0) out vec2 texcoord;
+layout(location = 1) out vec4 offset;
+
+void main() {
+  texcoord = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+  gl_Position = vec4(texcoord * 2.0 - 1.0, 0.0, 1.0);
+  SMAANeighborhoodBlendingVS(texcoord, offset);
+}
@@ -0,0 +1,11 @@
+// Shared setup for the SMAA passes: the upstream SMAA.hlsl (third_party/smaa)
+// in its GLSL 4 mode at the High preset. Vulkan, like Direct3D, puts the
+// texture origin at the top left, which is what SMAA and its lookup textures
+// expect, so nothing is flipped.
+layout(push_constant) uniform Push {
+  vec4 metrics;    // 1/width, 1/height, width, height
+  uint linearize;  // 1 when the target view re-encodes to sRGB
+} push;
+#define SMAA_RT_METRICS push.metrics
+#define SMAA_GLSL_4 1
+#define SMAA_PRESET_HIGH 1
@@ -0,0 +1,12 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#include "smaa_common.glsl"
+#define SMAA_INCLUDE_VS 0
+#include "SMAA.hlsl"
+// Luma edges on the eye's sRGB-encoded bytes, as SMAA recommends.
+layout(set = 0, binding = 0) uniform sampler2D colorTex;
+layout(location = 0) in vec2 texcoord;
+layout(location = 1) in vec4 offset[3];
+layout(location = 0) out vec2 edges;
+
+void main() { edges = SMAALumaEdgeDetectionPS(texcoord, offset, colorTex); }
@@ -0,0 +1,13 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#include "smaa_common.glsl"
+#define SMAA_INCLUDE_PS 0
+#include "SMAA.hlsl"
+layout(location = 0) out vec2 texcoord;
+layout(location = 1) out vec4 offset[3];
+
+void main() {
+  texcoord = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+  gl_Position = vec4(texcoord * 2.0 - 1.0, 0.0, 1.0);
+  SMAAEdgeDetectionVS(texcoord, offset);
+}
@@ -0,0 +1,17 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#include "smaa_common.glsl"
+#define SMAA_INCLUDE_VS 0
+#include "SMAA.hlsl"
+layout(set = 0, binding = 0) uniform sampler2D edgesTex;
+layout(set = 0, binding = 1) uniform sampler2D areaTex;
+layout(set = 0, binding = 2) uniform sampler2D searchTex;
+layout(location = 0) in vec2 texcoord;
+layout(location = 1) in vec2 pixcoord;
+layout(location = 2) in vec4 offset[3];
+layout(location = 0) out vec4 weights;
+
+void main() {
+  weights = SMAABlendingWeightCalculationPS(texcoord, pixcoord, offset, edgesTex,
+                                            areaTex, searchTex, vec4(0.0));
+}
@@ -0,0 +1,14 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#include "smaa_common.glsl"
+#define SMAA_INCLUDE_PS 0
+#include "SMAA.hlsl"
+layout(location = 0) out vec2 texcoord;
+layout(location = 1) out vec2 pixcoord;
+layout(location = 2) out vec4 offset[3];
+
+void main() {
+  texcoord = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+  gl_Position = vec4(texcoord * 2.0 - 1.0, 0.0, 1.0);
+  SMAABlendingWeightCalculationVS(texcoord, pixcoord, offset);
+}
@@ -5,9 +5,33 @@
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="color-scheme" content="dark">
-  <title>Nightcap for Linux</title>
-  <meta name="description" content="Play Roblox on Linux like it was made for your PC. Nightcap is Mocktail, tuned to feel fast and look sharp.">
+  <title>Nightcap: Roblox on Linux</title>
+  <meta name="description" content="Roblox on Linux, tuned for desktop play. A Mocktail fork that keeps up with Roblox updates, with extra bug fixes, custom assets and more.">
+  <meta name="google-site-verification" content="vznL8W2txRlmfwhGg7ZBPSxQaPV9OtaIUoYPvmd9aUA">
+  <link rel="canonical" href="https://coderdayton.github.io/nightcap/">
  <link rel="icon" href="nightcap.svg" type="image/svg+xml">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="Nightcap">
+  <meta property="og:title" content="Nightcap: Roblox on Linux">
+  <meta property="og:description" content="Roblox on Linux, tuned for desktop play. A Mocktail fork that keeps up with Roblox updates, with extra bug fixes, custom assets and more.">
+  <meta property="og:url" content="https://coderdayton.github.io/nightcap/">
+  <meta property="og:image" content="https://coderdayton.github.io/nightcap/preview.png">
+  <meta property="og:image:alt" content="Roblox running on Linux with Nightcap">
+  <meta name="twitter:card" content="summary_large_image">
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "SoftwareApplication",
+    "name": "Nightcap",
+    "description": "Roblox on Linux, tuned for desktop play. A Mocktail fork that keeps up with Roblox updates, with extra bug fixes, custom assets and more.",
+    "applicationCategory": "GameApplication",
+    "operatingSystem": "Linux",
+    "url": "https://coderdayton.github.io/nightcap/",
+    "downloadUrl": "https://github.com/CoderDayton/nightcap/releases/latest",
+    "license": "https://www.apache.org/licenses/LICENSE-2.0",
+    "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }
+  }
+  </script>
  <link rel="stylesheet" href="styles.css">
 </head>
 <body>
@@ -17,8 +41,9 @@
        <a href="https://github.com/CoderDayton/nightcap" aria-label="Nightcap on GitHub" title="GitHub"><svg viewBox="0 0 16 16" width="24" height="24" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg></a>
        <a href="https://discord.gg/DbAUG9hBFU" aria-label="Nightcap on Discord" title="Discord"><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true"><path fill="currentColor" d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189z"/></svg></a>
      </p>
+      <p class="eyebrow">Roblox on Linux, tuned for desktop play</p>
      <h1><img src="nightcap.svg" alt=""><span>Nightcap</span></h1>
-      <p class="lede">Play Roblox on Linux like it was made for your PC. Nightcap is Mocktail, tuned to feel fast and look sharp.</p>
+      <p class="lede">A Mocktail fork that keeps up with Roblox updates, with extra bug fixes, custom assets and more.</p>
      <p class="actions">
        <a class="button" href="https://github.com/CoderDayton/nightcap/releases/latest/download/Nightcap-x86_64.AppImage">Download AppImage</a>
        <a class="button secondary" href="nightcap.flatpakref">Install with Flatpak</a>
@@ -50,16 +75,20 @@ cd nightcap &amp;&amp; make build
    <section class="row">
      <h2>What's different</h2>
      <dl class="body facts">
-        <dt>Input lag</dt>
-        <dd>Lower. Frames are shown as soon as they are ready.</dd>
-        <dt>Textures</dt>
-        <dd>Sharper, with your own PNG overrides if you want them.</dd>
-        <dt>ETC2</dt>
-        <dd>Textures render correctly on desktop GPUs.</dd>
-        <dt>Error 319</dt>
-        <dd>No more kicks after joining a server.</dd>
-        <dt>RAM and screen</dt>
-        <dd>Roblox sees your real RAM and screen size.</dd>
+        <dt>Roblox updates</dt>
+        <dd>New Roblox versions work soon after they come out.</dd>
+        <dt>More games</dt>
+        <dd>Answers a server check some experiences use, so you can play those too.</dd>
+        <dt>Voice chat</dt>
+        <dd>Your microphone still works after a Roblox update.</dd>
+        <dt>Login</dt>
+        <dd>Verification checks and captchas finish instead of hanging.</dd>
+        <dt>Look</dt>
+        <dd>The new home screen and side menu, like on Windows.</dd>
+        <dt>Your own assets</dt>
+        <dd>Drop in your own cursors, fonts and skies. The folder layout matches Sober's.</dd>
+        <dt>Mouse and CPU</dt>
+        <dd>Optional raw mouse input, and less CPU use while idle.</dd>
      </dl>
    </section>

@@ -48,8 +48,21 @@ button:focus-visible { outline: 2px solid var(--link); outline-offset: 3px; }

 .top a:hover { color: var(--ink); }

-.hero h1 {
+.eyebrow {
+  display: inline-block;
  margin: clamp(48px, 12vh, 130px) 0 0;
+  padding: 6px 12px;
+  border: 1px solid var(--line);
+  background: var(--code-bg);
+  color: var(--link);
+  font-size: .85rem;
+  font-weight: 700;
+  letter-spacing: .06em;
+  text-transform: uppercase;
+}
+
+.hero h1 {
+  margin: 18px 0 0;
  font-size: clamp(3.6rem, 15vw, 9.5rem);
  font-weight: 800;
  line-height: .95;
@@ -66,7 +79,7 @@ button:focus-visible { outline: 2px solid var(--link); outline-offset: 3px; }
 }

 .lede {
-  max-width: 30ch;
+  max-width: 34ch;
  margin: 22px 0 0;
  color: var(--ink);
  font-size: 1.25rem;
@@ -148,6 +148,57 @@ bool ParseOptionalFmodOutputDeviceBridge(
  return input_fields_present == 0 || input_fields_present == 4;
 }

+bool ParseOptionalVrDebugDeviceBridge(
+    const Json& object,
+    std::optional<VrDebugDeviceBridgeProfile>* bridge_profile) {
+  if (bridge_profile == nullptr) {
+    return false;
+  }
+  bridge_profile->reset();
+  const auto field = object.find("vr_debug_device_bridge");
+  if (field == object.end() || field->is_null()) {
+    return true;
+  }
+  if (!field->is_object()) {
+    return false;
+  }
+
+  std::optional<std::uintptr_t> vtable_rva;
+  std::optional<std::uintptr_t> constructor_rva;
+  std::optional<std::uintptr_t> state_getter_rva;
+  std::optional<std::uintptr_t> eye_getter_rva;
+  std::optional<std::uintptr_t> eye_initializer_rva;
+  std::optional<std::uintptr_t> emulator_flag_storage_rva;
+  std::optional<std::uintptr_t> device_create_framebuffer_vtable_offset;
+  if (!ParseOptionalRva(*field, "vtable_rva", &vtable_rva) ||
+      !ParseOptionalRva(*field, "constructor_rva", &constructor_rva) ||
+      !ParseOptionalRva(*field, "state_getter_rva", &state_getter_rva) ||
+      !ParseOptionalRva(*field, "eye_getter_rva", &eye_getter_rva) ||
+      !ParseOptionalRva(*field, "eye_initializer_rva", &eye_initializer_rva) ||
+      !ParseOptionalRva(*field, "emulator_flag_storage_rva",
+                        &emulator_flag_storage_rva) ||
+      !ParseOptionalRva(*field, "device_create_framebuffer_vtable_offset",
+                        &device_create_framebuffer_vtable_offset) ||
+      !vtable_rva.has_value() || !constructor_rva.has_value() ||
+      !state_getter_rva.has_value() || !eye_getter_rva.has_value() ||
+      !eye_initializer_rva.has_value() ||
+      !emulator_flag_storage_rva.has_value() ||
+      !device_create_framebuffer_vtable_offset.has_value()) {
+    return false;
+  }
+
+  *bridge_profile = VrDebugDeviceBridgeProfile{
+      *vtable_rva,
+      *constructor_rva,
+      *state_getter_rva,
+      *eye_getter_rva,
+      *eye_initializer_rva,
+      *emulator_flag_storage_rva,
+      *device_create_framebuffer_vtable_offset,
+  };
+  return true;
+}
+
 }  // namespace

 std::string_view BuildStatusName(BuildStatus status) noexcept {
@@ -211,6 +262,7 @@ ProfileLookupResult FindBuildProfile(const std::string& manifest_path,
    const Json* reason = RequiredField(entry, "reason");
    std::optional<std::uintptr_t> fullscreen_setter_rva;
    std::optional<FmodOutputDeviceBridgeProfile> fmod_output_device_bridge;
+    std::optional<VrDebugDeviceBridgeProfile> vr_debug_device_bridge;
    if (version_name == nullptr || !version_name->is_string() ||
        version_code == nullptr || !version_code->is_number_integer() ||
        profile_build_id == nullptr || !profile_build_id->is_string() ||
@@ -227,7 +279,8 @@ ProfileLookupResult FindBuildProfile(const std::string& manifest_path,
                          "user_game_settings_fullscreen_setter_rva",
                          &fullscreen_setter_rva) ||
        !ParseOptionalFmodOutputDeviceBridge(
-            entry, &fmod_output_device_bridge)) {
+            entry, &fmod_output_device_bridge) ||
+        !ParseOptionalVrDebugDeviceBridge(entry, &vr_debug_device_bridge)) {
      return Failure("compatibility profile has missing or invalid fields");
    }

@@ -278,6 +331,7 @@ ProfileLookupResult FindBuildProfile(const std::string& manifest_path,
        allow_host_constructor_replay->get<bool>(),
        fullscreen_setter_rva,
        fmod_output_device_bridge,
+        vr_debug_device_bridge,
        reason->get_ref<const std::string&>(),
    };
  }
@@ -6,6 +6,27 @@ namespace mocktail::compat {
 namespace {

 constexpr HostAbiProfile kProfiles[] = {
+    // Roblox 2.738.1397; promoted from the exact-build probation profile.
+    {"5f0704edd9064f566ee3d6df2bd2fabbcc709f03",
+     {{{0x1d73422, HostBridgeKind::kAllocate, "small-allocate"},
+       {0x1d7667a, HostBridgeKind::kUsableSize, "usable-size"},
+       {0x222f4c0, HostBridgeKind::kReallocate, "reallocate"},
+       {0x1d731c2, HostBridgeKind::kAllocate, "allocate"},
+       {0x1d8e7f9, HostBridgeKind::kAlignedAllocate, "aligned-allocate-direct"},
+       {0x1d76c19, HostBridgeKind::kFree, "free"}}},
+     6,
+     {0x76e2da0, 0x77efb98, 0x7c4b780, 0x400, 0x1d73838, 0x1dffad7, 0x7b87830,
+      0x7b878c0, 0x400000},
+     {0x1d731c2, 0x1d76c19},
+     0x70e1618,
+     3599,
+     {{{2, 3}, {5, 3599}}},
+     2,
+     {{{2, 3599}}},
+     1,
+     2,
+     {0x22308d3, 0x7b8b998},
+     HostAllocatorStrategy::kNativeMimalloc},
    // Roblox 2.736.1408 arm64-v8a. Every RVA was derived from the AArch64
    // payload of the same release as the x86-64 reference above, matched by
    // allocator internals, init_array call graphs, and static state layout.
@@ -41,12 +62,11 @@ constexpr HostAbiProfile kProfiles[] = {
       {0x1d2f43a, HostBridgeKind::kUsableSize, "usable-size"},
       {0x21e68bf, HostBridgeKind::kReallocate, "reallocate"},
       {0x1d2bf82, HostBridgeKind::kAllocate, "allocate"},
-       {0x1d47a63, HostBridgeKind::kAlignedAllocate,
-        "aligned-allocate-direct"},
+       {0x1d47a63, HostBridgeKind::kAlignedAllocate, "aligned-allocate-direct"},
       {0x1d2f9d9, HostBridgeKind::kFree, "free"}}},
     6,
-     {0x7652e70, 0x775fd28, 0x7bb4340, 0x400, 0x1d2c5f8, 0x1db7b57,
-      0x7af0430, 0x7af04c0, 0x400000},
+     {0x7652e70, 0x775fd28, 0x7bb4340, 0x400, 0x1d2c5f8, 0x1db7b57, 0x7af0430,
+      0x7af04c0, 0x400000},
     {0x1d2bf82, 0x1d2f9d9},
     0x7057818,
     3570,
@@ -66,12 +86,11 @@ constexpr HostAbiProfile kProfiles[] = {
       {0x1cf9c3a, HostBridgeKind::kUsableSize, "usable-size"},
       {0x21af33f, HostBridgeKind::kReallocate, "reallocate"},
       {0x1cf677e, HostBridgeKind::kAllocate, "allocate"},
-       {0x1d12197, HostBridgeKind::kAlignedAllocate,
-        "aligned-allocate-direct"},
+       {0x1d12197, HostBridgeKind::kAlignedAllocate, "aligned-allocate-direct"},
       {0x1cfa1d9, HostBridgeKind::kFree, "free"}}},
     6,
-     {0x7571570, 0x767e428, 0x7ad47e8, 0x400, 0x1cf6df8, 0x1d82be7,
-      0x7a10730, 0x7a107c0, 0x400000},
+     {0x7571570, 0x767e428, 0x7ad47e8, 0x400, 0x1cf6df8, 0x1d82be7, 0x7a10730,
+      0x7a107c0, 0x400000},
     {0x1cf677e, 0x1cfa1d9},
     0x6f78a18,
     3556,
@@ -92,12 +111,11 @@ constexpr HostAbiProfile kProfiles[] = {
       {0x1fe4c84, HostBridgeKind::kUsableSize, "usable-size"},
       {0x203daae, HostBridgeKind::kReallocate, "reallocate"},
       {0x1c39c3a, HostBridgeKind::kAllocate, "allocate"},
-       {0x1c8dbf8, HostBridgeKind::kAlignedAllocate,
-        "aligned-allocate-direct"},
+       {0x1c8dbf8, HostBridgeKind::kAlignedAllocate, "aligned-allocate-direct"},
       {0x1c3eb72, HostBridgeKind::kFree, "free"}}},
     6,
-     {0x7030ae0, 0x703a7e8, 0x72a16d0, 0x400, 0x1c39f1d, 0x2040817,
-      0x71e92f0, 0x71e9380, 0x400000},
+     {0x7030ae0, 0x703a7e8, 0x72a16d0, 0x400, 0x1c39f1d, 0x2040817, 0x71e92f0,
+      0x71e9380, 0x400000},
     {0x1c39c3a, 0x1c3eb72},
     0x6c2c9b0,
     0x6cc8 / 8,
@@ -37,9 +37,14 @@ PresentModePolicy ResolvePresentModePolicy(std::string_view vsync_value,

 PresentModePolicy CachedPresentModePolicy() {
  static const PresentModePolicy policy = [] {
+    // main() clears MOCKTAIL_VR_ENABLED when VR cannot start for this build,
+    // so the VR limit only applies while VR is actually active.
+    const std::string_view vr = EnvironmentOr("MOCKTAIL_VR_ENABLED", "0");
+    const bool vr_enabled = vr == "1" || vr == "true" || vr == "on";
    return ResolvePresentModePolicy(
        EnvironmentOr("MOCKTAIL_VSYNC", "auto"),
-        EnvironmentOr("MOCKTAIL_FRAME_RATE_LIMIT", "-1"));
+        vr_enabled ? EnvironmentOr("MOCKTAIL_VR_FRAME_RATE_LIMIT", "unlimited")
+                   : EnvironmentOr("MOCKTAIL_FRAME_RATE_LIMIT", "-1"));
  }();
  return policy;
 }
@@ -92,6 +92,34 @@ bool Etc2UploadByteCounts(EtcFormat format, const VkExtent3D& extent,
  return true;
 }

+bool Etc2ImageByteCounts(EtcFormat format, const VkExtent3D& extent,
+                         std::uint32_t mip_levels, std::uint32_t layers,
+                         std::uint32_t scale, VkDeviceSize* compressed,
+                         VkDeviceSize* decoded) {
+  if (extent.width == 0 || extent.height == 0 || extent.depth == 0 ||
+      mip_levels == 0 || layers == 0 || scale == 0 || compressed == nullptr ||
+      decoded == nullptr) {
+    return false;
+  }
+  const auto level = [](std::uint32_t size, std::uint32_t mip) {
+    return std::max<VkDeviceSize>(1, static_cast<VkDeviceSize>(size) >> mip);
+  };
+  VkDeviceSize compressed_total = 0;
+  VkDeviceSize decoded_total = 0;
+  for (std::uint32_t mip = 0; mip < mip_levels && mip < 32; ++mip) {
+    const VkDeviceSize depth = level(extent.depth, mip);
+    compressed_total += ((level(extent.width, mip) + 3) / 4) *
+                        ((level(extent.height, mip) + 3) / 4) * depth *
+                        EtcBlockBytes(format);
+    decoded_total += level(extent.width * scale, mip) *
+                     level(extent.height * scale, mip) * depth *
+                     EtcDecodedTexelBytes(format);
+  }
+  *compressed = compressed_total * layers;
+  *decoded = decoded_total * layers;
+  return true;
+}
+
 namespace {

 bool EmulationDisabledByEnvironment() {
@@ -207,8 +235,21 @@ struct ImageRecord {
  // Decoded level-0 texels of a scaled image; every host mip is resampled
  // from them so the texture keeps its detail at every draw size.
  std::shared_ptr<const RgbaImage> base;
+  EmulatedTextureBytes bytes;
 };

+// `now` is read under the lock that produced `totals`, so concurrent changes
+// reach the trace in the order they happened.
+void TraceTextureBytes(const EmulatedTextureBytes& totals, std::uint64_t now) {
+  ChromeTraceWriter* const trace = ActiveProfileTrace();
+  if (trace == nullptr) {
+    return;
+  }
+  constexpr double kMegabyte = 1024.0 * 1024.0;
+  trace->Counter("emulated texture (MB)", now, totals.decoded / kMegabyte);
+  trace->Counter("compressed texture (MB)", now, totals.compressed / kMegabyte);
+}
+
 bool IsColorFormat(EtcFormat format) {
  return format == EtcFormat::kEtc2Rgb8 || format == EtcFormat::kEtc2Rgb8A1 ||
         format == EtcFormat::kEtc2Rgba8;
@@ -669,6 +710,8 @@ struct VulkanEtc2Emulation::State {
  std::unordered_map<VkPhysicalDevice, bool> physical_devices;
  std::vector<std::unique_ptr<HostDevice>> devices;
  std::unordered_map<VkImage, ImageRecord> images;
+  // Sum over `images`; guarded by `mutex`.
+  EmulatedTextureBytes texture_bytes;
  std::unordered_map<VkBuffer, BufferBinding> buffers;
  std::unordered_map<VkDeviceMemory, Mapping> mappings;
  std::unordered_map<VkCommandBuffer, CommandRecord> commands;
@@ -1245,6 +1288,8 @@ void VulkanEtc2Emulation::DestroyDevice(VkDevice device) {
  // Nothing may free staging or the semaphore while a decode still writes it.
  state_->DrainDecodes();
  std::vector<std::unique_ptr<StagingBlock>> doomed;
+  EmulatedTextureBytes totals;
+  std::uint64_t now = 0;
  {
    std::lock_guard<std::mutex> lock(state_->mutex);
    for (auto it = state_->commands.begin(); it != state_->commands.end();) {
@@ -1265,11 +1310,20 @@ void VulkanEtc2Emulation::DestroyDevice(VkDevice device) {
      }
    }
    for (auto it = state_->images.begin(); it != state_->images.end();) {
-      it = it->second.device == device ? state_->images.erase(it) : std::next(it);
+      if (it->second.device == device) {
+        state_->texture_bytes.compressed -= it->second.bytes.compressed;
+        state_->texture_bytes.decoded -= it->second.bytes.decoded;
+        it = state_->images.erase(it);
+      } else {
+        ++it;
+      }
    }
+    totals = state_->texture_bytes;
+    now = TraceClockNanos();
    state_->has_commands.store(!state_->commands.empty(),
                               std::memory_order_release);
  }
+  TraceTextureBytes(totals, now);
  if (const HostDevice* dev = state_->Find(device); dev != nullptr) {
    for (const auto& block : doomed) {
      DestroyStagingBlock(*dev, *block);
@@ -1316,6 +1370,14 @@ VkResult VulkanEtc2Emulation::CreateImage(VkDevice device,
  }
  const VkResult result = dev->create_image(device, &host_info, allocator, image);
  if (result == VK_SUCCESS && image != nullptr) {
+    EmulatedTextureBytes bytes;
+    if (!Etc2ImageByteCounts(format.etc_format, create_info->extent,
+                             create_info->mipLevels, create_info->arrayLayers,
+                             scale, &bytes.compressed, &bytes.decoded)) {
+      bytes = {};
+    }
+    EmulatedTextureBytes totals;
+    std::uint64_t now = 0;
    {
      std::lock_guard<std::mutex> lock(state_->mutex);
      state_->images[*image] = {device,
@@ -1324,8 +1386,14 @@ VkResult VulkanEtc2Emulation::CreateImage(VkDevice device,
                                create_info->extent.width,
                                create_info->extent.height,
                                nullptr,
-                                nullptr};
+                                nullptr,
+                                bytes};
+      state_->texture_bytes.compressed += bytes.compressed;
+      state_->texture_bytes.decoded += bytes.decoded;
+      totals = state_->texture_bytes;
+      now = TraceClockNanos();
    }
+    TraceTextureBytes(totals, now);
    if (ShouldLog(&g_image_logs, 4)) {
      std::fprintf(stderr,
                   "  [vulkan] ETC2 image %ux%u mips=%u format=%d -> host "
@@ -1346,12 +1414,33 @@ void VulkanEtc2Emulation::DestroyImage(VkDevice device, VkImage image,
    return;
  }
  if (dev->emulated) {
-    std::lock_guard<std::mutex> lock(state_->mutex);
-    state_->images.erase(image);
+    EmulatedTextureBytes totals;
+    std::uint64_t now = 0;
+    bool changed = false;
+    {
+      std::lock_guard<std::mutex> lock(state_->mutex);
+      const auto it = state_->images.find(image);
+      if (it != state_->images.end()) {
+        state_->texture_bytes.compressed -= it->second.bytes.compressed;
+        state_->texture_bytes.decoded -= it->second.bytes.decoded;
+        state_->images.erase(it);
+        totals = state_->texture_bytes;
+        now = TraceClockNanos();
+        changed = true;
+      }
+    }
+    if (changed) {
+      TraceTextureBytes(totals, now);
+    }
  }
  dev->destroy_image(device, image, allocator);
 }

+EmulatedTextureBytes VulkanEtc2Emulation::TextureBytes() const {
+  std::lock_guard<std::mutex> lock(state_->mutex);
+  return state_->texture_bytes;
+}
+
 VkResult VulkanEtc2Emulation::CreateImageView(
    VkDevice device, const VkImageViewCreateInfo* create_info,
    const VkAllocationCallbacks* allocator, VkImageView* view) {
@@ -0,0 +1,18 @@
+#include "jni_method_names.h"
+
+#include <unordered_map>
+
+namespace jnivm::internal {
+
+JniMethod LookupJniMethod(std::string_view name) {
+  static const auto* const kMethods =
+      new std::unordered_map<std::string_view, JniMethod>{
+#define MOCKTAIL_JNI_METHOD_ENTRY(id, text) {text, JniMethod::id},
+          MOCKTAIL_JNI_METHOD_NAMES(MOCKTAIL_JNI_METHOD_ENTRY)
+#undef MOCKTAIL_JNI_METHOD_ENTRY
+      };
+  const auto it = kMethods->find(name);
+  return it == kMethods->end() ? JniMethod::kUnknown : it->second;
+}
+
+}  // namespace jnivm::internal
@@ -0,0 +1,266 @@
+#ifndef MOCKTAIL_JNIVM_JNI_METHOD_NAMES_H_
+#define MOCKTAIL_JNIVM_JNI_METHOD_NAMES_H_
+
+#include <cstdint>
+#include <string_view>
+
+namespace jnivm::internal {
+
+// Every Java method name the JNI dispatch matches on. GetMethodID and
+// GetStaticMethodID resolve a name to its entry once, so dispatch compares
+// enum values. A name that is not listed resolves to JniMethod::kUnknown.
+#define MOCKTAIL_JNI_METHOD_NAMES(X) \
+  X(kA, "a") \
+  X(kApply, "apply") \
+  X(kAttachObserver, "attachObserver") \
+  X(kBootstrapTheApp, "bootstrapTheApp") \
+  X(kCheckInit, "checkInit") \
+  X(kClose, "close") \
+  X(kCommit, "commit") \
+  X(kConnect, "connect") \
+  X(kConstructor, "<init>") \
+  X(kContains, "contains") \
+  X(kCurrentActivity, "currentActivity") \
+  X(kCurrentTimeMillis, "currentTimeMillis") \
+  X(kD, "d") \
+  X(kDeleteCurrentUserValues, "deleteCurrentUserValues") \
+  X(kDeleteSecureValue, "deleteSecureValue") \
+  X(kDeleteUserValues, "deleteUserValues") \
+  X(kDetachObserver, "detachObserver") \
+  X(kDispose, "dispose") \
+  X(kDoSubscribeProtocolMethodResponseRaw, "doSubscribeProtocolMethodResponseRaw") \
+  X(kEdit, "edit") \
+  X(kEnableBuiltInAEC, "enableBuiltInAEC") \
+  X(kEnableBuiltInAGC, "enableBuiltInAGC") \
+  X(kEnableBuiltInNS, "enableBuiltInNS") \
+  X(kF, "f") \
+  X(kFindClass, "findClass") \
+  X(kForName, "forName") \
+  X(kG, "g") \
+  X(kGameActivityHideKeyboard, "gameActivity_hideKeyboard") \
+  X(kGameActivityOnAppReady, "gameActivity_onAppReady") \
+  X(kGameActivityOnDidLogInReceived, "gameActivity_onDidLogInReceived") \
+  X(kGameActivityOnDidLogOutReceived, "gameActivity_onDidLogOutReceived") \
+  X(kGameActivityOnDidSignUp, "gameActivity_onDidSignUp") \
+  X(kGameActivityOnDidSwitchAccountReceived, "gameActivity_onDidSwitchAccountReceived") \
+  X(kGameActivityOnEngineInitialized, "gameActivity_onEngineInitialized") \
+  X(kGameActivityOnExperienceStart, "gameActivity_onExperienceStart") \
+  X(kGameActivityOnExperienceStop, "gameActivity_onExperienceStop") \
+  X(kGameActivityOnFlagsFailed, "gameActivity_onFlagsFailed") \
+  X(kGameActivityOnFlagsLoaded, "gameActivity_onFlagsLoaded") \
+  X(kGameActivityOnGameLoaded, "gameActivity_onGameLoaded") \
+  X(kGameActivityOnLuaAppDidReturn, "gameActivity_onLuaAppDidReturn") \
+  X(kGameActivityOnLuaTextBoxChanged, "gameActivity_onLuaTextBoxChanged") \
+  X(kGameActivityOnLuaTextBoxPropertyChanged, "gameActivity_onLuaTextBoxPropertyChanged") \
+  X(kGameActivityOnMotionEventListening, "gameActivity_onMotionEventListening") \
+  X(kGameActivityOnRestartLuaApp, "gameActivity_onRestartLuaApp") \
+  X(kGameActivityOnScanQrCode, "gameActivity_onScanQrCode") \
+  X(kGameActivityOnScreenOrientationChanged, "gameActivity_onScreenOrientationChanged") \
+  X(kGameActivityOnScreenshotReady, "gameActivity_onScreenshotReady") \
+  X(kGameActivitySetAppUpgradeStatus, "gameActivity_setAppUpgradeStatus") \
+  X(kGameActivityShowKeyboard, "gameActivity_showKeyboard") \
+  X(kGameDidLeave, "gameDidLeave") \
+  X(kGet, "get") \
+  X(kGetAbsolutePath, "getAbsolutePath") \
+  X(kGetActivity, "getActivity") \
+  X(kGetAlternateName, "getAlternateName") \
+  X(kGetAndroidApiVersion, "getAndroidApiVersion") \
+  X(kGetApiBaseUrl, "getApiBaseUrl") \
+  X(kGetApiGatewayUrl, "getApiGatewayUrl") \
+  X(kGetApiVersion, "getApiVersion") \
+  X(kGetApplicationContext, "getApplicationContext") \
+  X(kGetApplicationInfo, "getApplicationInfo") \
+  X(kGetAppVersion, "getAppVersion") \
+  X(kGetAssetManager, "getAssetManager") \
+  X(kGetAssets, "getAssets") \
+  X(kGetBaseContext, "getBaseContext") \
+  X(kGetBaseURL, "getBaseURL") \
+  X(kGetBaseUrl, "getBaseUrl") \
+  X(kGetBrand, "getBrand") \
+  X(kGetBufferSizeInFrames, "getBufferSizeInFrames") \
+  X(kGetBuildId, "getBuildId") \
+  X(kGetBuildRelease, "getBuildRelease") \
+  X(kGetBuildType, "getBuildType") \
+  X(kGetBytes, "getBytes") \
+  X(kGetCacheDir, "getCacheDir") \
+  X(kGetCanonicalPath, "getCanonicalPath") \
+  X(kGetClassLoader, "getClassLoader") \
+  X(kGetClientSettingsUrl, "getClientSettingsUrl") \
+  X(kGetContext, "getContext") \
+  X(kGetCookie, "getCookie") \
+  X(kGetCurrentText, "getCurrentText") \
+  X(kGetCurrentTextBoxInfo, "getCurrentTextBoxInfo") \
+  X(kGetCurrentUser, "getCurrentUser") \
+  X(kGetDecorView, "getDecorView") \
+  X(kGetDefaultDisplay, "getDefaultDisplay") \
+  X(kGetDensityDpi, "getDensityDpi") \
+  X(kGetDevice, "getDevice") \
+  X(kGetDeviceManufacturer, "getDeviceManufacturer") \
+  X(kGetDeviceModel, "getDeviceModel") \
+  X(kGetDeviceStaticParams, "getDeviceStaticParams") \
+  X(kGetDisplay, "getDisplay") \
+  X(kGetDisplayName, "getDisplayName") \
+  X(kGetExternalFilesDir, "getExternalFilesDir") \
+  X(kGetFilesDir, "getFilesDir") \
+  X(kGetGameLocale, "getGameLocale") \
+  X(kGetHeight, "getHeight") \
+  X(kGetHint, "getHint") \
+  X(kGetHolder, "getHolder") \
+  X(kGetId, "getId") \
+  X(kGetImplementation, "getImplementation") \
+  X(kGetInstallerPackageName, "getInstallerPackageName") \
+  X(kGetInt, "getInt") \
+  X(kGetLastLoggedInUser, "getLastLoggedInUser") \
+  X(kGetLastLoggedInUserId, "getLastLoggedInUserId") \
+  X(kGetLastRaw, "getLastRaw") \
+  X(kGetLocale, "getLocale") \
+  X(kGetManufacturer, "getManufacturer") \
+  X(kGetMessageBus, "getMessageBus") \
+  X(kGetMessageBusConnection, "getMessageBusConnection") \
+  X(kGetMode, "getMode") \
+  X(kGetModel, "getModel") \
+  X(kGetNativeHelper, "getNativeHelper") \
+  X(kGetNativeTextBoxInfo, "getNativeTextBoxInfo") \
+  X(kGetOutputBlockSize, "getOutputBlockSize") \
+  X(kGetOutputSampleRate, "getOutputSampleRate") \
+  X(kGetPackageInfo, "getPackageInfo") \
+  X(kGetPackageManager, "getPackageManager") \
+  X(kGetPackageName, "getPackageName") \
+  X(kGetPath, "getPath") \
+  X(kGetPlaceholder, "getPlaceholder") \
+  X(kGetPlatformName, "getPlatformName") \
+  X(kGetPlatformSystemDialogHandler, "getPlatformSystemDialogHandler") \
+  X(kGetProduct, "getProduct") \
+  X(kGetProperty, "getProperty") \
+  X(kGetPublicIPv4Addresseses, "getPublicIPv4Addresseses") \
+  X(kGetRefreshRate, "getRefreshRate") \
+  X(kGetResources, "getResources") \
+  X(kGetRobloxLocale, "getRobloxLocale") \
+  X(kGetRootView, "getRootView") \
+  X(kGetRotation, "getRotation") \
+  X(kGetScreenHeight, "getScreenHeight") \
+  X(kGetScreenWidth, "getScreenWidth") \
+  X(kGetSdkVersion, "getSdkVersion") \
+  X(kGetSecureValue, "getSecureValue") \
+  X(kGetSecureValueForCurrentUser, "getSecureValueForCurrentUser") \
+  X(kGetSecureValueForUser, "getSecureValueForUser") \
+  X(kGetSettingsUrl, "getSettingsUrl") \
+  X(kGetSharedPreferences, "getSharedPreferences") \
+  X(kGetStreamMaxVolume, "getStreamMaxVolume") \
+  X(kGetStreamVolume, "getStreamVolume") \
+  X(kGetString, "getString") \
+  X(kGetSurface, "getSurface") \
+  X(kGetSystemDialogHandler, "getSystemDialogHandler") \
+  X(kGetSystemService, "getSystemService") \
+  X(kGetSystemTheme, "getSystemTheme") \
+  X(kGetTargetSdkVersion, "getTargetSdkVersion") \
+  X(kGetText, "getText") \
+  X(kGetTextBoxInfo, "getTextBoxInfo") \
+  X(kGetTheme, "getTheme") \
+  X(kGetUserId, "getUserId") \
+  X(kGetUsername, "getUsername") \
+  X(kGetUsers, "getUsers") \
+  X(kGetVideoCodecs, "getVideoCodecs") \
+  X(kGetWidth, "getWidth") \
+  X(kGetWindow, "getWindow") \
+  X(kGetWindowManager, "getWindowManager") \
+  X(kGetWWWBaseUrl, "getWWWBaseUrl") \
+  X(kGetWwwBaseUrl, "getWwwBaseUrl") \
+  X(kH, "h") \
+  X(kHasNext, "hasNext") \
+  X(kHasSystemFeature, "hasSystemFeature") \
+  X(kHideKeyboard, "hideKeyboard") \
+  X(kIdentityHashCode, "identityHashCode") \
+  X(kInit, "init") \
+  X(kInitPlayout, "initPlayout") \
+  X(kInitRecording, "initRecording") \
+  X(kIsAAudioSupported, "isAAudioSupported") \
+  X(kIsAudioConfigVerified, "isAudioConfigVerified") \
+  X(kIsAudioSourceMatchingRecordingSession, "isAudioSourceMatchingRecordingSession") \
+  X(kIsAvailable, "isAvailable") \
+  X(kIsBluetoothA2dpOn, "isBluetoothA2dpOn") \
+  X(kIsBluetoothOn, "isBluetoothOn") \
+  X(kIsBluetoothScoOn, "isBluetoothScoOn") \
+  X(kIsChangingConfigurations, "isChangingConfigurations") \
+  X(kIsCommunicationModeEnabled, "isCommunicationModeEnabled") \
+  X(kIsConnected, "isConnected") \
+  X(kIsDestroyed, "isDestroyed") \
+  X(kIsDeviceBlacklistedForOpenSLESUsage, "isDeviceBlacklistedForOpenSLESUsage") \
+  X(kIsEmpty, "isEmpty") \
+  X(kIsFinishing, "isFinishing") \
+  X(kIsLowLatencyInputSupported, "isLowLatencyInputSupported") \
+  X(kIsLowLatencyOutputSupported, "isLowLatencyOutputSupported") \
+  X(kIsProAudioSupported, "isProAudioSupported") \
+  X(kIsSystemThemeAvailable, "isSystemThemeAvailable") \
+  X(kIsValid, "isValid") \
+  X(kIterator, "iterator") \
+  X(kK1, "k1") \
+  X(kL0, "l0") \
+  X(kLength, "length") \
+  X(kLoadClass, "loadClass") \
+  X(kLowLatencyFlag, "lowLatencyFlag") \
+  X(kNanoTime, "nanoTime") \
+  X(kNativeGetCookiesForDomain, "nativeGetCookiesForDomain") \
+  X(kNativeGetCookiesInNetscapeFormat, "nativeGetCookiesInNetscapeFormat") \
+  X(kNativeGetTextBoxInfo, "nativeGetTextBoxInfo") \
+  X(kOnAppBridgeNotification, "onAppBridgeNotification") \
+  X(kOnDataModelNotificationCallback, "onDataModelNotificationCallback") \
+  X(kOnItemSet, "onItemSet") \
+  X(kOnLuaTextBoxChangedCallback, "onLuaTextBoxChangedCallback") \
+  X(kOnLuaTextBoxPropertyChangedCallback, "onLuaTextBoxPropertyChangedCallback") \
+  X(kOnSetCookie, "onSetCookie") \
+  X(kOpen, "open") \
+  X(kOpenNativeOverlay, "openNativeOverlay") \
+  X(kOpenWebActivity, "openWebActivity") \
+  X(kOptString, "optString") \
+  X(kOutputAAudioHeadphonesChanged, "OutputAAudioHeadphonesChanged") \
+  X(kProAudioFlag, "proAudioFlag") \
+  X(kQ, "q") \
+  X(kRequestOrientationAsDefault, "requestOrientationAsDefault") \
+  X(kRequestResponse, "requestResponse") \
+  X(kRestartInput, "restartInput") \
+  X(kRun, "run") \
+  X(kRunOnUiThread, "runOnUiThread") \
+  X(kSetAppBridgeNotificationListener, "setAppBridgeNotificationListener") \
+  X(kSetBaseUrl, "setBaseUrl") \
+  X(kSetCookie, "setCookie") \
+  X(kSetCookiesFromDisk, "setCookiesFromDisk") \
+  X(kSetCurrentUser, "setCurrentUser") \
+  X(kSetImeEditorInfoFields, "setImeEditorInfoFields") \
+  X(kSetImplementation, "setImplementation") \
+  X(kSetMicrophoneMute, "setMicrophoneMute") \
+  X(kSetRequestHandler, "setRequestHandler") \
+  X(kSetRequestHandlerRaw, "setRequestHandlerRaw") \
+  X(kSetSecureValue, "setSecureValue") \
+  X(kSetSecureValueForCurrentUser, "setSecureValueForCurrentUser") \
+  X(kSetSecureValueForUser, "setSecureValueForUser") \
+  X(kSetSoftKeyboardActive, "setSoftKeyboardActive") \
+  X(kSetState, "setState") \
+  X(kSetStreamVolume, "setStreamVolume") \
+  X(kSetWindowFlags, "setWindowFlags") \
+  X(kShowKeyboard, "showKeyboard") \
+  X(kShowLeaveAppPrompt, "showLeaveAppPrompt") \
+  X(kSize, "size") \
+  X(kStartPlayout, "startPlayout") \
+  X(kStartRecording, "startRecording") \
+  X(kStopPlayout, "stopPlayout") \
+  X(kStopRecording, "stopRecording") \
+  X(kSubscribe, "subscribe") \
+  X(kSubscribeProtocolMethodResponseRaw, "subscribeProtocolMethodResponseRaw") \
+  X(kSupportsAAudio, "supportsAAudio") \
+  X(kSupportsLowLatency, "supportsLowLatency") \
+  X(kSyncCookiesFromEngine, "syncCookiesFromEngine") \
+  X(kWrite, "write")
+
+enum class JniMethod : std::uint16_t {
+  kUnknown = 0,
+#define MOCKTAIL_JNI_METHOD_ENUMERATOR(id, name) id,
+  MOCKTAIL_JNI_METHOD_NAMES(MOCKTAIL_JNI_METHOD_ENUMERATOR)
+#undef MOCKTAIL_JNI_METHOD_ENUMERATOR
+};
+
+JniMethod LookupJniMethod(std::string_view name);
+
+}  // namespace jnivm::internal
+
+#endif  // MOCKTAIL_JNIVM_JNI_METHOD_NAMES_H_
@@ -61,18 +61,22 @@
 #include "linker/linker.h"
 #include "mocktail/graphics/bionic_egl_bridge.h"
 #include "mocktail/graphics/chrome_trace_writer.h"
+#include "mocktail/vr/roblox_vr_device_bridge.h"
 #include "runtime/engine_pump_rest.h"
 #include "runtime/device_memory_profile.h"
 #include "runtime/display_size.h"
 #include "runtime/environment.h"
 #include "runtime/discord_rpc.h"
+#include "runtime/luau_codegen_switch.h"
 #include "runtime/jnivm_platform_web_callbacks.h"
 #include "runtime/owned_pthread.h"
 #include "runtime/platform_cache_migration.h"
+#include "runtime/asset_overlay_names.h"
 #include "runtime/roblox_app_lifecycle.h"
 #include "runtime/roblox_capability_resolver.h"
 #include "runtime/roblox_platform_web_symbols.h"
 #include "runtime/roblox_experience_composition.h"
+#include "runtime/roblox_haptic_protocol_bridge.h"
 #include "runtime/roblox_game_session_native_adapter.h"
 #include "runtime/roblox_window_input_runtime.h"
 #include "runtime/roblox_text_input_jni_bridge.h"
@@ -212,6 +216,7 @@ using NativeSendGameLoadedFn = void (*)(JNIEnv*, jclass, jstring, jstring,
 using NativePassSupportedRefreshRatesFn = void (*)(JNIEnv*, jclass,
                                                   jfloatArray);
 using NativePassCurrentDisplayRefreshRateFn = void (*)(JNIEnv*, jclass, jfloat);
+using NativeUpdateMobileHapticsStateFn = void (*)(JNIEnv*, jclass, jboolean, jstring);
 using NativeSetStringParamFn = void (*)(JNIEnv*, jclass, jstring);
 using NativeSetBaseUrlFn = void (*)(JNIEnv*, jclass, jstring, jstring);
 using NativeSetTaskSchedulerBackgroundModeFn = void (*)(JNIEnv*, jclass,
@@ -379,6 +384,7 @@ struct EngineStartupContext {
  NativePassSupportedRefreshRatesFn native_pass_supported_refresh_rates;
  NativePassCurrentDisplayRefreshRateFn native_pass_current_display_refresh_rate;
  NativeNoArgFn native_start_lua_app_dm;
+  NativeUpdateMobileHapticsStateFn native_update_mobile_haptics_state;
 };


@@ -1963,6 +1969,48 @@ extern "C" void MocktailConstructorWrapper() {
  MaybePrintLibRobloxConstructorSummary(idx);
 }

+// Unmaps the rbxasset:// names that have a file in the asset overlay folder, so
+// Roblox opens those files instead of downloading the stock asset. Must run
+// before any libroblox code does: the segment loses PROT_EXEC while it is
+// written.
+void DisableOverlaidAssetMappings(uintptr_t base) {
+  const std::vector<std::string> names = mocktail::runtime::OverlayRbxAssetNames(
+      CurrentRuntimePaths().asset_overlay_dir());
+  const long page_size = sysconf(_SC_PAGESIZE);
+  if (names.empty() || page_size <= 0) {
+    return;
+  }
+  const auto* header = reinterpret_cast<const Elf64_Ehdr*>(base);
+  const auto* segments =
+      reinterpret_cast<const Elf64_Phdr*>(base + header->e_phoff);
+  std::size_t changed = 0;
+  for (std::size_t index = 0; index < header->e_phnum; ++index) {
+    const Elf64_Phdr& segment = segments[index];
+    if (segment.p_type != PT_LOAD || (segment.p_flags & PF_W) != 0 ||
+        segment.p_filesz == 0) {
+      continue;
+    }
+    const uintptr_t begin = base + segment.p_vaddr;
+    const uintptr_t page_mask = static_cast<uintptr_t>(page_size) - 1;
+    const uintptr_t page_begin = begin & ~page_mask;
+    const std::size_t span =
+        ((begin + segment.p_filesz + page_mask) & ~page_mask) - page_begin;
+    const int original =
+        PROT_READ | ((segment.p_flags & PF_X) != 0 ? PROT_EXEC : 0);
+    if (mprotect(reinterpret_cast<void*>(page_begin), span,
+                 PROT_READ | PROT_WRITE) != 0) {
+      continue;
+    }
+    changed += mocktail::runtime::DisableAssetNameMappings(
+        reinterpret_cast<std::uint8_t*>(begin), segment.p_filesz, names);
+    mprotect(reinterpret_cast<void*>(page_begin), span, original);
+  }
+  std::cout << "  [asset] overlay holds " << names.size()
+            << " rbxasset file(s); unmapped " << changed
+            << " download name(s)\n"
+            << std::flush;
+}
+
 extern "C" void mocktail_before_soinfo_constructors(const char* realpath,
                                                    uintptr_t base) {
  if (realpath == nullptr || std::strstr(realpath, "libroblox.so") == nullptr ||
@@ -1971,6 +2019,7 @@ extern "C" void mocktail_before_soinfo_constructors(const char* realpath,
  }

  g_libroblox_base = base;
+  DisableOverlaidAssetMappings(base);
  g_mocktail_abort_libroblox_base = base;
  g_libroblox_base_static = base;

@@ -2197,8 +2246,12 @@ void MocktailSetAssetPath(JNIEnv* env, jstring asset_path) {
  if (path.empty()) {
    path = DefaultAssetPath();
  }
-  setenv("MOCKTAIL_ASSET_ROOT", path.c_str(), 1);
-  std::cout << "  [engine] asset root set to " << path << '\n' << std::flush;
+  std::filesystem::path root_path(path);
+  if (root_path.filename() == "content") {
+    root_path = root_path.parent_path();
+  }
+  setenv("MOCKTAIL_ASSET_ROOT", root_path.c_str(), 1);
+  std::cout << "  [engine] asset root set to " << root_path.string() << '\n' << std::flush;
 }

 void MocktailAppBridgeInit(JNIEnv* env, jstring app_params) {
@@ -2637,7 +2690,8 @@ jobject BuildAppBridgeInitParams(JNIEnv* env, jstring client_settings,
  SetStringField(env, params, "userAgent", user_agent.c_str());
  SetBooleanField(env, params, "isTablet", JNI_FALSE);
  SetBooleanField(env, params, "isPotato", JNI_FALSE);
-  SetBooleanField(env, params, "isVrDevice", JNI_FALSE);
+  SetBooleanField(env, params, "isVrDevice",
+                  IsEnabled("MOCKTAIL_VR_ENABLED") ? JNI_TRUE : JNI_FALSE);
  SetStringField(env, params, "buildVariant", "googleProdRelease");
  SetObjectField(env, params, "vrContext", "Landroid/app/Activity;",
                 activity);
@@ -4264,6 +4318,23 @@ std::cerr << "  [engine] nativeAppBridgeV2InitWithParams recovered\n"
    std::cout << "  [engine] updateAppUISizes returned\n" << std::flush;
  }

+  if (context->native_update_mobile_haptics_state) {
+    env = ensure_env();
+    std::cout << "  [engine] NativeGLInterface.nativeUpdateMobileHapticsState\n"
+              << std::flush;
+    const std::string motors_json =
+        mocktail::runtime::RobloxHapticProtocolBridge::GetMotorsJson();
+    jstring motors_str = env->NewStringUTF(motors_json.c_str());
+    if (motors_str != nullptr) {
+      context->native_update_mobile_haptics_state(env, native_gl_class,
+                                                  JNI_TRUE, motors_str);
+      env->DeleteLocalRef(motors_str);
+    }
+    std::cout
+        << "  [engine] NativeGLInterface.nativeUpdateMobileHapticsState returned\n"
+        << std::flush;
+  }
+
  int init_delay_ms = GetEnvInt("MOCKTAIL_APPBRIDGE_INIT_DELAY_MS", 0);
  if (init_delay_ms > 0) {
    std::cout << "  [engine] wait after AppBridge init: " << init_delay_ms
@@ -4544,6 +4615,16 @@ std::cerr << "  [engine] nativeAppBridgeV2InitWithParams recovered\n"
      std::cout
          << "  [engine] nativeAppBridgeV2SendAppEventOnGameLoaded returned\n"
          << std::flush;
+      if (context->native_update_mobile_haptics_state) {
+        const std::string motors_json =
+            mocktail::runtime::RobloxHapticProtocolBridge::GetMotorsJson();
+        jstring motors_str = env->NewStringUTF(motors_json.c_str());
+        if (motors_str != nullptr) {
+          context->native_update_mobile_haptics_state(env, native_gl_class,
+                                                      JNI_TRUE, motors_str);
+          env->DeleteLocalRef(motors_str);
+        }
+      }
    }
  }

@@ -4612,6 +4693,27 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
                << "; continuing without Rich Presence\n";
    }
  }
+  mocktail::runtime::LuauCodegenMenuSwitch luau_codegen_switch(
+      [&process_environment]() -> std::uint8_t* {
+        if (process_environment.GetOr("MOCKTAIL_LUAU_CODEGEN_MENU_SWITCH",
+                                      "0") != "1") {
+          return nullptr;
+        }
+        const std::uintptr_t base = g_libroblox_base;
+        std::uint8_t* flag = mocktail::runtime::FindFastFlagValue(
+            mocktail::runtime::LoadedImageSegments(base),
+            mocktail::runtime::kLuauCodegenAllFastFlagName);
+        if (flag == nullptr) {
+          std::cerr << "  [luau-codegen] DebugLuauCodegenAll not found; "
+                       "leaving it on in games\n";
+        } else {
+          std::cout << "  [luau-codegen] menus-only switch at +0x" << std::hex
+                    << (reinterpret_cast<std::uintptr_t>(flag) - base)
+                    << std::dec << '\n';
+        }
+        return flag;
+      },
+      discord_rpc.observer());
  const mocktail::runtime::InputCapabilityConfig& input_capabilities =
      runtime_config.input_capabilities();
  if (!runtime_config.frame_rate().valid()) {
@@ -4619,6 +4721,11 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
                 "-1, display, unlimited, or a positive integer\n";
    return EXIT_FAILURE;
  }
+  if (!runtime_config.vr_frame_rate().valid()) {
+    std::cerr << "[FATAL] Invalid MOCKTAIL_VR_FRAME_RATE_LIMIT; expected "
+                 "-1, display, unlimited, or a positive integer\n";
+    return EXIT_FAILURE;
+  }
  if (!runtime_config.theme_mode_valid()) {
    std::cerr
        << "[FATAL] Invalid MOCKTAIL_THEME; expected roblox, system, light, "
@@ -4680,8 +4787,14 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
    return EXIT_FAILURE;
  }

-  const mocktail::compat::BuildProfile& build_profile =
-      *profile_result.profile;
+  const mocktail::compat::BuildProfile& build_profile = *profile_result.profile;
+  if (IsEnabled("MOCKTAIL_VR_ENABLED") &&
+      mocktail::vr::FindRobloxVrDeviceProfile(build_profile.elf_build_id) ==
+          nullptr) {
+    std::cerr << "[FATAL] Experimental Roblox VR has no verified profile for "
+              << build_profile.elf_build_id << "\n";
+    return EXIT_FAILURE;
+  }
  const mocktail::compat::HostAbiProfile* host_abi_profile =
      mocktail::compat::FindHostAbiProfile(build_profile.elf_build_id);
  const bool experiment_allowed =
@@ -5831,6 +5944,20 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
  std::cout << "  [linker] Bionic unwind metadata validated for libroblox\n"
            << std::flush;

+  // The experimental VR bridge is armed only for --vr on an exact supported
+  // Build ID. It validates its machine contracts and interposes the
+  // DebugDeviceVR vtable slots after relocations and before guest startup
+  // can create the object. A no-op success while no bridge is armed.
+  if (const mocktail::Status vr_activation =
+          mocktail::vr::NotifyRobloxVrImageLoaded(
+              linker::FindLoadedAndroidLibraryBase("libroblox"));
+      !vr_activation.ok()) {
+    std::cerr << "\n[FATAL] Experimental Roblox VR bridge activation "
+                 "failed: "
+              << vr_activation.message() << '\n';
+    return EXIT_FAILURE;
+  }
+
  // The pre-constructor hook owns installation; repeating arena setup here is
  // not idempotent.
  if (HostAbiExperimentRequested() &&
@@ -6007,6 +6134,8 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
      eager_permissions_bridge;
  std::unique_ptr<mocktail::runtime::RobloxCallProtocolBridge>
      eager_call_protocol_bridge;
+  std::unique_ptr<mocktail::runtime::RobloxHapticProtocolBridge>
+      eager_haptic_protocol_bridge;
  std::shared_ptr<ExperienceLifecycleTarget> experience_lifecycle_target;
  std::shared_ptr<mocktail::runtime::RobloxWindowInputRuntime>
      window_input_runtime;
@@ -6303,6 +6432,14 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
            roblox_handle,
            "Java_com_roblox_engine_jni_NativeGLInterface_"
            "nativeAppBridgeV2SendAppEventOnGameLoaded"));
+    auto* native_update_mobile_haptics_state =
+        mocktail::runtime::RobloxHapticProtocolBridge::EnabledForThisSession()
+            ? reinterpret_cast<NativeUpdateMobileHapticsStateFn>(
+                  linker::ResolveSymbol(
+                      roblox_handle,
+                      "Java_com_roblox_engine_jni_NativeGLInterface_"
+                      "nativeUpdateMobileHapticsState"))
+            : nullptr;
    auto* native_set_asset_path =
        reinterpret_cast<NativeSetStringParamFn>(linker::ResolveSymbol(
            roblox_handle,
@@ -6381,6 +6518,10 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
              << reinterpret_cast<const void*>(native_send_app_ready) << '\n'
              << "    native_send_game_loaded="
              << reinterpret_cast<const void*>(native_send_game_loaded) << '\n'
+              << "    native_update_mobile_haptics_state="
+              << reinterpret_cast<const void*>(
+                     native_update_mobile_haptics_state)
+              << '\n'
              << "    native_start_lua_app_dm="
              << reinterpret_cast<const void*>(native_start_lua_app_dm) << '\n'
              << "    native_call_messages_from_main_thread="
@@ -6721,9 +6862,17 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
      eager_call_protocol_bridge =
          std::make_unique<mocktail::runtime::RobloxCallProtocolBridge>(
              environment, symbols.permissions, objects);
+      if (mocktail::runtime::RobloxHapticProtocolBridge::
+              EnabledForThisSession()) {
+        eager_haptic_protocol_bridge =
+            std::make_unique<mocktail::runtime::RobloxHapticProtocolBridge>(
+                environment, symbols.permissions, objects);
+      }
      status = eager_permissions_bridge->Initialize();
      if (status.ok())
        status = eager_call_protocol_bridge->Initialize();
+      if (status.ok() && eager_haptic_protocol_bridge != nullptr)
+        status = eager_haptic_protocol_bridge->Initialize();
      env->DeleteLocalRef(bus);
      if (!status.ok()) {
        std::cerr << "[FATAL] GAME platform protocols did not initialize: "
@@ -6790,7 +6939,7 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
              jni_factory, present_boundary, std::move(surface_config),
              &dependencies.roblox_credential(),
              mocktail::runtime::RobloxExperienceSurfaceProvider{},
-              discord_rpc.observer(),
+              luau_codegen_switch.observer(),
              dependencies.clear_persisted_web_view_cookie(),
              runtime_config.microphone_enabled(),
              platform_web_symbols.account);
@@ -6885,7 +7034,8 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
        native_on_fragment_start,
        native_pass_supported_refresh_rates,
        native_pass_current_display_refresh_rate,
-        native_start_lua_app_dm};
+        native_start_lua_app_dm,
+        native_update_mobile_haptics_state};
    if (game_session_runtime != nullptr) {
      if (!game_present_observer.Register(
              &mocktail::runtime::RobloxGameSessionRuntime::
@@ -7111,6 +7261,12 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
    while (true) {
      const uint64_t fps_tick_start_ns = fps_trace ? MonotonicNanos() : 0;
      const bool keep_window_open = mocktail::window::PumpEvents();
+      // Deliver XR tracked-controller input on the same thread and through the
+      // same router as SDL input, once per loop iteration after the SDL pump.
+      // Inert in non-VR builds or while no OpenXR controller layer is active.
+      if (window_input_runtime != nullptr) {
+        window_input_runtime->DrainXrControllers();
+      }
      game_surface_events_completed = drain_game_surface_events();
      const uint64_t fps_after_sdl_ns = fps_trace ? MonotonicNanos() : 0;
      if (!game_surface_events_completed || !keep_window_open) {
@@ -7226,6 +7382,10 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
      input_shutdown_completed = window_input_runtime->Shutdown().ok() &&
                                 input_shutdown_completed;
    }
+    if (eager_haptic_protocol_bridge != nullptr) {
+      (void)eager_haptic_protocol_bridge->Shutdown();
+      eager_haptic_protocol_bridge.reset();
+    }
    if (eager_call_protocol_bridge != nullptr) {
      (void)eager_call_protocol_bridge->Shutdown();
      eager_call_protocol_bridge.reset();
@@ -24,6 +24,11 @@
 #include "mocktail/audio/fmod_jni_audio_bridge.h"
 #include "mocktail/audio/webrtc_jni_audio_bridge.h"
 #include "mocktail/audio/roblox_output_device_bridge.h"
+#include "mocktail/vr/headset_detection.h"
+#include "mocktail/vr/openxr_backend.h"
+#include "mocktail/vr/openxr_probe.h"
+#include "mocktail/vr/roblox_vr_device_bridge.h"
+#include "mocktail/vr/virtual_keyboard.h"
 #include "runtime/auth_runtime_composition.h"
 #include "runtime/command_line.h"
 #include "runtime/crash_report_policy.h"
@@ -33,6 +38,7 @@
 #include "runtime/fleasion.h"
 #include "runtime/game_mode.h"
 #include "runtime/graphics_launch_policy.h"
+#include "runtime/luau_codegen_switch.h"
 #include "runtime/memory_limit.h"
 #include "runtime/payload_update_preflight.h"
 #include "runtime/performance_policy.h"
@@ -42,6 +48,8 @@
 #include "runtime/roblox_desktop_app_policy.h"
 #include "runtime/roblox_experience_launch_bridge.h"
 #include "runtime/roblox_fullscreen_runtime_bridge.h"
+#include "runtime/roblox_text_display_state.h"
+#include "runtime/roblox_text_editor.h"
 #include "runtime/runtime_config_bootstrap.h"
 #include "runtime/runtime_config_file.h"
 #include "runtime/runtime_paths.h"
@@ -245,6 +253,11 @@ void ConfigureHostDriverEnvironment() {

 int main(int argc, char* argv[]) {
  ConfigureHostDriverEnvironment();
+  // vr.mode: auto asks SteamVR for a headset from a copy of this process.
+  if (const char* probe = std::getenv(mocktail::vr::kHeadsetProbeEnvironment);
+      probe != nullptr && std::string_view(probe) == "1") {
+    return mocktail::vr::RunHeadsetProbeChild();
+  }
  const auto process_started_at = std::chrono::system_clock::now();
  mocktail::runtime::CommandLineParseResult command_line =
      mocktail::runtime::ParseCommandLine(argc, argv);
@@ -279,6 +292,7 @@ int main(int argc, char* argv[]) {
  }

  const mocktail::runtime::ProcessEnvironment environment;
+  const bool vr_requested = environment.HasNonEmpty("MOCKTAIL_VR_ENABLED");
  const std::string built_in_compatibility_manifest = environment.GetOr(
      "MOCKTAIL_UPDATE_COMPATIBILITY_PATH",
      environment.GetOr("MOCKTAIL_COMPATIBILITY_MANIFEST",
@@ -322,6 +336,17 @@ int main(int argc, char* argv[]) {
  }
  mocktail::runtime::ScrubCommandLineLaunchArguments(&command_line.options,
                                                     argc, argv);
+
+  // Reject --vr in a build without OpenXR before touching any data or state
+  // directories. A vr.enabled config is checked once the config is loaded.
+  const std::string vr_request = environment.GetOr("MOCKTAIL_VR_ENABLED", "");
+  if ((vr_request == "1" || vr_request == "true" || vr_request == "on") &&
+      !mocktail::vr::IsOpenXrSupportCompiled()) {
+    std::cerr << "  [vr] This build does not include OpenXR support. "
+                 "Use a VR-enabled build of Mocktail; refusing to start "
+                 "Roblox with --vr in a non-VR build.\n";
+    return EXIT_FAILURE;
+  }
  mocktail::runtime::SessionLog session_log;
  mocktail::runtime::FailureSupportBundleGuard support_bundle_guard(
      environment, paths,
@@ -391,6 +416,41 @@ int main(int argc, char* argv[]) {
    }
    return EXIT_FAILURE;
  }
+  if (command_line.options.mode == mocktail::runtime::CommandMode::kRun &&
+      runtime_config.config.vr_mode() == mocktail::runtime::VrMode::kAuto) {
+    std::error_code self_error;
+    const std::filesystem::path self =
+        std::filesystem::read_symlink("/proc/self/exe", self_error);
+    const mocktail::vr::HeadsetDetection detection =
+        mocktail::vr::DetectSteamVrHeadset(self_error ? std::string()
+                                                      : self.string());
+    std::cerr << "  [vr] vr.mode is auto: " << detection.reason
+              << (detection.headset ? "; starting in VR\n"
+                                    : "; starting on the desktop\n");
+    if (detection.headset) {
+      // A detected headset is not an explicit --vr: a Roblox build without
+      // VR support still starts on the desktop.
+      if (setenv("MOCKTAIL_VR_ENABLED", "1", 1) != 0) {
+        std::cerr << "[FATAL] Cannot enable VR for the detected headset\n";
+        return EXIT_FAILURE;
+      }
+      runtime_config = mocktail::runtime::LoadRuntimeConfig(
+          environment, paths.config_file());
+      if (!runtime_config) {
+        std::cerr << "[FATAL] Cannot load " << paths.config_file() << ": "
+                  << runtime_config.error << '\n';
+        return EXIT_FAILURE;
+      }
+    }
+  }
+  if (runtime_config.config.vr_enabled() &&
+      !mocktail::vr::IsOpenXrSupportCompiled()) {
+    std::cerr << "  [vr] This build does not include OpenXR support, but "
+                 "VR is on; set vr.mode to off or auto in "
+              << paths.config_file()
+              << ".\n";
+    return EXIT_FAILURE;
+  }
  if (runtime_config.config.use_system_proxy()) {
    const mocktail::runtime::SystemProxyResult system_proxy =
        mocktail::runtime::ResolveSystemProxy();
@@ -612,6 +672,10 @@ int main(int argc, char* argv[]) {
      std::cerr << "[FATAL] Cannot bind assets to explicit Roblox library\n";
      return EXIT_FAILURE;
    }
+    const std::filesystem::path adjacent_root =
+        adjacent_assets.filename() == "content" ? adjacent_assets.parent_path()
+                                                : adjacent_assets;
+    setenv("MOCKTAIL_ASSET_ROOT", adjacent_root.c_str(), 1);
    std::cout << "  [runtime] explicit Roblox library uses adjacent assets: "
              << adjacent_assets << '\n';
  }
@@ -703,8 +767,13 @@ int main(int argc, char* argv[]) {
      if ((needs_active_library &&
           setenv("ROBLOX_LIB_PATH", active.roblox_library.c_str(), 1) != 0) ||
          (needs_active_assets &&
-           setenv("MOCKTAIL_ASSET_PATH", active.assets_content.c_str(), 1) !=
-               0)) {
+           (setenv("MOCKTAIL_ASSET_PATH", active.assets_content.c_str(), 1) != 0 ||
+            setenv("MOCKTAIL_ASSET_ROOT",
+                   (active.assets_content.filename() == "content"
+                        ? active.assets_content.parent_path()
+                        : active.assets_content)
+                       .c_str(),
+                   1) != 0))) {
        std::cerr << "[FATAL] Cannot activate resolved Roblox payload\n";
        return EXIT_FAILURE;
      }
@@ -770,7 +839,72 @@ int main(int argc, char* argv[]) {
              << " model=\""
              << runtime_config.config.device_profile().display_name << "\"\n";
  }
+  mocktail::compat::PayloadCompatibilityResult compatibility;
+  bool vr_active = false;
  if (command_line.options.mode == mocktail::runtime::CommandMode::kRun) {
+    const std::string compatibility_manifest =
+        environment.GetOr("MOCKTAIL_COMPATIBILITY_MANIFEST",
+                          MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST);
+    compatibility = mocktail::compat::CheckPayloadCompatibility(
+        runtime_config.config.roblox_library_path().string(),
+        compatibility_manifest,
+        command_line.options.allow_unverified_build);
+    if (!compatibility) {
+      std::cerr << "[FATAL] " << compatibility.error << '\n';
+      return EXIT_FAILURE;
+    }
+    if (!compatibility.profile.vr_debug_device_bridge.has_value()) {
+      if (const auto* vr_profile =
+              mocktail::vr::FindRobloxVrDeviceProfile(compatibility.build_id)) {
+        compatibility.profile.vr_debug_device_bridge = *vr_profile;
+      }
+    }
+    const bool vr_build_supported =
+        compatibility.profile.vr_debug_device_bridge.has_value();
+    if (runtime_config.config.vr_enabled() && vr_requested &&
+        !vr_build_supported) {
+      // An explicit --vr on a build without VR support is a user error, not
+      // something to silently ignore; say which builds work and how to pick.
+      std::cerr << "[FATAL] VR is not available for Roblox "
+                << compatibility.profile.version_name << " (version "
+                << compatibility.profile.version_code << ", Build ID "
+                << compatibility.build_id << ").\n"
+                << "  VR supports builds "
+                << mocktail::vr::DescribeSupportedVrBuilds()
+                << ". Point --roblox-lib at one of those payloads'\n"
+                << "  libroblox.so, or launch without --vr.\n";
+      return EXIT_FAILURE;
+    }
+    vr_active = runtime_config.config.vr_enabled() && vr_build_supported;
+    if (runtime_config.config.vr_enabled() && !vr_active) {
+      std::cerr << "  [vr] Roblox " << compatibility.profile.version_name
+                << " (Build ID " << compatibility.build_id
+                << ") has no VR support (supported: "
+                << mocktail::vr::DescribeSupportedVrBuilds()
+                << "); continuing without VR\n";
+      if (setenv("MOCKTAIL_VR_ENABLED", "0", 1) != 0) {
+        std::cerr << "[FATAL] Cannot disable VR for this Roblox build\n";
+        return EXIT_FAILURE;
+      }
+    }
+    if (vr_active) {
+      const mocktail::vr::VrBackendMode vr_backend_mode =
+          mocktail::vr::ResolveVrBackendMode(true);
+      std::cerr << "  [vr] experimental backend="
+                << mocktail::vr::VrBackendModeName(vr_backend_mode)
+                << ": Roblox renders both eyes through its DebugDeviceVR "
+                   "debug device (Build ID "
+                << compatibility.build_id << ")";
+      if (vr_backend_mode == mocktail::vr::VrBackendMode::kXrOutput) {
+        std::cerr << "; eye images are submitted to the active OpenXR runtime "
+                     "as a projection layer. Start WiVRn or SteamVR/ALVR and "
+                     "connect the headset "
+                     "before launching.\n";
+      } else {
+        std::cerr << "; OpenXR output is disabled in this diagnostic mode "
+                     "(MOCKTAIL_VR_BACKEND=native).\n";
+      }
+    }
    const std::filesystem::path fflags_path =
        paths.config_root() / "fflags.json";
    const auto fflags = mocktail::services::LoadAndMergeFflagsFile(
@@ -788,7 +922,8 @@ int main(int argc, char* argv[]) {
    std::string client_settings_overrides;
    std::vector<std::string> kept_fflag_overrides;
    if (!mocktail::runtime::MergeRuntimeClientSettingsOverrides(
-            runtime_config.config.frame_rate(),
+            vr_active ? runtime_config.config.vr_frame_rate()
+                      : runtime_config.config.frame_rate(),
            runtime_config.config.performance(), fflags.json,
            &client_settings_overrides, &command_line_error,
            &kept_fflag_overrides)) {
@@ -809,6 +944,12 @@ int main(int argc, char* argv[]) {
                << command_line_error << '\n';
      return EXIT_FAILURE;
    }
+    if (!mocktail::runtime::MergeVrClientSettingsOverrides(
+            vr_active, audio_capture_overrides,
+            &audio_capture_overrides, &command_line_error)) {
+      std::cerr << "[FATAL] Cannot apply VR policy: " << command_line_error << '\n';
+      return EXIT_FAILURE;
+    }
    if (setenv("MOCKTAIL_CLIENT_SETTINGS_OVERRIDES_JSON",
               audio_capture_overrides.c_str(), 1) != 0) {
      std::cerr << "[FATAL] Cannot export runtime client-settings policy\n";
@@ -824,6 +965,12 @@ int main(int argc, char* argv[]) {
                << command_line_error << '\n';
      return EXIT_FAILURE;
    }
+    if (!mocktail::runtime::MergeVrClientSettingsOverrides(
+            vr_active, fast_flags_overrides,
+            &fast_flags_overrides, &command_line_error)) {
+      std::cerr << "[FATAL] Cannot apply VR policy: " << command_line_error << '\n';
+      return EXIT_FAILURE;
+    }
    if (setenv("MOCKTAIL_FAST_FLAGS_JSON", fast_flags_overrides.c_str(), 1) !=
        0) {
      std::cerr << "[FATAL] Cannot export crash-report fast-flags policy\n";
@@ -864,10 +1011,14 @@ int main(int argc, char* argv[]) {
                   "counts under Roblox client-settings control\n";
    }
  }
+  const mocktail::runtime::FrameRatePolicy& active_frame_rate =
+      vr_active ? runtime_config.config.vr_frame_rate()
+                : runtime_config.config.frame_rate();
  if (command_line.options.mode == mocktail::runtime::CommandMode::kRun &&
-      runtime_config.config.frame_rate().mode ==
+      active_frame_rate.mode ==
          mocktail::runtime::FrameRateLimitMode::kUnlimited) {
-    std::cout << "  [runtime] frame-rate mode=unlimited scheduler_target="
+    std::cout << "  [runtime] " << (vr_active ? "vr " : "")
+              << "frame-rate mode=unlimited scheduler_target="
              << mocktail::runtime::kMaximumSupportedRobloxSchedulerFps
              << " vsync=" << runtime_config.config.vsync_mode() << '\n';
  }
@@ -882,19 +1033,15 @@ int main(int argc, char* argv[]) {

  mocktail::runtime::RobloxFullscreenRuntimeBridge fullscreen_bridge;
  mocktail::audio::RobloxOutputDeviceBridge output_device_bridge;
+  // Never destroyed: Shutdown() stops waiting after 2 s, and a guest thread
+  // still inside a hook then keeps using this object until the process ends.
+  static auto& vr_device_bridge = *new mocktail::vr::RobloxVrDeviceBridge;
+  // Never destroyed, for the same reason: the hooks call into the backend.
+  static auto& xr_backend = *new mocktail::vr::OpenXrBackend;
+  struct DisarmOnExit {
+    ~DisarmOnExit() { xr_backend.Disarm(); }
+  } disarm_xr_backend_on_exit;
  if (command_line.options.mode == mocktail::runtime::CommandMode::kRun) {
-    const std::string compatibility_manifest =
-        environment.GetOr("MOCKTAIL_COMPATIBILITY_MANIFEST",
-                          MOCKTAIL_DEFAULT_COMPATIBILITY_MANIFEST);
-    const mocktail::compat::PayloadCompatibilityResult compatibility =
-        mocktail::compat::CheckPayloadCompatibility(
-            runtime_config.config.roblox_library_path().string(),
-            compatibility_manifest,
-            command_line.options.allow_unverified_build);
-    if (!compatibility) {
-      std::cerr << "[FATAL] " << compatibility.error << '\n';
-      return EXIT_FAILURE;
-    }
    const mocktail::Status fullscreen_status =
        fullscreen_bridge.Install(compatibility.profile);
    if (!fullscreen_status.ok()) {
@@ -924,6 +1071,66 @@ int main(int argc, char* argv[]) {
                << output_device_status.message() << '\n';
      return EXIT_FAILURE;
    }
+    if (vr_active) {
+      const mocktail::Status vr_device_status =
+          vr_device_bridge.Install(compatibility.profile);
+      if (!vr_device_status.ok()) {
+        std::cerr << "[FATAL] Cannot install experimental Roblox VR device "
+                     "bridge: "
+                  << vr_device_status.message() << '\n';
+        return EXIT_FAILURE;
+      }
+      if (mocktail::vr::ResolveVrBackendMode(true) ==
+          mocktail::vr::VrBackendMode::kXrOutput) {
+        // Fail closed and loudly when no OpenXR runtime is reachable; the
+        // native-stereo diagnostic mode must be requested explicitly.
+        const mocktail::Status xr_status =
+            xr_backend.Arm(runtime_config.config.graphics_backend() ==
+                                   mocktail::runtime::GraphicsBackend::kVulkan
+                               ? mocktail::vr::VrGraphicsApi::kVulkan
+                               : mocktail::vr::VrGraphicsApi::kOpenGles);
+        if (!xr_status.ok()) {
+          std::cerr
+              << "[FATAL] Cannot arm the OpenXR backend for --vr: "
+              << xr_status.message() << '\n'
+              << "  Start WiVRn or SteamVR/ALVR, connect your headset, then "
+                 "run mocktail -vr again.\n"
+              << "  For a custom runtime set XR_RUNTIME_JSON to its manifest.\n"
+              << "  Set MOCKTAIL_VR_BACKEND=native for the "
+                 "native-stereo diagnostic mode without a runtime.\n";
+          return EXIT_FAILURE;
+        }
+        // The in-headset keyboard follows Roblox's TextBox keyboard requests
+        // and types through the same events as the desktop keyboard.
+        mocktail::vr::VirtualKeyboardHost keyboard_host;
+        keyboard_host.input_requested = [](void*) {
+          return mocktail::window::TextInputRequested();
+        };
+        keyboard_host.commit_text = [](void*, const char* utf8) {
+          mocktail::window::QueueVirtualTextInput(utf8);
+        };
+        keyboard_host.press_key = [](void*, std::uint32_t scancode) {
+          mocktail::window::QueueVirtualKeyPress(scancode);
+        };
+        mocktail::vr::SetVirtualKeyboardHost(&keyboard_host);
+        // TextBox text is drawn as a desktop window overlay that never reaches
+        // the eye images; mirror it into the keyboard's text field.
+        mocktail::runtime::SetRobloxTextDisplayMirror(
+            {nullptr, [](void*,
+                         const mocktail::runtime::RobloxTextDisplayUpdate&
+                             update) {
+               if (update.event ==
+                   mocktail::runtime::RobloxTextDisplayEvent::kHide) {
+                 mocktail::vr::ClearVirtualKeyboardText();
+                 return;
+               }
+               mocktail::vr::SetVirtualKeyboardText(
+                   update.utf8, update.utf8_size, update.cursor_utf16,
+                   mocktail::runtime::IsRobloxPasswordTextInputType(
+                       update.text_input_type));
+             }});
+      }
+    }
  }

  mocktail::legacy::RuntimeDependencies dependencies;
@@ -1012,6 +1219,7 @@ int main(int argc, char* argv[]) {
      std::cout
          << "  [auth] explicit guest identity selected for production VM\n";
    }
+    unsetenv("MOCKTAIL_LUAU_CODEGEN_MENU_SWITCH");
    if (runtime_config.config.desktop_playability()) {
      std::filesystem::path assets = paths.DefaultAssetPath();
      if (environment.HasNonEmpty("MOCKTAIL_ASSET_PATH")) {
@@ -1034,10 +1242,13 @@ int main(int argc, char* argv[]) {
        return EXIT_FAILURE;
      }
      std::string desktop_client_settings;
+      const std::string user_client_settings =
+          environment.GetOr("MOCKTAIL_CLIENT_SETTINGS_OVERRIDES_JSON", "{}");
+      const bool user_set_luau_codegen =
+          mocktail::runtime::ClientSettingsSetLuauCodegenAll(
+              user_client_settings);
      if (!mocktail::runtime::MergeDesktopAppPolicyClientSettingsOverride(
-              desktop_policy.policy_json,
-              environment.GetOr("MOCKTAIL_CLIENT_SETTINGS_OVERRIDES_JSON",
-                                "{}"),
+              desktop_policy.policy_json, user_client_settings,
              &desktop_client_settings, &command_line_error)) {
        std::cerr << "[FATAL] Cannot activate desktop Roblox app-policy: "
                  << command_line_error << '\n';
@@ -1048,11 +1259,33 @@ int main(int argc, char* argv[]) {
        std::cerr << "[FATAL] Cannot export desktop Roblox app-policy\n";
        return EXIT_FAILURE;
      }
+      setenv("MOCKTAIL_LUAU_CODEGEN_MENU_SWITCH",
+             user_set_luau_codegen ? "0" : "1", 1);
      std::cout << "  [runtime] desktop app-policy ready: normalized="
                << desktop_policy.normalized_policy_count
                << " updated=" << (desktop_policy.updated ? 1 : 0)
                << " runtime_override=1\n";
    }
+    if (vr_active) {
+      std::string vr_client_settings;
+      std::string vr_fast_flags;
+      if (!mocktail::runtime::MergeVrAppPolicyClientSettingsOverrides(
+              vr_active,
+              environment.GetOr("MOCKTAIL_CLIENT_SETTINGS_OVERRIDES_JSON", "{}"),
+              environment.GetOr("MOCKTAIL_FAST_FLAGS_JSON", "{}"),
+              &vr_client_settings, &vr_fast_flags, &command_line_error)) {
+        std::cerr << "[FATAL] Cannot apply VR app-policy: "
+                  << command_line_error << '\n';
+        return EXIT_FAILURE;
+      }
+      if (setenv("MOCKTAIL_CLIENT_SETTINGS_OVERRIDES_JSON",
+                 vr_client_settings.c_str(), 1) != 0 ||
+          setenv("MOCKTAIL_FAST_FLAGS_JSON", vr_fast_flags.c_str(), 1) != 0) {
+        std::cerr << "[FATAL] Cannot export VR app-policy\n";
+        return EXIT_FAILURE;
+      }
+      std::cout << "  [vr] app-policy idle render throttling disabled\n";
+    }
    auto android_window_context =
        std::make_shared<AndroidWindowBridgeContext>();
    jnivm::AndroidWindowCallbacks android_window_callbacks;
@@ -1125,6 +1358,8 @@ int main(int argc, char* argv[]) {
                              std::to_string(runtime_status) + ".");
  }
  support_bundle_guard.SetExitCode(runtime_status);
+  xr_backend.Disarm();
+  vr_device_bridge.Shutdown();
  output_device_bridge.Shutdown();
  fullscreen_bridge.Shutdown();
  memory_limit_watchdog.Stop();
@@ -0,0 +1,64 @@
+#include "runtime/asset_overlay_names.h"
+
+#include <algorithm>
+#include <cstring>
+#include <system_error>
+
+namespace mocktail {
+namespace runtime {
+
+std::vector<std::string> OverlayRbxAssetNames(
+    const std::filesystem::path& overlay_dir) {
+  std::vector<std::string> names;
+  const std::filesystem::path content = overlay_dir / "content";
+  std::error_code error;
+  std::filesystem::recursive_directory_iterator it(
+      content, std::filesystem::directory_options::skip_permission_denied,
+      error);
+  const std::filesystem::recursive_directory_iterator end;
+  for (; !error && it != end; it.increment(error)) {
+    std::error_code entry_error;
+    if (!it->is_regular_file(entry_error)) {
+      continue;
+    }
+    const std::filesystem::path relative =
+        it->path().lexically_relative(content);
+    names.push_back("rbxasset://" + relative.generic_string());
+  }
+  std::sort(names.begin(), names.end());
+  return names;
+}
+
+std::size_t DisableAssetNameMappings(std::uint8_t* data, std::size_t size,
+                                     const std::vector<std::string>& names) {
+  std::size_t changed = 0;
+  if (data == nullptr) {
+    return changed;
+  }
+  std::uint8_t* const end = data + size;
+  for (const std::string& name : names) {
+    // The trailing NUL is part of the needle, so a longer string never matches.
+    const std::size_t needle_size = name.size() + 1;
+    if (name.empty() || needle_size > size) {
+      continue;
+    }
+    std::uint8_t* cursor = data;
+    while (cursor + needle_size <= end) {
+      auto* found = static_cast<std::uint8_t*>(
+          memmem(cursor, static_cast<std::size_t>(end - cursor), name.c_str(),
+                 needle_size));
+      if (found == nullptr) {
+        break;
+      }
+      if (found == data || found[-1] == 0) {
+        found[0] = '!';
+        ++changed;
+      }
+      cursor = found + needle_size;
+    }
+  }
+  return changed;
+}
+
+}  // namespace runtime
+}  // namespace mocktail
@@ -76,6 +76,8 @@ CommandLineParseResult ParseCommandLine(int argc, const char* const argv[]) {
                           &result.options.graphics_backend, &result.error)) {
        return result;
      }
+    } else if (argument == "--vr" || argument == "-vr" || argument == "--no-vr") {
+      result.options.vr_enabled = argument != "--no-vr";
    } else if (argument == "--allow-unverified-build") {
      result.options.allow_unverified_build = true;
    } else if (argument == "--force-run-latest") {
@@ -149,6 +151,7 @@ CommandLineParseResult ParseCommandLine(int argc, const char* const argv[]) {
      (!result.options.roblox_library_path.empty() ||
       result.options.window_mode != WindowMode::kUnspecified ||
       !result.options.graphics_backend.empty() ||
+       result.options.vr_enabled.has_value() ||
       result.options.allow_unverified_build ||
       !result.options.launch_request_json.empty())) {
    result.error = "--force-run-latest must be used on its own";
@@ -226,6 +229,11 @@ void ScrubCommandLineLaunchArguments(CommandLineOptions* options, int argc,

 bool ApplyCommandLineEnvironment(const CommandLineOptions& options,
                                 std::string* error) {
+  if (options.vr_enabled.has_value() &&
+      !SetEnvironment("MOCKTAIL_VR_ENABLED", *options.vr_enabled ? "1" : "0",
+                      error)) {
+    return false;
+  }
  if (!options.roblox_library_path.empty() &&
      !SetEnvironment("ROBLOX_LIB_PATH", options.roblox_library_path, error)) {
    return false;
@@ -271,6 +279,9 @@ std::string CommandLineUsage(const std::string& program_name) {
      << compat::kGuestAbi << " libroblox.so\n"
      << "  --headless               Run without creating an SDL window\n"
      << "  --windowed               Force windowed startup (default)\n"
+      << "  -vr / --vr / --no-vr     Launch Roblox via OpenXR (WiVRn) or "
+         "disable vr.enabled\n"
+      << "                          VR builds enable VR by default; use --no-vr to opt out.\n"
      << "  --graphics <backend>     direct-vulkan | opengl | system | "
         "angle-vulkan (default: direct-vulkan)\n"
      << "  --allow-unverified-build Run a known but unverified Build-ID "
@@ -93,7 +93,7 @@ bool UnthrottledPresentation(const RuntimeConfig& config) {
  if (config.vsync_mode() == "off" || config.vsync_mode() == "0") {
    return true;
  }
-  return config.frame_rate().mode == FrameRateLimitMode::kUnlimited;
+  return config.active_frame_rate().mode == FrameRateLimitMode::kUnlimited;
 }

 bool ParsePciVendor(const std::string& raw, unsigned int* vendor) {
@@ -0,0 +1,150 @@
+#include "runtime/luau_codegen_switch.h"
+
+#include <elf.h>
+
+#include <algorithm>
+#include <cstring>
+#include <iostream>
+#include <string>
+#include <utility>
+
+#include <nlohmann/json.hpp>
+
+namespace mocktail {
+namespace runtime {
+namespace {
+
+constexpr std::size_t kNameSlotOffset = 8;
+constexpr std::size_t kRecordTailSize = 16;
+
+std::string_view SegmentBytes(const LoadedImageSegment& segment) {
+  return {reinterpret_cast<const char*>(segment.address), segment.size};
+}
+
+std::vector<std::uintptr_t> NameAddresses(
+    const std::vector<LoadedImageSegment>& segments, std::string_view name) {
+  std::string needle(name);
+  needle.push_back('\0');
+  std::vector<std::uintptr_t> addresses;
+  for (const LoadedImageSegment& segment : segments) {
+    const std::string_view bytes = SegmentBytes(segment);
+    for (std::size_t at = bytes.find(needle); at != std::string_view::npos;
+         at = bytes.find(needle, at + 1)) {
+      addresses.push_back(segment.address + at);
+    }
+  }
+  return addresses;
+}
+
+}  // namespace
+
+std::vector<LoadedImageSegment> LoadedImageSegments(std::uintptr_t image_base) {
+  std::vector<LoadedImageSegment> segments;
+  if (image_base == 0) {
+    return segments;
+  }
+  const auto* header = reinterpret_cast<const Elf64_Ehdr*>(image_base);
+  if (std::memcmp(header->e_ident, ELFMAG, SELFMAG) != 0 ||
+      header->e_ident[EI_CLASS] != ELFCLASS64 || header->e_phoff == 0) {
+    return segments;
+  }
+  const auto* program = reinterpret_cast<const Elf64_Phdr*>(
+      image_base + static_cast<std::uintptr_t>(header->e_phoff));
+  for (std::size_t index = 0; index < header->e_phnum; ++index) {
+    if (program[index].p_type != PT_LOAD || program[index].p_memsz == 0) {
+      continue;
+    }
+    segments.push_back({image_base + program[index].p_vaddr,
+                        static_cast<std::size_t>(program[index].p_memsz),
+                        (program[index].p_flags & PF_W) != 0});
+  }
+  return segments;
+}
+
+std::uint8_t* FindFastFlagValue(const std::vector<LoadedImageSegment>& segments,
+                                std::string_view name) {
+  const std::vector<std::uintptr_t> names = NameAddresses(segments, name);
+  if (names.empty()) {
+    return nullptr;
+  }
+  std::uint8_t* found = nullptr;
+  int matches = 0;
+  for (const LoadedImageSegment& segment : segments) {
+    if (!segment.writable || segment.size < kNameSlotOffset + kRecordTailSize) {
+      continue;
+    }
+    const std::uintptr_t first =
+        (segment.address + kNameSlotOffset + 7) & ~std::uintptr_t{7};
+    const std::uintptr_t end = segment.address + segment.size;
+    for (std::uintptr_t slot = first; slot + kRecordTailSize <= end;
+         slot += 8) {
+      std::uintptr_t pointer = 0;
+      std::memcpy(&pointer, reinterpret_cast<const void*>(slot),
+                  sizeof(pointer));
+      if (std::find(names.begin(), names.end(), pointer) == names.end()) {
+        continue;
+      }
+      std::uint64_t length = 0;
+      std::memcpy(&length, reinterpret_cast<const void*>(slot + 8),
+                  sizeof(length));
+      if (length != name.size()) {
+        continue;
+      }
+      found = reinterpret_cast<std::uint8_t*>(slot - kNameSlotOffset);
+      ++matches;
+    }
+  }
+  return matches == 1 ? found : nullptr;
+}
+
+bool ClientSettingsSetLuauCodegenAll(std::string_view overrides_json) {
+  const nlohmann::json overrides =
+      nlohmann::json::parse(overrides_json, nullptr, false, true);
+  return overrides.is_object() &&
+         overrides.contains(std::string(kLuauCodegenAllClientSetting));
+}
+
+bool LuauCodegenAllForPhase(RobloxExperiencePresencePhase phase) {
+  return phase == RobloxExperiencePresencePhase::kBrowsing;
+}
+
+LuauCodegenMenuSwitch::LuauCodegenMenuSwitch(
+    LocateFlagFn locate_flag, RobloxExperiencePresenceObserver next)
+    : locate_flag_(std::move(locate_flag)), next_(next) {}
+
+RobloxExperiencePresenceObserver LuauCodegenMenuSwitch::observer() {
+  return {this, &LuauCodegenMenuSwitch::Notify};
+}
+
+void LuauCodegenMenuSwitch::OnPhase(
+    RobloxExperiencePresencePhase phase,
+    const RobloxExperienceLaunchRequest* request) {
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (!located_) {
+      located_ = true;
+      flag_ = locate_flag_ ? locate_flag_() : nullptr;
+    }
+    if (flag_ != nullptr) {
+      const std::uint8_t current = __atomic_load_n(flag_, __ATOMIC_RELAXED);
+      const std::uint8_t wanted = LuauCodegenAllForPhase(phase) ? 1 : 0;
+      if (current <= 1 && current != wanted) {
+        __atomic_store_n(flag_, wanted, __ATOMIC_RELAXED);
+        std::cout << "  [luau-codegen] native code for all scripts "
+                  << (wanted != 0 ? "on" : "off") << '\n';
+      }
+    }
+  }
+  if (next_.valid()) {
+    next_.notify(next_.context, phase, request);
+  }
+}
+
+void LuauCodegenMenuSwitch::Notify(
+    void* context, RobloxExperiencePresencePhase phase,
+    const RobloxExperienceLaunchRequest* request) {
+  static_cast<LuauCodegenMenuSwitch*>(context)->OnPhase(phase, request);
+}
+
+}  // namespace runtime
+}  // namespace mocktail
@@ -375,6 +375,47 @@ bool MergeAudioDeviceMenuClientSettingsOverrides(std::string_view base_json,
  return true;
 }

+bool MergeVrClientSettingsOverrides(bool enabled, std::string_view base_json,
+                                    std::string* merged_json,
+                                    std::string* error) {
+  if (merged_json == nullptr) {
+    if (error != nullptr) {
+      *error = "VR client-settings output is required";
+    }
+    return false;
+  }
+  auto overrides = nlohmann::json::parse(base_json.empty() ? "{}" : base_json,
+                                         nullptr, false, true);
+  if (overrides.is_discarded() || !overrides.is_object()) {
+    if (error != nullptr) {
+      *error = "VR client-settings input must be a JSON object";
+    }
+    return false;
+  }
+  // Without VR the flags are left exactly as the user (fflags.json) set
+  // them; only an active VR session forces the emulator on.
+  if (enabled) {
+    overrides["FFlagDebugEnableVREmulator"] = "True";
+    // Roblox 2998's SurfaceController startup throttle renders at 1 Hz while
+    // waiting for AppStartRendering. Our XR frame loop is driven by guest
+    // presents, so that also stalls head/controller updates in the VR menu.
+    // Keep VR rendering continuous; leave the non-VR startup policy alone.
+    overrides["FFlagSlowDownRendering"] = "False";
+    // The eye textures already use the OpenXR extent; render their contents
+    // at full resolution as well, without Roblox's dynamic downscaling.
+    overrides["FFlagDebugDisableDRS"] = "True";
+    // Place the Avatar Editor character 6 studs in front of the VR camera
+    // instead of at the origin when IsVRAppBuild() is active.
+    overrides["FFlagFixVRAvatarPlacement"] = "True";
+    // Mobile suppresses vibration when a gamepad connects unless KeepHaptics
+    // is enabled; VR controllers connect as Gamepad1.
+    overrides["FFlagKeepHapticsOnMobileWhenGamepadConnected"] = "True";
+    overrides["FFlagVRHaptics"] = "True";
+  }
+  *merged_json = overrides.dump();
+  return true;
+}
+
 bool MergeAudioCaptureClientSettingsOverrides(bool microphone_enabled,
                                              std::string_view base_json,
                                              std::string* merged_json,
@@ -14,6 +14,7 @@
 #include <string_view>
 #include <utility>

+#include "runtime/luau_codegen_switch.h"
 #include "runtime/runtime_paths.h"

 namespace mocktail {
@@ -22,6 +23,8 @@ namespace {

 constexpr std::uintmax_t kMaximumJsonBytes = 16U * 1024U * 1024U;
 constexpr std::string_view kAppPolicySuffix = ":app-policy";
+constexpr const char* kFlyoutVariantFlag = "FIntFlyoutTestVariantRollout12";
+constexpr const char* kDesktopFlyoutVariant = "2";
 constexpr std::string_view kDesktopAppPolicyOverride =
    "FStringAppConfigurationOverrideAppPolicy";
 std::atomic<std::uint64_t> g_temporary_sequence{0};
@@ -357,6 +360,9 @@ bool MergeDesktopAppPolicyClientSettingsOverride(std::string_view policy_json,
    return false;
  }
  overrides[std::string(kDesktopAppPolicyOverride)] = policy_json;
+  // Native Luau code makes the app's menus faster. LuauCodegenMenuSwitch turns
+  // it off in games, which keep Roblox's own per-script choice.
+  overrides.emplace(std::string(kLuauCodegenAllClientSetting), "True");
  // The SDUI Charts page in 2.736/2.738 can pass a table to TextColor3 and
  // leave the whole LuaApp blank. Default to the working legacy page while
  // preserving explicit user overrides for testing newer UI patches.
@@ -364,10 +370,72 @@ bool MergeDesktopAppPolicyClientSettingsOverride(std::string_view policy_json,
  // Roblox enrolls desktop clients in the flyout side panel through a
  // server-side experiment that does not reach this client. Variant 2 is the
  // desktop side panel; an explicit user override is preserved.
-  overrides.emplace("FIntFlyoutTestVariantRollout12", "2");
+  overrides.emplace(kFlyoutVariantFlag, kDesktopFlyoutVariant);
  *merged_json = overrides.dump();
  return true;
 }

+bool MergeVrAppPolicyClientSettingsOverrides(
+    bool enabled, std::string_view client_settings_json,
+    std::string_view fast_flags_json, std::string* merged_client_settings,
+    std::string* merged_fast_flags, std::string* error) {
+  if (merged_client_settings == nullptr || merged_fast_flags == nullptr) {
+    if (error != nullptr) {
+      *error = "VR app-policy outputs are required";
+    }
+    return false;
+  }
+  if (!enabled) {
+    *merged_client_settings = client_settings_json;
+    *merged_fast_flags = fast_flags_json;
+    return true;
+  }
+
+  auto client_settings = nlohmann::json::parse(
+      client_settings_json.empty() ? "{}" : client_settings_json, nullptr,
+      false, true);
+  auto fast_flags = nlohmann::json::parse(
+      fast_flags_json.empty() ? "{}" : fast_flags_json, nullptr, false, true);
+  if (!client_settings.is_object() || !fast_flags.is_object()) {
+    if (error != nullptr) {
+      *error = "VR client-settings and fast-flags overrides must be JSON objects";
+    }
+    return false;
+  }
+
+  nlohmann::json policy = nlohmann::json::object();
+  const nlohmann::json* channels[] = {&client_settings, &fast_flags};
+  for (const auto* channel : channels) {
+    const auto existing = channel->find(kDesktopAppPolicyOverride);
+    if (existing == channel->end()) {
+      continue;
+    }
+    // An empty FString means no app-policy override. The later fast-flags
+    // channel can clear/replace an earlier client-settings override.
+    if (existing->is_string() &&
+        existing->get_ref<const std::string&>().empty()) {
+      policy = nlohmann::json::object();
+    } else if (!DecodePolicy(*existing, &policy)) {
+      if (error != nullptr) {
+        *error = "VR app-policy override must be an encoded JSON object";
+      }
+      return false;
+    }
+  }
+  policy["ThrottleFramerate"] = false;
+  // The desktop side panel cannot be reached with the VR pointer. fflags.json
+  // is the later channel, so a user's own value there still decides.
+  const auto flyout = client_settings.find(kFlyoutVariantFlag);
+  if (flyout != client_settings.end() && *flyout == kDesktopFlyoutVariant) {
+    *flyout = "0";
+  }
+  const std::string encoded_policy = policy.dump();
+  client_settings[std::string(kDesktopAppPolicyOverride)] = encoded_policy;
+  fast_flags[std::string(kDesktopAppPolicyOverride)] = encoded_policy;
+  *merged_client_settings = client_settings.dump();
+  *merged_fast_flags = fast_flags.dump();
+  return true;
+}
+
 }  // namespace runtime
 }  // namespace mocktail
@@ -466,6 +466,20 @@ Status RobloxExperienceComposition::InitializePlatformProtocols() {
    (void)ReleaseGlobalObjects();
    return status;
  }
+  std::unique_ptr<RobloxHapticProtocolBridge> haptic_protocol_bridge;
+  if (RobloxHapticProtocolBridge::EnabledForThisSession()) {
+    haptic_protocol_bridge = std::make_unique<RobloxHapticProtocolBridge>(
+        environment_, permissions_symbols_, permissions_objects);
+    status = haptic_protocol_bridge->Initialize();
+    if (!status.ok()) {
+      (void)call_protocol_bridge->Shutdown();
+      (void)permissions_bridge->Shutdown();
+      (void)browser_service_bridge->Shutdown();
+      (void)web_view_bridge->Shutdown();
+      (void)ReleaseGlobalObjects();
+      return status;
+    }
+  }
  // AccountProtocol only shortens a device-integrity login challenge that
  // cannot succeed here, so its absence or failure never blocks startup.
  std::unique_ptr<RobloxAccountBridge> account_bridge;
@@ -493,6 +507,7 @@ Status RobloxExperienceComposition::InitializePlatformProtocols() {
    browser_service_bridge_ = std::move(browser_service_bridge);
    permissions_bridge_ = std::move(permissions_bridge);
    call_protocol_bridge_ = std::move(call_protocol_bridge);
+    haptic_protocol_bridge_ = std::move(haptic_protocol_bridge);
    account_bridge_ = std::move(account_bridge);
    platform_protocols_initialized_ = true;
  }
@@ -1446,8 +1461,9 @@ Status RobloxExperienceComposition::DrainLaunchRequests() {
      return Status::Ok();
    if (!launch_in_progress_ && active_launch_ == nullptr && game_active_ &&
        !pending_launch_requests_.empty()) {
-      // Start the queued launch only after consuming this leave callback, so
-      // it cannot reach the next controller.
+      // Blocks a reentrant drain while the leave pumps main-thread messages.
+      // The leave ends in the Native stage with no Lua app return, so the
+      // queued launch starts on the next drain.
      controlled_switch_waiting_for_return_ = true;
      switch_active_game = true;
    }
@@ -1456,7 +1472,7 @@ Status RobloxExperienceComposition::DrainLaunchRequests() {
    std::fprintf(stderr,
                 "[experience] leaving active game for queued launch\n");
    const Status leave_status = LeaveGame();
-    if (!leave_status.ok()) {
+    {
      std::lock_guard<std::mutex> lock(mutex_);
      controlled_switch_waiting_for_return_ = false;
    }
@@ -1693,6 +1709,7 @@ Status RobloxExperienceComposition::Shutdown() {
  std::unique_ptr<RobloxBrowserServiceBridge> browser_service_bridge;
  std::unique_ptr<RobloxPermissionsBridge> permissions_bridge;
  std::unique_ptr<RobloxCallProtocolBridge> call_protocol_bridge;
+  std::unique_ptr<RobloxHapticProtocolBridge> haptic_protocol_bridge;
  std::unique_ptr<RobloxAccountBridge> account_bridge;
  std::shared_ptr<WebViewHelperProcess> web_surface_process;
  jnivm::VM* late_lifecycle_vm = nullptr;
@@ -1719,6 +1736,7 @@ Status RobloxExperienceComposition::Shutdown() {
    browser_service_bridge = std::move(browser_service_bridge_);
    permissions_bridge = std::move(permissions_bridge_);
    call_protocol_bridge = std::move(call_protocol_bridge_);
+    haptic_protocol_bridge = std::move(haptic_protocol_bridge_);
    account_bridge = std::move(account_bridge_);
    web_surface_process = std::move(web_surface_process_);
    web_surface_logical_exit_observer_ = {};
@@ -1736,9 +1754,14 @@ Status RobloxExperienceComposition::Shutdown() {
  if (web_surface_process != nullptr) {
    (void)web_surface_process->RequestClose();
  }
-  Status status = call_protocol_bridge != nullptr
-                      ? call_protocol_bridge->Shutdown()
+  Status status = haptic_protocol_bridge != nullptr
+                      ? haptic_protocol_bridge->Shutdown()
                      : Status::Ok();
+  const Status call_status = call_protocol_bridge != nullptr
+                                 ? call_protocol_bridge->Shutdown()
+                                 : Status::Ok();
+  if (status.ok())
+    status = call_status;
  const Status account_status =
      account_bridge != nullptr ? account_bridge->Shutdown() : Status::Ok();
  if (status.ok())
@@ -0,0 +1,497 @@
+#include "runtime/roblox_haptic_protocol_bridge.h"
+
+#include <dlfcn.h>
+
+#include <algorithm>
+#include <cctype>
+#include <chrono>
+#include <cmath>
+#include <condition_variable>
+#include <cstdlib>
+#include <mutex>
+#include <nlohmann/json.hpp>
+#include <optional>
+#include <string_view>
+#include <thread>
+#include <vector>
+
+extern "C" {
+void mocktail_vr_controller_request_haptics(int32_t hand, float amplitude,
+                                            uint64_t duration_ns,
+                                            float frequency_hz) __attribute__((weak));
+void mocktail_vr_controller_stop_haptics(int32_t hand) __attribute__((weak));
+}
+
+namespace mocktail {
+namespace runtime {
+namespace {
+
+constexpr std::size_t kMaximumJsonBytes = 64 * 1024;
+constexpr uint64_t kMinimumDurationNs = 50000000ULL;      // 50ms
+constexpr uint64_t kMaximumDurationNs = 5000000000ULL;    // 5 seconds
+
+bool HasBoundedDepth(const std::string& json) {
+  int depth = 0;
+  bool quoted = false;
+  bool escaped = false;
+  for (const char ch : json) {
+    if (quoted) {
+      if (escaped)
+        escaped = false;
+      else if (ch == '\\')
+        escaped = true;
+      else if (ch == '"')
+        quoted = false;
+    } else if (ch == '"') {
+      quoted = true;
+    } else if (ch == '{' || ch == '[') {
+      if (++depth > 8)
+        return false;
+    } else if (ch == '}' || ch == ']') {
+      --depth;
+    }
+  }
+  return true;
+}
+
+std::optional<nlohmann::json> ParseJsonMessage(JNIEnv* env, jstring message) {
+  if (!message)
+    return std::nullopt;
+  const jsize size = env->GetStringUTFLength(message);
+  if (size <= 0 || static_cast<std::size_t>(size) > kMaximumJsonBytes)
+    return std::nullopt;
+  const char* bytes = env->GetStringUTFChars(message, nullptr);
+  if (!bytes)
+    return std::nullopt;
+  const std::string owned(bytes, static_cast<std::size_t>(size));
+  env->ReleaseStringUTFChars(message, bytes);
+  if (!HasBoundedDepth(owned))
+    return std::nullopt;
+  auto parsed = nlohmann::json::parse(owned, nullptr, false);
+  if (parsed.is_discarded() || !parsed.is_object())
+    return std::nullopt;
+  return parsed;
+}
+
+// 0 left, 1 right, -1 both (a motor that names neither hand).
+int HandForMotor(const std::string& motor_name) {
+  std::string lower_name = motor_name;
+  for (char& c : lower_name) {
+    c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+  }
+  if (lower_name.find("left") != std::string::npos ||
+      lower_name.find("large") != std::string::npos) {
+    return 0;
+  }
+  if (lower_name.find("right") != std::string::npos ||
+      lower_name.find("small") != std::string::npos) {
+    return 1;
+  }
+  return -1;
+}
+
+// One message's demand on each controller: a hand vibrates at the strongest
+// motor that maps to it instead of at whichever one came last.
+struct HandDemand {
+  bool present = false;
+  float amplitude = 0.0f;
+  uint64_t duration_ns = 0;
+};
+
+void AddMotorDemand(HandDemand (&hands)[2], const std::string& motor_name,
+                    float amplitude, uint64_t duration_ns) {
+  if (!std::isfinite(amplitude))
+    amplitude = 0.0f;
+  const int hand = HandForMotor(motor_name);
+  for (int index = 0; index < 2; ++index) {
+    if (hand != -1 && hand != index)
+      continue;
+    auto& demand = hands[index];
+    demand.present = true;
+    if (amplitude > demand.amplitude) {
+      demand.amplitude = amplitude;
+      demand.duration_ns = duration_ns;
+    }
+  }
+}
+
+void DispatchHandDemands(const HandDemand (&hands)[2], const HapticSinkFn& sink,
+                         const HapticStopFn& stop) {
+  for (int hand = 0; hand < 2; ++hand) {
+    const auto& demand = hands[hand];
+    if (!demand.present)
+      continue;
+    if (demand.amplitude <= 0.0f) {
+      if (stop)
+        stop(hand);
+    } else if (sink) {
+      sink(hand, std::clamp(demand.amplitude, 0.0f, 1.0f),
+           std::clamp(demand.duration_ns, kMinimumDurationNs,
+                      kMaximumDurationNs),
+           0.0f);
+    }
+  }
+}
+
+}  // namespace
+
+// Plays SetMotorState buffers sample by sample. Roblox sends HapticEffect
+// output as look-ahead waveforms (e.g. 100 samples x 25 ms) and replaces them
+// as it mixes, so each hand follows its latest buffer in real time.
+class HapticWaveformPlayer {
+ public:
+  using Clock = std::chrono::steady_clock;
+
+  HapticWaveformPlayer(HapticSinkFn sink, HapticStopFn stop)
+      : sink_(std::move(sink)), stop_(std::move(stop)) {}
+  ~HapticWaveformPlayer() { Halt(); }
+
+  HapticWaveformPlayer(const HapticWaveformPlayer&) = delete;
+  HapticWaveformPlayer& operator=(const HapticWaveformPlayer&) = delete;
+
+  // Starts `samples` (already trimmed, at least one) on `hand` now.
+  void Play(int hand, std::vector<float> samples, uint64_t ns_per_sample) {
+    {
+      std::lock_guard<std::mutex> lock(mutex_);
+      if (halted_)
+        return;
+      tracks_[hand] = Track{std::move(samples), ns_per_sample, Clock::now(), 0,
+                            true};
+      if (!thread_.joinable())
+        thread_ = std::thread([this] { Run(); });
+    }
+    wake_.notify_all();
+  }
+
+  void Stop(int hand) {
+    {
+      std::lock_guard<std::mutex> lock(mutex_);
+      tracks_[hand].active = false;
+    }
+    if (stop_)
+      stop_(hand);
+  }
+
+  // Accepts buffers again after Halt.
+  void Resume() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    halted_ = false;
+  }
+
+  // Ends playback, stopping any hand still vibrating.
+  void Halt() {
+    bool was_active[2] = {};
+    {
+      std::lock_guard<std::mutex> lock(mutex_);
+      halted_ = true;
+      for (int hand = 0; hand < 2; ++hand) {
+        was_active[hand] = tracks_[hand].active;
+        tracks_[hand].active = false;
+      }
+    }
+    wake_.notify_all();
+    if (thread_.joinable())
+      thread_.join();
+    for (int hand = 0; hand < 2; ++hand) {
+      if (was_active[hand] && stop_)
+        stop_(hand);
+    }
+  }
+
+ private:
+  struct Track {
+    std::vector<float> samples;
+    uint64_t ns_per_sample = 0;
+    Clock::time_point start;
+    std::size_t next = 0;
+    bool active = false;
+  };
+  struct Step {
+    int hand;
+    float amplitude;
+    uint64_t duration_ns;
+  };
+
+  void Run() {
+    std::unique_lock<std::mutex> lock(mutex_);
+    while (!halted_) {
+      const auto now = Clock::now();
+      std::optional<Clock::time_point> wake_at;
+      std::vector<Step> steps;
+      for (int hand = 0; hand < 2; ++hand) {
+        Track& track = tracks_[hand];
+        if (!track.active)
+          continue;
+        const auto period = std::chrono::nanoseconds(track.ns_per_sample);
+        const auto index = static_cast<std::size_t>((now - track.start) / period);
+        if (index >= track.samples.size()) {
+          track.active = false;
+          steps.push_back({hand, 0.0f, 0});
+          continue;
+        }
+        // A late wake skips to the current sample rather than replaying.
+        if (index >= track.next) {
+          steps.push_back({hand, track.samples[index], track.ns_per_sample});
+          track.next = index + 1;
+        }
+        const auto due = track.start + period * track.next;
+        if (!wake_at || due < *wake_at)
+          wake_at = due;
+      }
+      lock.unlock();
+      for (const Step& step : steps) {
+        if (step.amplitude <= 0.0f) {
+          if (stop_)
+            stop_(step.hand);
+        } else if (sink_) {
+          // The lease outlives one sample a little so steps join seamlessly;
+          // the next sample, or the final stop, replaces it.
+          sink_(step.hand, step.amplitude,
+                std::clamp(step.duration_ns, kMinimumDurationNs,
+                           kMaximumDurationNs),
+                0.0f);
+        }
+      }
+      lock.lock();
+      if (halted_)
+        break;
+      if (wake_at)
+        wake_.wait_until(lock, *wake_at);
+      else
+        wake_.wait(lock);
+    }
+  }
+
+  const HapticSinkFn sink_;
+  const HapticStopFn stop_;
+  std::mutex mutex_;
+  std::condition_variable wake_;
+  Track tracks_[2];
+  bool halted_ = false;
+  std::thread thread_;
+};
+
+namespace {
+
+// One hand's share of a SetMotorState: the per-sample maximum of its motors,
+// on the period of the first motor that reached it.
+struct HandWaveform {
+  bool present = false;
+  uint64_t ns_per_sample = 0;
+  std::vector<float> samples;
+};
+
+void AddMotorWaveform(HandWaveform (&hands)[2], const std::string& motor_name,
+                      const std::vector<float>& samples,
+                      uint64_t ns_per_sample) {
+  const int hand = HandForMotor(motor_name);
+  for (int index = 0; index < 2; ++index) {
+    if (hand != -1 && hand != index)
+      continue;
+    HandWaveform& wave = hands[index];
+    if (!wave.present) {
+      wave.present = true;
+      wave.ns_per_sample = ns_per_sample;
+    }
+    // Resample by time onto the hand's period (Roblox uses one period for
+    // every motor, so this is normally index for index).
+    const double ratio = static_cast<double>(wave.ns_per_sample) /
+                         static_cast<double>(ns_per_sample);
+    const auto length = static_cast<std::size_t>(
+        std::ceil(static_cast<double>(samples.size()) / ratio));
+    if (wave.samples.size() < length)
+      wave.samples.resize(length, 0.0f);
+    for (std::size_t at = 0; at < length; ++at) {
+      const auto source = static_cast<std::size_t>(at * ratio);
+      if (source < samples.size())
+        wave.samples[at] = std::max(wave.samples[at], samples[source]);
+    }
+  }
+}
+
+RobloxMessageBusReply Answer(JNIEnv* env, jstring message, std::size_t method,
+                             const HapticSinkFn& sink,
+                             const HapticStopFn& stop,
+                             const HapticStateSyncFn& state_sync,
+                             HapticWaveformPlayer& player) {
+  // Method 0: SupportsHaptics
+  if (method == 0) {
+    if (state_sync) {
+      state_sync(env);
+    }
+    return RobloxMessageBusReply{R"({"supportsHaptics":true})", 0, "supported"};
+  }
+
+  // Method 1: GetMotors
+  if (method == 1) {
+    if (state_sync) {
+      state_sync(env);
+    }
+    return RobloxMessageBusReply{RobloxHapticProtocolBridge::GetMotorsJson(), 0,
+                                 "ok"};
+  }
+
+  // Method 2: SetMotorState
+  if (method == 2) {
+    const auto parsed = ParseJsonMessage(env, message);
+    if (!parsed.has_value()) {
+      return RobloxMessageBusReply{"{}", 13, "invalid_request"};
+    }
+    const auto& root = *parsed;
+    HandWaveform hands[2];
+    for (auto it = root.begin(); it != root.end(); ++it) {
+      const auto& motor = it.value();
+      if (!motor.is_object())
+        continue;
+      double ms_per_sample = 20.0;
+      if (motor.contains("millisecondsPerSample") &&
+          motor["millisecondsPerSample"].is_number()) {
+        ms_per_sample = motor["millisecondsPerSample"].get<double>();
+      }
+      if (!std::isfinite(ms_per_sample) || ms_per_sample <= 0.0)
+        continue;
+      ms_per_sample = std::clamp(ms_per_sample, 1.0, 1000.0);
+      const auto ns_per_sample =
+          static_cast<uint64_t>(ms_per_sample * 1000000.0);
+      std::vector<float> samples;
+      if (motor.contains("intensities") && motor["intensities"].is_array()) {
+        for (const auto& item : motor["intensities"]) {
+          const float value = item.is_number() ? item.get<float>() : 0.0f;
+          samples.push_back(std::isfinite(value) ? std::clamp(value, 0.0f, 1.0f)
+                                                 : 0.0f);
+        }
+      } else if (motor.contains("intensity") && motor["intensity"].is_number()) {
+        const float value = motor["intensity"].get<float>();
+        samples.push_back(
+            std::isfinite(value) ? std::clamp(value, 0.0f, 1.0f) : 0.0f);
+      }
+      AddMotorWaveform(hands, it.key(), samples, ns_per_sample);
+    }
+    for (int hand = 0; hand < 2; ++hand) {
+      HandWaveform& wave = hands[hand];
+      if (!wave.present)
+        continue;
+      // The buffer is padded with silence; play only up to its last bump.
+      while (!wave.samples.empty() && wave.samples.back() <= 0.0f)
+        wave.samples.pop_back();
+      const std::size_t longest =
+          static_cast<std::size_t>(kMaximumDurationNs / wave.ns_per_sample);
+      if (wave.samples.size() > longest)
+        wave.samples.resize(longest);
+      if (wave.samples.empty())
+        player.Stop(hand);
+      else
+        player.Play(hand, std::move(wave.samples), wave.ns_per_sample);
+    }
+    return RobloxMessageBusReply{"{}", 0, "ok"};
+  }
+
+  // Method 3: UpdateSingletonVibration
+  if (method == 3) {
+    const auto parsed = ParseJsonMessage(env, message);
+    if (!parsed.has_value()) {
+      return RobloxMessageBusReply{"{}", 13, "invalid_request"};
+    }
+    float intensity = 0.0f;
+    if (parsed->contains("intensity") && (*parsed)["intensity"].is_number()) {
+      intensity = (*parsed)["intensity"].get<float>();
+    }
+    HandDemand hands[2];
+    AddMotorDemand(hands, "defaultMotor", intensity, kMinimumDurationNs);
+    DispatchHandDemands(hands, sink, stop);
+    return RobloxMessageBusReply{"{}", 0, "ok"};
+  }
+
+  return RobloxMessageBusReply{"{}", 13, "unknown_method"};
+}
+
+}  // namespace
+
+bool RobloxHapticProtocolBridge::EnabledForThisSession() {
+  const char* value = std::getenv("MOCKTAIL_VR_ENABLED");
+  const std::string_view vr = value != nullptr ? value : "";
+  return vr == "1" || vr == "true" || vr == "on";
+}
+
+std::string RobloxHapticProtocolBridge::GetMotorsJson() {
+  // Positional HapticEffects place hands at x = -1 (left) and +1 (right):
+  // VOXEL DESTRUCT 2 aims its per-hand effects there with a 0.5 radius.
+  const nlohmann::json motors = {
+      {"leftHand", {{"x", -1.0}, {"y", 0.0}, {"z", 0.0}}},
+      {"rightHand", {{"x", 1.0}, {"y", 0.0}, {"z", 0.0}}},
+      {"LeftHand", {{"x", -1.0}, {"y", 0.0}, {"z", 0.0}}},
+      {"RightHand", {{"x", 1.0}, {"y", 0.0}, {"z", 0.0}}},
+      {"Large", {{"x", -1.0}, {"y", 0.0}, {"z", 0.0}}},
+      {"Small", {{"x", 1.0}, {"y", 0.0}, {"z", 0.0}}},
+      {"large", {{"x", -1.0}, {"y", 0.0}, {"z", 0.0}}},
+      {"small", {{"x", 1.0}, {"y", 0.0}, {"z", 0.0}}},
+      {"defaultMotor", {{"x", 0.0}, {"y", 0.0}, {"z", 0.0}}},
+  };
+  return motors.dump();
+}
+
+RobloxHapticProtocolBridge::RobloxHapticProtocolBridge(
+    JniEnvironmentProvider environment, RobloxMessageBusSymbols symbols,
+    RobloxMessageBusObjects objects, HapticSinkFn haptic_sink,
+    HapticStopFn haptic_stop, HapticStateSyncFn haptic_state_sync) {
+  if (!haptic_sink) {
+    haptic_sink = [](int hand, float amplitude, uint64_t duration_ns,
+                     float frequency_hz) {
+      if (&mocktail_vr_controller_request_haptics != nullptr) {
+        mocktail_vr_controller_request_haptics(hand, amplitude, duration_ns,
+                                               frequency_hz);
+      } else {
+        using RequestFn = void (*)(int32_t, float, uint64_t, float);
+        auto fn = reinterpret_cast<RequestFn>(
+            dlsym(RTLD_DEFAULT, "mocktail_vr_controller_request_haptics"));
+        if (fn != nullptr) {
+          fn(hand, amplitude, duration_ns, frequency_hz);
+        }
+      }
+    };
+  }
+  if (!haptic_stop) {
+    haptic_stop = [](int hand) {
+      if (&mocktail_vr_controller_stop_haptics != nullptr) {
+        mocktail_vr_controller_stop_haptics(hand);
+      } else {
+        using StopFn = void (*)(int32_t);
+        auto fn = reinterpret_cast<StopFn>(
+            dlsym(RTLD_DEFAULT, "mocktail_vr_controller_stop_haptics"));
+        if (fn != nullptr) {
+          fn(hand);
+        }
+      }
+    };
+  }
+  player_ = std::make_shared<HapticWaveformPlayer>(haptic_sink, haptic_stop);
+  bridge_ = std::make_unique<RobloxMessageBusRequestBridge>(
+      environment, symbols, objects, "HapticProtocol",
+      std::vector<std::string>{"SupportsHaptics", "GetMotors", "SetMotorState",
+                               "UpdateSingletonVibration"},
+      [sink = std::move(haptic_sink), stop = std::move(haptic_stop),
+       sync = std::move(haptic_state_sync), player = player_](
+          JNIEnv* env, jstring message, std::size_t method) {
+        return Answer(env, message, method, sink, stop, sync, *player);
+      });
+}
+
+RobloxHapticProtocolBridge::~RobloxHapticProtocolBridge() {
+  // A handler may outlive the bridge inside the message bus; never let its
+  // player keep a controller vibrating.
+  player_->Halt();
+}
+
+Status RobloxHapticProtocolBridge::Initialize() {
+  player_->Resume();
+  return bridge_->Initialize();
+}
+
+Status RobloxHapticProtocolBridge::Shutdown() {
+  const Status status = bridge_->Shutdown();
+  player_->Halt();
+  return status;
+}
+
+}  // namespace runtime
+}  // namespace mocktail
@@ -10,6 +10,7 @@
 #include <string>
 #include <unordered_map>
 #include <utility>
+#include <vector>

 namespace mocktail {
 namespace runtime {
@@ -101,6 +102,24 @@ std::string LegacyFontName(int32_t font) {
  return "SourceSansPro-Regular.ttf";
 }

+// TwemojiMozilla covers Unicode emoji; RobloxEmoji holds the private-use
+// Roblox and Robux symbols.
+constexpr const char* kEmojiFontNames[] = {"TwemojiMozilla.ttf",
+                                           "RobloxEmoji.ttf"};
+
+std::vector<std::string> EmojiFontFiles(
+    const std::filesystem::path& asset_content_root) {
+  std::vector<std::string> files;
+  for (const char* name : kEmojiFontNames) {
+    const std::filesystem::path candidate =
+        asset_content_root / "fonts" / name;
+    if (IsRegularFile(candidate)) {
+      files.push_back(candidate.lexically_normal().string());
+    }
+  }
+  return files;
+}
+
 }  // namespace

 RobloxTextFontSelection ResolveRobloxTextFont(
@@ -111,6 +130,7 @@ RobloxTextFontSelection ResolveRobloxTextFont(
  }

  const std::filesystem::path content(asset_content_root);
+  selection.emoji_files = EmojiFontFiles(content);
  const std::optional<FontMapping> mapped = MappingFor(font, content);
  if (mapped.has_value()) {
    const std::filesystem::path candidate = content / "fonts" / mapped->file;
@@ -26,7 +26,7 @@ namespace {

 constexpr std::size_t kMaximumRasterTextBytes = 4096;
 constexpr std::uint64_t kMaximumOverlayPixels = 16ULL * 1024ULL * 1024ULL;
-constexpr std::size_t kMaximumFallbackFonts = 6;
+constexpr std::size_t kMaximumFallbackFonts = 8;

 std::mutex g_active_overlay_mutex;
 RobloxTextSurfaceOverlay* g_active_overlay = nullptr;
@@ -121,10 +121,35 @@ std::vector<std::string> ResolveFontFiles(
  } else if (!selection.primary_file.empty()) {
    files.push_back(selection.primary_file);
  }
+  files.insert(files.end(), selection.emoji_files.begin(),
+               selection.emoji_files.end());
  if (!FcInit()) {
    return files;
  }

+  // The sorted sans list rarely reaches an emoji font before the cap, so ask
+  // for the system emoji font by name ahead of it.
+  FcPattern* emoji = FcNameParse(reinterpret_cast<const FcChar8*>("emoji"));
+  if (emoji != nullptr) {
+    FcConfigSubstitute(nullptr, emoji, FcMatchPattern);
+    FcDefaultSubstitute(emoji);
+    FcResult emoji_result = FcResultNoMatch;
+    FcPattern* matched = FcFontMatch(nullptr, emoji, &emoji_result);
+    FcPatternDestroy(emoji);
+    FcChar8* file = nullptr;
+    if (matched != nullptr &&
+        FcPatternGetString(matched, FC_FILE, 0, &file) == FcResultMatch &&
+        file != nullptr && file[0] != '\0') {
+      const std::string candidate(reinterpret_cast<const char*>(file));
+      if (std::find(files.begin(), files.end(), candidate) == files.end()) {
+        files.push_back(candidate);
+      }
+    }
+    if (matched != nullptr) {
+      FcPatternDestroy(matched);
+    }
+  }
+
  FcPattern* pattern = FcNameParse(reinterpret_cast<const FcChar8*>("sans"));
  if (pattern == nullptr) {
    return files;
@@ -325,6 +350,20 @@ Status RobloxTextSurfaceOverlay::UpdateViewport(
  return Status::Ok();
 }

+namespace {
+std::mutex g_display_mirror_mutex;
+RobloxTextDisplaySink g_display_mirror;
+// Lets a text update skip the lock while no mirror is installed.
+std::atomic<bool> g_display_mirror_set{false};
+}  // namespace
+
+void SetRobloxTextDisplayMirror(RobloxTextDisplaySink sink) {
+  std::lock_guard<std::mutex> lock(g_display_mirror_mutex);
+  g_display_mirror = sink;
+  g_display_mirror_set.store(sink.update != nullptr,
+                             std::memory_order_release);
+}
+
 RobloxTextDisplaySink RobloxTextSurfaceOverlay::sink() {
  return {this, &RobloxTextSurfaceOverlay::UpdateCallback};
 }
@@ -334,6 +373,13 @@ void RobloxTextSurfaceOverlay::UpdateCallback(
  if (context != nullptr) {
    static_cast<RobloxTextSurfaceOverlay*>(context)->ApplyUpdate(update);
  }
+  if (!g_display_mirror_set.load(std::memory_order_acquire)) {
+    return;
+  }
+  std::lock_guard<std::mutex> lock(g_display_mirror_mutex);
+  if (g_display_mirror.update != nullptr) {
+    g_display_mirror.update(g_display_mirror.context, update);
+  }
 }

 void RobloxTextSurfaceOverlay::ApplyUpdate(
@@ -80,6 +80,14 @@ Status RobloxWindowInputRuntime::Initialize() {
                   gamepad_status.message().c_str());
    }
  }
+  // XR tracked controllers join the same authoritative route. Initialize is a
+  // no-op (false) in non-VR builds or without an armed OpenXR backend; that is
+  // the normal state, not an error.
+  xr_controllers_initialized_ = xr_controllers_.Initialize(
+      &RobloxWindowInputRuntime::XrControllerEventCallback, this);
+  if (xr_controllers_initialized_) {
+    std::fprintf(stderr, "  [vr-input] XR controller delivery armed\n");
+  }
  return Status::Ok();
 }

@@ -108,6 +116,7 @@ void RobloxWindowInputRuntime::PlatformEventCallback(
          std::get_if<platform::WindowFocusEvent>(&event.payload)) {
    if (focus->focused) {
      self->gamepads_.ResendState();
+      self->xr_controllers_.ResendState();
    }
  }
 }
@@ -124,6 +133,10 @@ Status RobloxWindowInputRuntime::Shutdown() {
    window::ClearMouseLockQueryCallback();
    mouse_lock_query_registered_ = false;
  }
+  // Disconnect the synthetic XR controller while the router still processes
+  // events, so its release path runs through the normal route.
+  xr_controllers_.Shutdown();
+  xr_controllers_initialized_ = false;
  gamepads_.Shutdown();
  const RobloxInputSnapshot snapshot = runtime_.Snapshot();
  Status status = runtime_.Deactivate();
@@ -203,6 +216,37 @@ RobloxInputSnapshot RobloxWindowInputRuntime::Snapshot() const {
  return runtime_.Snapshot();
 }

+void RobloxWindowInputRuntime::InjectPlatformEvent(
+    const platform::PlatformEvent& event) {
+  // Same router and same thread as SDL delivery: the XR controller path is a
+  // producer of platform events, not a parallel input stack.
+  (void)runtime_.HandleEvent(event);
+}
+
+void RobloxWindowInputRuntime::XrControllerEventCallback(
+    void* context, const platform::PlatformEvent& event) {
+  auto* self = static_cast<RobloxWindowInputRuntime*>(context);
+  if (self != nullptr) {
+    self->InjectPlatformEvent(event);
+  }
+}
+
+void RobloxWindowInputRuntime::DrainXrControllers() {
+  if (!xr_controllers_initialized_) {
+    return;
+  }
+  xr_controllers_.Drain();
+}
+
+void RobloxWindowInputRuntime::RequestXrControllerHaptics(
+    int hand, float amplitude, std::uint64_t duration_ns, float frequency_hz) {
+  xr_controllers_.RequestHaptics(hand, amplitude, duration_ns, frequency_hz);
+}
+
+void RobloxWindowInputRuntime::StopXrControllerHaptics(int hand) {
+  xr_controllers_.StopHaptics(hand);
+}
+
 bool RobloxWindowInputRuntime::MouseLockQueryCallback(void* context,
                                                      bool* locked_center) {
  if (context == nullptr || locked_center == nullptr) {
@@ -0,0 +1,272 @@
+#include "runtime/roblox_xr_controller_input.h"
+
+#include <dlfcn.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+
+#include "mocktail/vr/xr_controller.h"
+#include "mocktail/vr/xr_controller_abi.h"
+
+namespace mocktail {
+namespace runtime {
+namespace {
+
+// SDL3 gamepad ordinals for the merged synthetic controller. Both hands feed
+// one device: left hand -> left stick/left shoulder/X/Y, right hand -> right
+// stick/right shoulder/A/B; menu -> START.
+constexpr std::int16_t kAxisFull = 32767;
+
+std::int16_t FloatToRaw(float value) {
+  const float clamped =
+      std::clamp(std::isfinite(value) ? value : 0.f, -1.f, 1.f);
+  return static_cast<std::int16_t>(std::lround(clamped * kAxisFull));
+}
+
+std::int16_t TriggerToRaw(float value) {
+  const float clamped =
+      std::clamp(std::isfinite(value) ? value : 0.f, 0.f, 1.f);
+  return static_cast<std::int16_t>(std::lround(clamped * kAxisFull));
+}
+
+std::uint64_t NowNs() {
+  timespec ts{};
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return static_cast<std::uint64_t>(ts.tv_sec) * 1000000000ULL +
+         static_cast<std::uint64_t>(ts.tv_nsec);
+}
+
+} // namespace
+
+bool RobloxXrControllerInput::Initialize(EventSink sink, void *context) {
+  if (sink == nullptr) {
+    return false;
+  }
+  // Resolve the XR controller ABI through dlsym so this module links and runs
+  // in non-VR builds (symbols absent) and stays inert while no backend is
+  // armed. Never a hard dependency on OpenXR here.
+  auto pop = reinterpret_cast<MocktailVrControllerPopFn>(
+      dlsym(RTLD_DEFAULT, "mocktail_vr_controller_pop_delivery"));
+  auto haptics = reinterpret_cast<MocktailVrControllerHapticsFn>(
+      dlsym(RTLD_DEFAULT, "mocktail_vr_controller_request_haptics"));
+  auto stop_haptics = reinterpret_cast<MocktailVrControllerStopHapticsFn>(
+      dlsym(RTLD_DEFAULT, "mocktail_vr_controller_stop_haptics"));
+  return InitializeWithAbi(sink, context, pop, haptics, stop_haptics);
+}
+
+bool RobloxXrControllerInput::InitializeWithAbi(
+    EventSink sink, void *context, MocktailVrControllerPopFn pop,
+    MocktailVrControllerHapticsFn haptics,
+    MocktailVrControllerStopHapticsFn stop_haptics) {
+  if (sink == nullptr || pop == nullptr) {
+    // No XR controller layer (non-VR build or backend without controllers).
+    // This is the normal case for --no-vr and must not be treated as failure.
+    sink_ = nullptr;
+    context_ = nullptr;
+    pop_ = nullptr;
+    haptics_ = nullptr;
+    stop_haptics_ = nullptr;
+    initialized_ = false;
+    return false;
+  }
+  sink_ = sink;
+  context_ = context;
+  pop_ = reinterpret_cast<void *>(pop);
+  haptics_ = reinterpret_cast<void *>(haptics);
+  stop_haptics_ = reinterpret_cast<void *>(stop_haptics);
+  initialized_ = true;
+  return true;
+}
+
+void RobloxXrControllerInput::Shutdown() {
+  if (connected_) {
+    // Release the synthetic controller once so no button or stick stays live
+    // after teardown.
+    EmitConnection(false);
+  }
+  initialized_ = false;
+  generation_ = 0;
+  force_resync_ = false;
+  sink_ = nullptr;
+  context_ = nullptr;
+  pop_ = nullptr;
+  haptics_ = nullptr;
+  stop_haptics_ = nullptr;
+}
+
+void RobloxXrControllerInput::EmitConnection(bool connected) {
+  if (sink_ == nullptr) {
+    return;
+  }
+  platform::GamepadDescriptor descriptor;
+  descriptor.family = platform::GamepadFamily::kXbox;
+  descriptor.name = connected ? "Mocktail VR Controllers" : "";
+  if (connected) {
+    // Advertise exactly the buttons/axes this route can emit so the router
+    // accepts them: SOUTH/EAST/WEST/NORTH, START, both stick clicks, both
+    // shoulders.
+    for (const std::uint8_t button :
+         {static_cast<std::uint8_t>(vr::ControllerButtonToSdlOrdinal(
+              0, vr::ControllerButton::kFaceWest)),
+          static_cast<std::uint8_t>(vr::ControllerButtonToSdlOrdinal(
+              0, vr::ControllerButton::kFaceNorth)),
+          static_cast<std::uint8_t>(vr::ControllerButtonToSdlOrdinal(
+              1, vr::ControllerButton::kFaceSouth)),
+          static_cast<std::uint8_t>(vr::ControllerButtonToSdlOrdinal(
+              1, vr::ControllerButton::kFaceEast)),
+          static_cast<std::uint8_t>(
+              vr::ControllerButtonToSdlOrdinal(0, vr::ControllerButton::kMenu)),
+          static_cast<std::uint8_t>(vr::ControllerButtonToSdlOrdinal(
+              0, vr::ControllerButton::kThumbstick)),
+          static_cast<std::uint8_t>(vr::ControllerButtonToSdlOrdinal(
+              1, vr::ControllerButton::kThumbstick)),
+          static_cast<std::uint8_t>(vr::ControllerButtonToSdlOrdinal(
+              0, vr::ControllerButton::kSqueeze)),
+          static_cast<std::uint8_t>(vr::ControllerButtonToSdlOrdinal(
+              1, vr::ControllerButton::kSqueeze))}) {
+      descriptor.buttons |= (std::uint32_t{1} << button);
+    }
+    // Six axes: both sticks (x/y) and both triggers.
+    descriptor.axes = 0b111111;
+  }
+  platform::GamepadConnectionEvent event;
+  event.instance_id = kInstanceLeft;
+  event.connected = connected;
+  event.descriptor = std::move(descriptor);
+  event.remapped = false;
+  sink_(context_, platform::PlatformEvent{NowNs(), std::move(event)});
+  connected_ = connected;
+  std::fill(std::begin(last_buttons_), std::end(last_buttons_), false);
+  if (connected) {
+    std::fprintf(stderr, "  [vr-input] XR controllers connected to Roblox as a "
+                         "single synthetic gamepad\n");
+  } else {
+    std::fprintf(stderr,
+                 "  [vr-input] XR controllers disconnected from Roblox\n");
+  }
+}
+
+void RobloxXrControllerInput::EmitButton(int sdl_button, bool pressed) {
+  if (sink_ == nullptr || sdl_button < 0) {
+    return;
+  }
+  platform::GamepadButtonEvent event;
+  event.instance_id = kInstanceLeft;
+  event.button = static_cast<std::uint8_t>(sdl_button);
+  event.pressed = pressed;
+  sink_(context_, platform::PlatformEvent{NowNs(), std::move(event)});
+  ++delivered_events_;
+}
+
+void RobloxXrControllerInput::EmitAxis(int sdl_axis, std::int16_t value) {
+  if (sink_ == nullptr || sdl_axis < 0) {
+    return;
+  }
+  platform::GamepadAxisEvent event;
+  event.instance_id = kInstanceLeft;
+  event.axis = static_cast<std::uint8_t>(sdl_axis);
+  event.value = value;
+  sink_(context_, platform::PlatformEvent{NowNs(), std::move(event)});
+  ++delivered_events_;
+}
+
+void RobloxXrControllerInput::Drain() {
+  if (!initialized_ || pop_ == nullptr || sink_ == nullptr) {
+    return;
+  }
+  auto pop = reinterpret_cast<MocktailVrControllerPopFn>(pop_);
+  for (int batch = 0; batch < kMaxDrainPerPump; ++batch) {
+    MocktailVrControllerDelivery delivery{};
+    if (pop(&delivery) == 0) {
+      return;
+    }
+    if (delivery.session_generation < generation_)
+      continue;
+    if (delivery.session_generation != generation_) {
+      if (connected_)
+        EmitConnection(false);
+      generation_ = delivery.session_generation;
+    }
+    // Connection transitions first so subsequent button/axis events land on a
+    // registered device. Either hand being connected presents the merged
+    // controller as connected.
+    const bool connected = delivery.connected[0] || delivery.connected[1];
+    if (connected != connected_) {
+      EmitConnection(connected);
+    }
+    if (!connected_) {
+      // Nothing to deliver while disconnected; the disconnect already released
+      // every control through the router.
+      continue;
+    }
+
+    if (force_resync_) {
+      delivery.resync = 1;
+      force_resync_ = false;
+    }
+    if (delivery.resync)
+      ++resyncs_;
+    // Levels belong to this delivery, not a separately read newer snapshot.
+    // Merge first so a release/unbound button on one hand cannot cancel the
+    // other.
+    bool merged[16] = {};
+    for (int hand = 0; hand < 2; ++hand) {
+      if (!delivery.connected[hand])
+        continue;
+      for (int index = 0; index < MOCKTAIL_VR_CONTROLLER_BUTTON_COUNT;
+           ++index) {
+        const int button = vr::ControllerButtonToSdlOrdinal(
+            hand, static_cast<vr::ControllerButton>(index));
+        if (button >= 0 && button < 16)
+          merged[button] |= delivery.button_levels[hand][index] != 0;
+      }
+    }
+    for (int button = 0; button < 16; ++button) {
+      if (delivery.resync || merged[button] != last_buttons_[button])
+        EmitButton(button, merged[button]);
+      last_buttons_[button] = merged[button];
+    }
+
+    // Analog axes. Delivered as raw int16 so the router applies its single
+    // deadzone; we never pre-filter (avoids a double deadzone).
+    if (delivery.axes_valid[0] || delivery.axes_valid[1]) {
+      EmitAxis(
+          vr::ControllerAxisToSdlOrdinal(0, vr::ControllerAxis::kThumbstickX),
+          FloatToRaw(delivery.axes[0]));
+      EmitAxis(
+          vr::ControllerAxisToSdlOrdinal(0, vr::ControllerAxis::kThumbstickY),
+          FloatToRaw(delivery.axes[1]));
+      EmitAxis(
+          vr::ControllerAxisToSdlOrdinal(1, vr::ControllerAxis::kThumbstickX),
+          FloatToRaw(delivery.axes[2]));
+      EmitAxis(
+          vr::ControllerAxisToSdlOrdinal(1, vr::ControllerAxis::kThumbstickY),
+          FloatToRaw(delivery.axes[3]));
+      EmitAxis(vr::ControllerAxisToSdlOrdinal(0, vr::ControllerAxis::kTrigger),
+               TriggerToRaw(delivery.axes[4]));
+      EmitAxis(vr::ControllerAxisToSdlOrdinal(1, vr::ControllerAxis::kTrigger),
+               TriggerToRaw(delivery.axes[5]));
+    }
+  }
+}
+
+void RobloxXrControllerInput::RequestHaptics(int hand, float amplitude,
+                                             std::uint64_t duration_ns,
+                                             float frequency_hz) {
+  if (haptics_ == nullptr || (hand != 0 && hand != 1)) {
+    return;
+  }
+  reinterpret_cast<MocktailVrControllerHapticsFn>(haptics_)(
+      hand, amplitude, duration_ns, frequency_hz);
+}
+
+void RobloxXrControllerInput::StopHaptics(int hand) {
+  if (stop_haptics_ == nullptr || (hand != 0 && hand != 1)) {
+    return;
+  }
+  reinterpret_cast<MocktailVrControllerStopHapticsFn>(stop_haptics_)(hand);
+}
+
+} // namespace runtime
+} // namespace mocktail
@@ -173,9 +173,35 @@ std::string BuildNetworkProxyUrl(const NetworkProxyConfig& proxy) {
         (ipv6 ? "]" : "") + ":" + std::to_string(proxy.port);
 }

+const char* VrModeName(VrMode mode) {
+  switch (mode) {
+    case VrMode::kOn:
+      return "on";
+    case VrMode::kAuto:
+      return "auto";
+    case VrMode::kOff:
+      break;
+  }
+  return "off";
+}
+
 RuntimeConfig RuntimeConfig::FromEnvironment(const Environment& environment) {
  RuntimeConfig config;
  config.headless_ = LegacyEnabled(environment, "MOCKTAIL_HEADLESS");
+  if (environment.Get("MOCKTAIL_VR_ENABLED").has_value()) {
+    config.vr_enabled_ = ReadBoolean(environment, "MOCKTAIL_VR_ENABLED",
+                                     kDefaultVrEnabled, &config.vr_valid_);
+    config.vr_mode_ = config.vr_enabled_ ? VrMode::kOn : VrMode::kOff;
+  } else if (const auto mode = environment.Get("MOCKTAIL_VR_MODE");
+             mode.has_value()) {
+    if (*mode == "auto") {
+      config.vr_mode_ = VrMode::kAuto;
+    } else {
+      config.vr_enabled_ = ReadBoolean(environment, "MOCKTAIL_VR_MODE",
+                                       kDefaultVrEnabled, &config.vr_valid_);
+      config.vr_mode_ = config.vr_enabled_ ? VrMode::kOn : VrMode::kOff;
+    }
+  }
  config.roblox_library_path_ = environment.GetOr(
      "ROBLOX_LIB_PATH", config.roblox_library_path_.string());
  config.graphics_backend_name_ = environment.GetOr(
@@ -281,6 +307,10 @@ RuntimeConfig RuntimeConfig::FromEnvironment(const Environment& environment) {
  }
  config.frame_rate_ = ParseFrameRatePolicy(
      environment.GetOr("MOCKTAIL_FRAME_RATE_LIMIT", "-1"));
+  config.vr_frame_rate_ = ParseFrameRatePolicy(
+      environment.GetOr("MOCKTAIL_VR_FRAME_RATE_LIMIT", "unlimited"));
+  config.vr_anti_aliasing_ =
+      environment.GetOr("MOCKTAIL_VR_ANTI_ALIASING", config.vr_anti_aliasing_);
  config.vsync_mode_ = environment.GetOr("MOCKTAIL_VSYNC", "auto");
  config.performance_ = ParsePerformancePolicy(
      environment.GetOr("MOCKTAIL_MULTITHREADED_RENDERING", "0"),
@@ -71,6 +71,28 @@ graphics:
  # unless frame_rate_limit is unlimited.
  # vsync: off

+# vr:
+  # String (default: off): experimental VR through OpenXR on supported Roblox
+  # builds. off always starts on the desktop. on always starts in VR, like
+  # --vr. auto starts in VR when SteamVR is already running with a connected
+  # headset (ALVR included), and on the desktop otherwise. auto never starts
+  # SteamVR. --vr and --no-vr override this for one launch. The older
+  # enabled: true/false still works as on/off; set one or the other.
+  # Standalone OpenXR test scene: mocktail-vr-probe --scene.
+  # mode: off
+  # String (default: fxaa): smooth jagged edges in the headset. Roblox draws
+  # the VR eyes without anti-aliasing, so each eye is filtered on its way to
+  # the headset. fxaa is the cheapest. smaa finds edges more precisely and
+  # keeps text and fine detail sharper, at a little more GPU time. off sends
+  # the eyes as rendered.
+  # anti_aliasing: fxaa
+  # Optional string or integer: frame-rate limit used instead of
+  # graphics.frame_rate_limit while VR is active. Same values: -1 (Roblox's
+  # own cap, usually 60), display, unlimited, or any positive integer. The
+  # default, unlimited, lets the OpenXR runtime pace frames at the headset's
+  # refresh rate.
+  # frame_rate_limit: unlimited
+
 performance:
  # Boolean (default: false): size Roblox scheduler/render queues from every
  # physical CPU core. A place's Lua/main thread can still remain serial.
@@ -168,6 +168,10 @@ bool ValidateAndMap(const ValueMap& yaml, ValueMap* environment,
      "device.keyboard",
      "runtime.headless",
      "runtime.roblox_library",
+      "vr.enabled",
+      "vr.mode",
+      "vr.anti_aliasing",
+      "vr.frame_rate_limit",
      "appearance.theme",
      "graphics.backend",
      "graphics.frame_rate_limit",
@@ -318,6 +322,46 @@ bool ValidateAndMap(const ValueMap& yaml, ValueMap* environment,
    }
    (*environment)["MOCKTAIL_THEME"] = *theme;
  }
+  // The file only sets MOCKTAIL_VR_MODE, so --vr and --no-vr
+  // (MOCKTAIL_VR_ENABLED) always win over it.
+  const auto enabled = value("vr.enabled");
+  const auto mode = value("vr.mode");
+  if (enabled.has_value() && mode.has_value()) {
+    *error = "set either vr.mode or vr.enabled, not both";
+    return false;
+  }
+  if (enabled.has_value()) {
+    bool parsed = false;
+    if (!ParseBoolean(*enabled, &parsed)) {
+      *error = "vr.enabled must be true or false";
+      return false;
+    }
+    (*environment)["MOCKTAIL_VR_MODE"] = parsed ? "on" : "off";
+  }
+  if (mode.has_value()) {
+    if (*mode != "on" && *mode != "off" && *mode != "auto") {
+      *error = "vr.mode must be on, off, or auto";
+      return false;
+    }
+    (*environment)["MOCKTAIL_VR_MODE"] = *mode;
+  }
+  if (const auto anti_aliasing = value("vr.anti_aliasing");
+      anti_aliasing.has_value()) {
+    if (*anti_aliasing != "fxaa" && *anti_aliasing != "smaa" &&
+        *anti_aliasing != "off") {
+      *error = "vr.anti_aliasing must be fxaa, smaa, or off";
+      return false;
+    }
+    (*environment)["MOCKTAIL_VR_ANTI_ALIASING"] = *anti_aliasing;
+  }
+  if (const auto frame_rate = value("vr.frame_rate_limit");
+      frame_rate.has_value()) {
+    if (!ParseFrameRatePolicy(*frame_rate).valid()) {
+      *error = "vr.frame_rate_limit is not supported: " + *frame_rate;
+      return false;
+    }
+    (*environment)["MOCKTAIL_VR_FRAME_RATE_LIMIT"] = *frame_rate;
+  }
  if (const auto backend = value("graphics.backend"); backend.has_value()) {
    if (RuntimeConfig::ParseGraphicsBackend(*backend) ==
        GraphicsBackend::kUnknown) {
@@ -712,7 +756,7 @@ bool LoadYaml(const std::filesystem::path& path, ValueMap* values, bool* loaded,
          *error = "device must be a preset scalar or detailed mapping";
          valid = false;
        }
-      } else if (key == "runtime" || key == "appearance" ||
+      } else if (key == "runtime" || key == "appearance" || key == "vr" ||
                 key == "graphics" || key == "performance" ||
                 key == "audio" || key == "window" || key == "input" ||
                 key == "compatibility" || key == "network") {
@@ -781,6 +825,12 @@ RuntimeConfigLoadResult LoadRuntimeConfig(
  result.config = RuntimeConfig::FromEnvironment(layered);
  if (!result.config.frame_rate().valid()) {
    result.error = "frame-rate policy is invalid";
+  } else if (!result.config.vr_frame_rate().valid()) {
+    result.error = "VR frame-rate policy is invalid";
+  } else if (!result.config.vr_valid()) {
+    result.error = "VR configuration is invalid: MOCKTAIL_VR_ENABLED must be "
+                   "1/0, true/false, or on/off, and MOCKTAIL_VR_MODE on, off, "
+                   "or auto";
  } else if (!result.config.device_profile_valid()) {
    result.error = "device profile is invalid";
  } else if (!result.config.input_capabilities().touch_enabled &&
@@ -821,6 +871,10 @@ RuntimeConfigLoadResult LoadRuntimeConfig(

 bool ExportRuntimeConfigEnvironment(const RuntimeConfig& config,
                                    std::string* error) {
+  if (!config.vr_valid()) {
+    if (error != nullptr) *error = "cannot export an invalid VR configuration";
+    return false;
+  }
  if (!config.fleasion_valid()) {
    if (error != nullptr) *error = "cannot export invalid Fleasion configuration";
    return false;
@@ -877,6 +931,8 @@ bool ExportRuntimeConfigEnvironment(const RuntimeConfig& config,
  const bool base_exported =
      SetEnvironmentValue("MOCKTAIL_HEADLESS", config.headless() ? "1" : "0",
                          error) &&
+      SetEnvironmentValue("MOCKTAIL_VR_ENABLED", config.vr_enabled() ? "1" : "0",
+                          error) &&
      SetEnvironmentValue("MOCKTAIL_DEVICE_PROFILE", std::string(device.name),
                          error) &&
      SetEnvironmentValue("MOCKTAIL_DEVICE_CLASS",
@@ -926,6 +982,10 @@ bool ExportRuntimeConfigEnvironment(const RuntimeConfig& config,
                          config.desktop_playability() ? "1" : "0", error) &&
      SetEnvironmentValue("MOCKTAIL_FRAME_RATE_LIMIT",
                          FrameRateValue(config.frame_rate()), error) &&
+      SetEnvironmentValue("MOCKTAIL_VR_FRAME_RATE_LIMIT",
+                          FrameRateValue(config.vr_frame_rate()), error) &&
+      SetEnvironmentValue("MOCKTAIL_VR_ANTI_ALIASING",
+                          config.vr_anti_aliasing(), error) &&
      SetEnvironmentValue("MOCKTAIL_VSYNC", config.vsync_mode(), error) &&
      SetEnvironmentValue(
          "MOCKTAIL_MULTITHREADED_RENDERING",