5VR

5VR brings full 6DoF virtual reality to Grand Theft Auto V Legacy Story Mode. It is a runtime DLL-injection mod: a proxy loader hooks the game's D3D11 pipeline, a Script Hook V bridge drives the in-game camera per eye from your tracked head pose, and frames are submitted to your headset through OpenXR (default) or OpenVR — with an in-VR settings overlay, comfort options, and reprojection to smooth out the game's frame rate.

5VR is the public name of the project formerly developed under the codename GTAVR. Binaries, tools, config files, and environment variables still use the GTAVR name (GTAVOVR.exe, GTAVR_BACKEND, gtavr_settings.ini, …).

WARNING — STORY MODE ONLY

5VR works in Grand Theft Auto V Story Mode only. It must never be used in GTA Online. The mod's OnlineGuard continuously watches for online sessions and BattlEye anti-cheat presence and hard-disables the mod the moment either is detected. The disable is sticky for the rest of the game process, every detector fails closed, and there is intentionally no bypass — no config key, environment variable, registry value, or API can override it, and none will ever be added (see docs/online-guard.md). Modding GTA Online violates Rockstar's terms and gets players banned; this mod refuses to participate.

Use at your own risk. Even single-player modding may conflict with the game's EULA/ToS, and publisher enforcement policy can change at any time — by using 5VR you assume that risk (see docs/LEGAL.md). 5VR is an unofficial community project and is not affiliated with, endorsed by, or connected to Rockstar Games or Take-Two Interactive. You must own a legal copy of the game.

VR motion sickness is a real physiological risk — read docs/user/comfort.md before your first session.

Status

Experimental work in progress. The core pipeline runs on the primary target build, but many details are not yet confirmed on real hardware in a real headset; anything unconfirmed is labelled UNVERIFIED here and in docs/known-issues.md, which keeps an honest, under-promising list of what does not work yet. Read it before reporting bugs.

Features

• Full 6DoF head tracking — rotation and position, late-latched at presentation time; IPD and world scale always come from the VR runtime, never a hardcoded constant.
• Per-eye stereo rendering — the game camera is driven per eye through Script Hook V natives (the GH10 bridge path). Stereo modes: Native 3D AER (alternate-eye rendering, default) and Comfort Mono (one centered scene to both eyes, no stereoscopic depth). Smooth Stereo stays gated off until its evidence requirements pass.
• PoseWarp reprojection — rotation warp of the rendered frame to the freshest head pose at submit time (rotationWarp, on by default, OpenXR and OpenVR), plus optional depth-based rotation and translation reprojection (translationWarp, PoseWarp v2, OpenXR only, falls back to rotation-only when no matching scene depth is available).
• Comfort suite — locomotion vignette (on by default), opt-in snap turn with configurable angle, smooth-turn speed control, always-on cutscene theater mode, seated/standing calibration, quick recentre. Comfort is treated as a safety requirement (docs/user/comfort.md).
• In-VR settings overlay — ImGui-based, head-locked panel usable with controllers, mouse, or keyboard; changes persist automatically.
• Control panel — tools/GTAVR-Panel.bat: one-click runtime update, backend switch, game start, enable/disable toggle, live log tail, support bundle collection.
• Render-target caps and upscaling guards — eyeTargetMaxDimension (default 4096 px) plus a guarded per-eye pixel ceiling (Standard: 48 Mi-pixels/eye; Extreme: opt-in 65 Mi-pixels/eye and 8192 px, UNVERIFIED) keep "quality" settings from collapsing frametimes; the overlay reports requested vs. achieved eye size and why it was capped.
• Performance telemetry — frametime ring with p99/p99.9 reporting and CSV export (press F11 in-game); measurements are never averages.
• Two VR backends — OpenXR (primary, ADR-0006) and OpenVR for SteamVR-native setups.

Requirements

• GTA V Legacy, Story Mode, a supported build. The version-pinned manifest manifests/gtav_legacy.ini has sections for:

  • 1.0.3889.0 ([b3889]) — primary target. The camera pattern is confirmed against the live process (matrix resolves; camera control remains UNVERIFIED), and the HUD redirection registry is verified on this build. This is the only build the installer will set up, because the pinned ScriptHookV release hard-refuses every other game build.
  • 1.0.3095.0 ([b3095]) — manifest section present, patterns UNVERIFIED; the pinned ScriptHookV will not load on it.
  • GTA V Enhanced (GTA5_Enhanced.exe) — an experimental, fully UNVERIFIED manifest section matched by module name; not a supported install target.

  On an unknown build the mod logs a plain diagnostic and stays inert — there is no hardcoded fallback.

• Windows 10/11 x64.

• An OpenXR-capable headset runtime (recommended) or SteamVR (OpenVR).

• BattlEye disabled in the Rockstar Games Launcher (Launcher → Settings → General → uncheck BattlEye). This is Rockstar's own option for story-mode modding; the mod never touches BattlEye itself, and you cannot enter GTA Online while it is disabled.

• Internet access during the first install if you use the automated ScriptHookV acquisition (below).

• A GPU/driver that can hold a stable framerate in Story Mode — VR needs p99 frametime at or below your headset's reprojection threshold, not a high average (see docs/perf-report.md).

ScriptHookV is fetched at install time, never redistributed

5VR's camera bridge (GTAVRBridge.asi) is a Script Hook V plugin, but ScriptHookV is not part of this repository or any 5VR package. The setup (tools/launcher, ScriptHookPackage.cs) downloads one pinned release — ScriptHookV v3889.0 / 1158.13 — directly from its official publisher at dev-c.com, over HTTPS only, with redirects restricted to the dev-c.com domain and a bounded response size. It verifies the pinned SHA-256 of the archive and of each required inner file, then installs only ScriptHookV.dll and dinput8.dll (the publisher's ASI loader) into your game directory. Pre-existing files are backed up (.gtavr-backup), ownership is journaled in gtavr_scripthook_manifest.txt, and uninstall removes only bytes it can prove it owns. Any hash, size, network, or collision failure aborts before anything is changed. You may also install that exact ScriptHookV release manually from the official page instead.

Quick start

Easiest — no build required: download 5VR-QuickStart.exe from the Releases page and run it. The all-in-one setup locates your game directory automatically — or click Browse... and pick PlayGTAV.exe (or GTA5.exe) yourself — then installs the 5VR runtime (hash-verified), downloads the pinned, hash-verified ScriptHookV from its official publisher, and can launch the game straight into VR. Disable BattlEye first (above). The raw files are also available as 5VR-1.0.0.zip if you prefer a manual install via tools\install.bat.

From a cloned repository (developer workflow):

1. Disable BattlEye (above). Launch Story Mode once vanilla to confirm it works, then close GTA.

2. Build Release|x64 (see Building from source).

3. Install the runtime into your game directory (idempotent, every copied byte hash-verified; refuses unsupported game builds):

   tools\install.bat "C:\Program Files\Rockstar Games\Grand Theft Auto V"

   This installs the 5VR runtime only (version.dll proxy, OVRInject.dll, GTAVRBridge.asi, the OpenXR/OpenVR loaders, GTAVOVR.exe, the build manifest, config templates). Install ScriptHookV separately — via the setup's pinned download (above) or manually from the official page.

4. Optional preflight — checks the disabled marker, game build against manifests/, VR runtime, and BattlEye posture; launches and injects nothing:

   set GTAV_EXE_PATH=C:\Program Files\Rockstar Games\Grand Theft Auto V\GTA5.exe
   x64\Release\GTAVOVR.exe --check

   Exit codes: 0 ok-to-try · 2 unsupported build (no manifest section; the mod would stay inert) · 3 VR runtime missing · 4 injection failure · 5 mod disabled by gtavr.disabled.

5. Launch and play:

   tools\GTAVR-Play.bat

   One click: updates the installed runtime to match this build, runs the preflight, then starts the game. Or use tools\GTAVR-Panel.bat for the control panel (runtime update, backend switch, enable/disable, live log).

How injection happens

There is no manual injection step. The installer places OVRInjectShim beside GTA5.exe as version.dll — a proxy that forwards every VERSION export but first loads OVRInject.dll, before the game creates its D3D device and shaders (required for complete HUD shader discovery; ADR-0005). A pre-existing foreign version.dll is backed up and chain-loaded, so an earlier loader keeps working. GTAVOVR.exe remains as the development launcher (CreateRemoteThread injection plus the --check preflight); the shipped path is the proxy auto-load. Inside the game, GTAVRBridge.asi (ScriptHookV) applies the per-eye camera writes from the script thread while the render thread captures, warps, and submits each eye.

Uninstall / temporarily disable

tools\uninstall.bat "C:\Program Files\Rockstar Games\Grand Theft Auto V"

Uninstall removes only files whose hashes prove 5VR ownership, keeps your settings and logs, and restores a backed-up version.dll. To play normal Story Mode without uninstalling, use the Disable GTAVR toggle in the control panel (or the setup GUI): it writes an integrity-checked gtavr.disabled next-launch marker; Enable GTAVR removes it. The toggle is refused while GTA is running — loader state is latched at process start.

Choosing your VR backend — OpenXR or OpenVR

OpenXR is the default and recommended backend (ADR-0006). Use OpenVR for SteamVR-native headsets or when your OpenXR runtime misbehaves. Three selection mechanisms exist:

1. Environment variable — force a backend for anything launched from that shell:

   set GTAVR_BACKEND=openxr

   set GTAVR_BACKEND=openvr

2. Control panel switch — run tools\GTAVR-Panel.bat, pick the OpenXR (Pimax) or OpenVR (SteamVR) radio button, then click 2. Start game (auto-load). The panel passes GTAVR_BACKEND to the game process and persists the choice as [Runtime] backend= in %LOCALAPPDATA%\GTAVR\gtavr_settings.ini — the same file the in-headset overlay and the early-loaded version.dll core read (the game directory itself is admin-only, so the setting lives in the user-writable settings directory).

3. Point OpenXR at a specific runtime — XR_RUNTIME_JSON is passed through to the OpenXR loader:

   set XR_RUNTIME_JSON=C:\path\to\steamxr_win64.json

Concrete examples:

• Quest Link / Air Link / Virtual Desktop, WMR, Pimax → keep the default openxr with your headset's OpenXR runtime active.
• SteamVR-native headsets (Index, Vive) → either set GTAVR_BACKEND=openvr with SteamVR running, or keep OpenXR and set SteamVR as the OpenXR runtime (SteamVR → Settings → Developer).
• Pimax showing only its home environment → set Pimax Play to "no default environment", switch to SteamVR as the OpenXR runtime, or use the OpenVR backend — see docs/user/setup.md §6.

OpenVR caveat: its current texture-submission path cannot carry the historical pose a retained eye needs, so an AER request on OpenVR safely resolves to centered mono. Smooth Stereo is never selected implicitly on either backend.

Configuration

Config lives under GTAVR_SETTINGS_DIR (default: %LOCALAPPDATA%\GTAVR — user-writable, so overlay and panel changes persist even though the game directory is admin-only):

• gtavr_settings.ini — stereo mode, comfort, world scale, performance. Notable keys: stereoMode (1 = Native 3D AER default, 3 = Comfort Mono), vignetteEnabled / vignetteIntensity, snapTurning (default 0, opt-in) / snapTurnAngle / smoothTurnSpeed, worldScale, renderScale / renderQualityProfile, eyeTargetMaxDimension (hard cap on the per-eye target size, default 4096 px, 0 = off), rotationWarp (render→fresh-pose rotation warp at submit, default 1), translationWarp (PoseWarp v2 depth-based rotation+translation reprojection, default 1, OpenXR only). Overlay edits auto-save; the file is hot-reloaded.
• gtavr_camera.ini — camera-pose offsets (cameraOffsetX/Y/Z, default zero), image alignment (imageOffsetX/Y, imageScale), per-camera-type FOV overrides and camera-resolution bounds. Templates ship at the repo root.
• Useful environment variables: GTAVR_BACKEND, XR_RUNTIME_JSON, GTAVR_SETTINGS_DIR, GTAVR_LOG_DIR / GTAVR_LOG_PATH, GTAVR_VERBOSE=1 (debug channel).

Developer-only diagnostic INI keys (depthViz, headSpinDegS, eyeDumpDir, sceneCapture, depthWarpExperimental, …) exist for pipeline analysis. They are default-off, armed only via gtavr_settings.ini — environment variables deliberately do not arm them — and are documented in AGENTS.md. Leave them alone for normal play.

In-VR overlay & controls

The settings menu is a head-locked panel rendered into the headset — no alt-tab needed.

• Open/close: Delete or Insert (keyboard, works even before controllers connect), F10, or the controller menu button; both-grips / both-face-buttons combos also toggle it.
• Controllers: right thumbstick moves the cursor, trigger = left click, grip = right click; left thumbstick scrolls.
• Fallbacks: the physical mouse drives the overlay cursor when the game window is focused; arrow keys + Enter/Esc work too.
• What it exposes: stereo mode (Native 3D AER / Comfort Mono) with measured per-eye cadence, comfort options (vignette, snap turn), world scale, render quality/scale with requested-vs-achieved eye size, display refresh information, and Reset Image — the single recovery action that restores automatic image alignment and rebuilds the head reference.

All changes persist to gtavr_settings.ini. Press F11 in-game to force a perf CSV export (gtavr_perf.csv).

Building from source

• Open GTAVOVR.sln in Visual Studio and build Release|x64 (toolset v145). Projects: GTAVOVR (launcher), OVRInject (core), OVRInjectShim (proxy loader), GTAVRBridge (ScriptHookV bridge), tests/GTAVRTests.

• CLI build (Git Bash — use dash switches; /p: gets path-mangled):

  env -u GTAV_INSTALL_DIR "/c/Program Files/Microsoft Visual Studio/18/Community/MSBuild/Current/Bin/MSBuild.exe" GTAVOVR.sln -p:Configuration=Release -p:Platform=x64 -m -v:m

  env -u GTAV_INSTALL_DIR is required: the post-build copy into the game directory fails the build if that variable points at a non-writable path.

• Vendored dependencies live in ThirdParty/ (OpenVR headers, OpenXR SDK per ThirdParty/openxr/README.md, Dear ImGui per ThirdParty/imgui/SETUP.md with HAS_IMGUI, MinHook, DirectXMath, readerwriterqueue).

• A clean clone also needs the vendored binaries the build links (openvr_api.lib/.dll, openxr_loader.lib/.dll, GTAVRBridge/ScriptHookV.lib). Restore or verify them with:

  powershell -ExecutionPolicy Bypass -File tools\bootstrap_thirdparty.ps1
  powershell -ExecutionPolicy Bypass -File tools\bootstrap_thirdparty.ps1 -VerifyOnly

  The script hash-verifies (pinned SHA-256) what is present and re-fetches OpenVR v2.12.14 and the OpenXR loader 1.1.54 from their pinned upstream URLs. ScriptHookV.lib is non-redistributable and cannot be auto-fetched: download the Script Hook V SDK from dev-c.com/gtav/scripthookv (Alexander Blade) and copy lib\ScriptHookV.lib from the SDK archive to GTAVRBridge\ScriptHookV.lib — the script prints these instructions.

Testing

tests\run_tests.bat

builds tests/GTAVRTests.vcxproj (Release|x64; pass Debug to override) and runs the unit-test runner — 38 suites, 361 tests / 6713 checks green as of 2026-08-01. The samples/D3D11Cube slice has a golden-image harness: run it twice with GTAVR_SLICE_GOLDEN=40, then python samples/check_golden.py checks determinism and stereo disparity. Manual in-game validation follows docs/test-matrix.md — nothing counts as PASS without a capture or trace attached.

Troubleshooting

• Logs first. Every refusal or degradation is logged in plain language. The main log is gtavrInjectLog.txt (in the game directory when launched via GTAVR-Play.bat / the panel); override the location with GTAVR_LOG_PATH or GTAVR_LOG_DIR. Look for the GTAVR session summary block and the one-line verdict GTAVR MOD ACTIVE / GTAVR MOD INERT / OnlineGuard: *** MOD HARD-DISABLED *** reason: .... Set GTAVR_VERBOSE=1 for per-decision traces before reproducing a problem.
• Preflight exit codes (GTAVOVR.exe --check): 0 ok-to-try, 2 unsupported build, 3 runtime missing, 4 injection failure, 5 mod disabled by gtavr.disabled. Common log messages and their fixes (Unsupported game build, BattlEye active, No OpenXR runtime, Online session detected) are tabulated in docs/user/setup.md §4.
• Support bundle: tools\collect_logs.bat gathers the inject log, shim log, perf CSV, crash minidumps, config/manifest snapshots, and system info into a timestamped GTAVR_LogBundle_* folder on your Desktop (no game files). The control panel's Collect log bundle button does the same.
• Known issues: docs/known-issues.md is the honest, dated list of what is broken, degraded, or UNVERIFIED — check it before reporting.

Project layout

GTAVOVR/          dev launcher + preflight (CreateRemoteThread, --check)
OVRInject/        injected core: D3D11 hooks, stereo engine, OpenXR/OpenVR
                  backends, overlay, OnlineGuard, perf stats, shaders
OVRInjectShim/    shipped loader; installed beside GTA5.exe as version.dll
GTAVRBridge/      ScriptHookV .asi bridge (native camera writes, session natives)
ThirdParty/       vendored dependencies (OpenVR, OpenXR, ImGui, MinHook, ...)
manifests/        per-title, per-build version-pinned signatures/offsets/hashes
tools/            install/uninstall, launcher, control panel, log collector,
                  third-party bootstrap, pattern scanners
tests/            unit-test runner + injection-lifecycle harness
samples/          D3D11Cube vertical slice + golden-image harness
docs/             architecture, ADRs, legal, known issues, test matrix,
                  perf report, docs/user/ setup & comfort guides

Credits

Third-party components (see docs/THIRD_PARTY_NOTICES.md for full license texts):

• OpenVR — Valve Corporation, BSD 3-Clause
• OpenXR headers and loader — The Khronos Group Inc., Apache-2.0 / MIT
• Dear ImGui — Omar Cornut and contributors, MIT
• MinHook — Tsuda Kageyu and contributors, BSD 2-Clause
• DirectXMath — Microsoft Corporation, MIT
• readerwriterqueue — Cameron Desrochers, Simplified BSD
• Script Hook V — Alexander Blade. Never redistributed; the installer downloads one pinned, hash-verified release from the official publisher at the user's request.

Design knowledge was informed by public analysis of prior third-party VR mods. No code, shaders, binaries, or assets from those works are copied or distributed (see docs/LEGAL.md).

License

5VR's own code is proprietary — see LICENSE. Third-party components under ThirdParty/ remain under their own licenses (docs/THIRD_PARTY_NOTICES.md).