dim-ghub · Sep 12, 2026 · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -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

diff --git a/.gitmodules b/.gitmodules
@@ -4,3 +4,6 @@
 [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
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,12 @@ Release notes on GitHub are taken from the matching section here.
 - `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. FXAA now
+  smooths each eye on its way to the headset, with no measurable frame-time cost on a Quest 2 at 90 Hz.
+  `vr.anti_aliasing: off` turns it 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.
 
@@ -25,6 +31,14 @@ Release notes on GitHub are taken from the matching section here.
 - 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.
 
+### Changed
+
+- 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

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -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.
@@ -296,6 +298,7 @@ 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
@@ -599,6 +602,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

diff --git a/FAQ.md b/FAQ.md
@@ -75,7 +75,5 @@ Start WiVRn or SteamVR/ALVR, connect your headset, then run:
 ./build/mocktail --vr
 ```
 
-That branch's
-[README](https://github.com/CoderDayton/nightcap/blob/vr/README.md#experimental-vr)
-and [docs/VR.md](https://github.com/CoderDayton/nightcap/blob/vr/docs/VR.md)
-have the details, including how to try it without a headset.
+The [README](README.md#experimental-vr) and [docs/VR.md](docs/VR.md) have the
+details, including how to try it without a headset.
diff --git a/README.md b/README.md
@@ -148,6 +148,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
@@ -230,6 +232,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

diff --git a/cmake/MocktailInput.cmake b/cmake/MocktailInput.cmake
@@ -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

diff --git a/cmake/MocktailVR.cmake b/cmake/MocktailVR.cmake
@@ -0,0 +1,110 @@
+# 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})
+  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()
diff --git a/config/mocktail.example.yaml b/config/mocktail.example.yaml
@@ -52,6 +52,27 @@ 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; fxaa filters each eye on its way to the
+  # headset, which costs well under a millisecond. 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.

diff --git a/config/roblox_compatibility.json b/config/roblox_compatibility.json
@@ -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"
+      }
     }
   ]
 }