How joeyhodge/uevr works
UEVR is a Windows-only Unreal Engine VR mod/injection framework built as a native C++ runtime that runs inside the target game process. The repo is centered around the in-process mod loader and hook layer; the separate injector/front-end is referenced in the README but is not part of this tree.
1. Process entry and framework bootstrap
- src/Main.cpp and src/Framework.* form the runtime entry path.
- Mod, Mods, and WindowFilter provide the framework for enabling/disabling features and filtering game windows/events.
- ExceptionHandler is the crash/diagnostic boundary for the injected runtime.
2. Core hook boundary
- src/hooks/* contains the low-level interception points for Direct3D 11/12, XInput, DirectInput, and Windows messages.
- These hooks are the main boundary between the game’s normal execution and UEVR’s overlays, VR rendering, and input remapping.
3. VR subsystem
- src/mods/vr/* is the main VR feature stack.
- It owns runtime selection and integration (runtimes/OpenVR, runtimes/OpenXR, VRRuntime), headset/tracking hooks, and the VR overlay components.
- This layer translates engine state into stereo/pose updates and pushes them into the chosen VR runtime.
4. Graphics integration
- The VR module has separate D3D11 and D3D12 components plus helper code under src/mods/vr/d3d12.
- This is where frame submission, textures, command context, and overlay rendering meet the game’s graphics API.
- Precompiled shader assets under src/mods/vr/shaders/Compiled support the on-screen/VR rendering path.
5. Unreal Engine-specific interception
- src/mods/pluginloader/* contains hooks for Unreal internals such as fake stereo rendering, RHI texture functions, render target pooling, FUObjectArray, and UScriptStruct.
- src/mods/uobjecthook/* adds object-level introspection and SDK dumping.
- This is the engine boundary that makes the mod work across Unreal 4/5 versions without requiring game source.
6. Lua scripting and runtime extensibility
- lua-api/ is a separate scripting subsystem built on Lua and sol2.
- ScriptContext, ScriptState, and datatype bindings expose engine/game-facing objects to Lua.
- The provided examples show that scripting is used for user-authored behavior, UI, and configuration rather than just automation.
7. C++ plugin extensibility
- src/mods/PluginLoader.* and the include/uevr/* headers define the C++ plugin surface.
- Example plugins under examples/example_plugin and side-projects/sdk-test show the intended extension model.
- This is the main mod authoring boundary: internal runtime APIs on one side, game- and VR-specific extensions on the other.
8. Rendering diagnostics and analysis
- src/render/* contains shader compilation, shader override registry, frame resource inspection, and D3D12 diagnostics/export.
- These subsystems support debugging broken rendering, inspecting frames, and modifying shaders/effects to keep games playable in VR.
9. User-facing overlay and in-game UI
- The repo vendors/customizes ImGui in src/uevr-imgui and also has helper code in src/utility/ImGui.*.
- The overlay is used for the in-game menu, render inspector, config controls, and VR shortcuts described in the README.
- This UI sits on top of the hooked render path and is not a separate app.
10. External dependencies and runtime assumptions
- Major external/runtime dependencies are Unreal Engine SDK headers (dependencies/submodules/UESDK), OpenVR, OpenXR, Lua, glm, imgui, spdlog, and sol2.
- The architecture is heavily tied to Windows + DirectX 11/12 + Unreal Engine.
- Build orchestration is CMake-based (CMakeLists.txt, cmkr.cmake, cmake.toml) with CI workflows for build/release.
11. Auxiliary tools and packaging
- vr-plugin-nullifier is a small helper tool for disabling conflicting VR plugins in games.
- examples/renderlib provides a reusable rendering sample layer, likely for validating D3D/ImGui integration outside the full runtime.
- These are support artifacts around the main injection/runtime architecture, not the core product itself.
12. Primary data flow
- Game process starts → UEVR runtime injects/initializes → hooks intercept render/input/window calls → Unreal internals are patched for stereo/pose/render target behavior → VR runtime submits frames to OpenVR/OpenXR → ImGui/Lua/plugin layers extend behavior and expose configuration → diagnostics tools observe and modify rendering when needed.
Main entry points: VR.cpp VR Module · Framework.cpp Framework · Mods.cpp Mods · VRRuntime.hpp VR Runtime
Components 22
Runtime Core
Injected process entry, framework lifecycle, and shared mod management.
- Main · Injected process entry and runtime bootstrap.
src/Main.cpp - Framework · Coordinates runtime initialization and shutdown.
src/Framework.cpp - Mods · Enables and organizes framework features.
src/Mods.cpp - Mod · Common mod behavior and extension point.
src/Mod.cpp - Window Filter · Filters game windows and events.
src/WindowFilter.cpp - Crash Handler · Exception boundary for the injected runtime.
src/ExceptionHandler.cpp
Hook Boundary
Low-level interception of graphics, input, and window messages.
- D3D11 Hook · Intercepts Direct3D 11 render calls.
src/hooks/D3D11Hook.cpp - D3D12 Hook · Intercepts Direct3D 12 render calls.
src/hooks/D3D12Hook.cpp - XInput Hook · Intercepts controller input.
src/hooks/XInputHook.cpp - DirectInput Hook · Intercepts legacy keyboard and mouse input.
src/hooks/DInputHook.cpp - Win Message Hook · Intercepts Windows messages and focus behavior.
src/hooks/WindowsMessageHook.cpp
VR and Rendering
VR feature stack, graphics integration, diagnostics, and overlay rendering.
- VR Module · Main VR subsystem that ties tracking, overlays, and runtime selection together.
src/mods/VR.cpp - VR Runtime · Selects and drives OpenVR or OpenXR backends.
src/mods/vr/runtimes/VRRuntime.hpp - OpenVR · OpenVR integration layer.
src/mods/vr/runtimes/OpenVR.cpp - OpenXR · OpenXR integration layer.
src/mods/vr/runtimes/OpenXR.cpp - D3D11 Comp · VR rendering path for Direct3D 11.
src/mods/vr/D3D11Component.cpp - D3D12 Comp · VR rendering path for Direct3D 12.
src/mods/vr/D3D12Component.cpp - Overlay · In-game menu and VR overlay rendering.
src/mods/vr/OverlayComponent.cpp
Extensibility
Lua and C++ plugin surfaces plus example consumers.
- Plugin Loader · C++ plugin surface for mod authors.
src/mods/PluginLoader.cpp - Lua Loader · Embeds Lua and exposes runtime scripting.
src/mods/LuaLoader.cpp - Lua Bindings · Exports engine, ImGui, JSON, filesystem, and input types to scripts.
lua-api/lib/src/ScriptContext.cpp - Example Plugin · Reference C++ plugin implementation.
examples/example_plugin/Plugin.cpp
Connections 24
- Main → Framework: boots · Entry point initializes the framework.
- Framework → Mods: loads · Framework activates registered mods.
- Framework → Crash Handler: wraps · Runtime is guarded by crash handling.
- Mods → Mod: manages · Registry coordinates feature modules.
- Mods → Window Filter: applies · Filters window-level behavior.
- Framework → D3D11 Hook: installs · Framework enables graphics interception.
- Framework → D3D12 Hook: installs · Framework enables graphics interception.
- Framework → XInput Hook: installs · Framework enables input interception.
- Framework → DirectInput Hook: installs · Framework enables input interception.
- Framework → Win Message Hook: installs · Framework enables window-message interception.
- D3D11 Hook → VR Module: hands off · Graphics hook forwards into the VR feature stack.
- D3D12 Hook → VR Module: hands off · Graphics hook forwards into the VR feature stack.
- VR Module → VR Runtime: selects · VR module chooses backend runtime behavior.
- VR Runtime → OpenVR: uses · Backend option for OpenVR.
- VR Runtime → OpenXR: uses · Backend option for OpenXR.
- VR Module → D3D11 Comp: renders · VR module integrates the D3D11 rendering path.
- VR Module → D3D12 Comp: renders · VR module integrates the D3D12 rendering path.
- VR Module → Overlay: draws · VR module owns in-game overlay presentation.
- VR Module → Plugin Loader: extends · VR features are exposed to C++ plugins.
- VR Module → Lua Loader: extends · VR features are exposed to Lua scripts.
- Lua Loader → Lua Bindings: binds · Lua runtime exports native objects and helpers.
- Plugin Loader → Example Plugin: demonstrates · Example plugin shows the extension model.
- VR Module → Overlay: uses · Overlay sits on top of the hooked render path.
- VR Module → Plugin Loader: coordinates · Plugin hooks can influence VR behavior and rendering.