# joeyhodge/uevr architecture

> Architecture diagram of the GitHub repository joeyhodge/uevr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joeyhodge/uevr
- Repository: https://github.com/joeyhodge/uevr

## Overview

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: [`src/mods/VR.cpp`](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/VR.cpp) (VR Module), [`src/Framework.cpp`](https://github.com/joeyhodge/uevr/blob/ue57performance/src/Framework.cpp) (Framework), [`src/Mods.cpp`](https://github.com/joeyhodge/uevr/blob/ue57performance/src/Mods.cpp) (Mods), [`src/mods/vr/runtimes/VRRuntime.hpp`](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/runtimes/VRRuntime.hpp) (VR Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Runtime Core"]
  node_node_main["Main<br/>entrypoint<br/>[Main.cpp]"]
  node_node_framework["Framework<br/>lifecycle<br/>[Framework.cpp]"]
  node_node_mods["Mods<br/>mod-registry<br/>[Mods.cpp]"]
  node_node_mod["Mod<br/>[Mod.cpp]"]
  node_node_windowfilter["Window Filter<br/>window-policy<br/>[WindowFilter.cpp]"]
  node_node_exception["Crash Handler<br/>diagnostics"]
end

subgraph group_group_hooks["Hook Boundary"]
  node_node_d3d11hook["D3D11 Hook<br/>graphics-hook<br/>[D3D11Hook.cpp]"]
  node_node_d3d12hook["D3D12 Hook<br/>graphics-hook<br/>[D3D12Hook.cpp]"]
  node_node_xinputhook["XInput Hook<br/>input-hook<br/>[XInputHook.cpp]"]
  node_node_dinputhook["DirectInput Hook<br/>input-hook<br/>[DInputHook.cpp]"]
  node_node_winhook["Win Message Hook<br/>window-hook"]
end

subgraph group_group_vr["VR and Rendering"]
  node_node_vr["VR Module<br/>feature-stack<br/>[VR.cpp]"]
  node_node_vr_runtime["VR Runtime<br/>runtime-abstraction<br/>[VRRuntime.hpp]"]
  node_node_openvr["OpenVR<br/>vr-backend<br/>[OpenVR.cpp]"]
  node_node_openxr["OpenXR<br/>vr-backend<br/>[OpenXR.cpp]"]
  node_node_d3d11comp["D3D11 Comp<br/>graphics-path<br/>[D3D11Component.cpp]"]
  node_node_d3d12comp["D3D12 Comp<br/>graphics-path<br/>[D3D12Component.cpp]"]
  node_node_overlay["Overlay<br/>ui-layer"]
end

subgraph group_group_ext["Extensibility"]
  node_node_pluginloader["Plugin Loader<br/>plugin-api<br/>[PluginLoader.cpp]"]
  node_node_lua["Lua Loader<br/>script-runtime<br/>[LuaLoader.cpp]"]
  node_node_bindings["Lua Bindings<br/>[ScriptContext.cpp]"]
  node_node_example_plugin["Example Plugin<br/>sample-extension<br/>[Plugin.cpp]"]
end

node_node_main -->|"boots"| node_node_framework
node_node_framework -->|"loads"| node_node_mods
node_node_framework -->|"wraps"| node_node_exception
node_node_mods -->|"manages"| node_node_mod
node_node_mods -->|"applies"| node_node_windowfilter
node_node_framework -->|"installs"| node_node_d3d11hook
node_node_framework -->|"installs"| node_node_d3d12hook
node_node_framework -->|"installs"| node_node_xinputhook
node_node_framework -->|"installs"| node_node_dinputhook
node_node_framework -->|"installs"| node_node_winhook
node_node_d3d11hook -->|"hands off"| node_node_vr
node_node_d3d12hook -->|"hands off"| node_node_vr
node_node_vr -->|"selects"| node_node_vr_runtime
node_node_vr_runtime -->|"uses"| node_node_openvr
node_node_vr_runtime -->|"uses"| node_node_openxr
node_node_vr -->|"renders"| node_node_d3d11comp
node_node_vr -->|"renders"| node_node_d3d12comp
node_node_vr -->|"draws"| node_node_overlay
node_node_vr -->|"extends"| node_node_pluginloader
node_node_vr -->|"extends"| node_node_lua
node_node_lua -->|"binds"| node_node_bindings
node_node_pluginloader -.->|"demonstrates"| node_node_example_plugin
node_node_vr -->|"uses"| node_node_overlay
node_node_vr -->|"coordinates"| node_node_pluginloader

click node_node_main "https://github.com/joeyhodge/uevr/blob/ue57performance/src/Main.cpp"
click node_node_framework "https://github.com/joeyhodge/uevr/blob/ue57performance/src/Framework.cpp"
click node_node_mods "https://github.com/joeyhodge/uevr/blob/ue57performance/src/Mods.cpp"
click node_node_mod "https://github.com/joeyhodge/uevr/blob/ue57performance/src/Mod.cpp"
click node_node_windowfilter "https://github.com/joeyhodge/uevr/blob/ue57performance/src/WindowFilter.cpp"
click node_node_exception "https://github.com/joeyhodge/uevr/blob/ue57performance/src/ExceptionHandler.cpp"
click node_node_d3d11hook "https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/D3D11Hook.cpp"
click node_node_d3d12hook "https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/D3D12Hook.cpp"
click node_node_xinputhook "https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/XInputHook.cpp"
click node_node_dinputhook "https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/DInputHook.cpp"
click node_node_winhook "https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/WindowsMessageHook.cpp"
click node_node_vr "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/VR.cpp"
click node_node_vr_runtime "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/runtimes/VRRuntime.hpp"
click node_node_openvr "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/runtimes/OpenVR.cpp"
click node_node_openxr "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/runtimes/OpenXR.cpp"
click node_node_d3d11comp "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/D3D11Component.cpp"
click node_node_d3d12comp "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/D3D12Component.cpp"
click node_node_overlay "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/OverlayComponent.cpp"
click node_node_pluginloader "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/PluginLoader.cpp"
click node_node_lua "https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/LuaLoader.cpp"
click node_node_bindings "https://github.com/joeyhodge/uevr/blob/ue57performance/lua-api/lib/src/ScriptContext.cpp"
click node_node_example_plugin "https://github.com/joeyhodge/uevr/blob/ue57performance/examples/example_plugin/Plugin.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_framework,node_node_mods,node_node_mod,node_node_windowfilter,node_node_exception toneBlue
class node_node_d3d11hook,node_node_d3d12hook,node_node_xinputhook,node_node_dinputhook,node_node_winhook toneAmber
class node_node_vr,node_node_vr_runtime,node_node_openvr,node_node_openxr,node_node_d3d11comp,node_node_d3d12comp,node_node_overlay toneMint
class node_node_pluginloader,node_node_lua,node_node_bindings,node_node_example_plugin toneRose
```

## Components

### Runtime Core

Injected process entry, framework lifecycle, and shared mod management.

- [Main](https://github.com/joeyhodge/uevr/blob/ue57performance/src/Main.cpp): entrypoint · Injected process entry and runtime bootstrap. · `src/Main.cpp`
- [Framework](https://github.com/joeyhodge/uevr/blob/ue57performance/src/Framework.cpp): lifecycle · Coordinates runtime initialization and shutdown. · `src/Framework.cpp`
- [Mods](https://github.com/joeyhodge/uevr/blob/ue57performance/src/Mods.cpp): mod-registry · Enables and organizes framework features. · `src/Mods.cpp`
- [Mod](https://github.com/joeyhodge/uevr/blob/ue57performance/src/Mod.cpp): base-mod · Common mod behavior and extension point. · `src/Mod.cpp`
- [Window Filter](https://github.com/joeyhodge/uevr/blob/ue57performance/src/WindowFilter.cpp): window-policy · Filters game windows and events. · `src/WindowFilter.cpp`
- [Crash Handler](https://github.com/joeyhodge/uevr/blob/ue57performance/src/ExceptionHandler.cpp): diagnostics · Exception boundary for the injected runtime. · `src/ExceptionHandler.cpp`

### Hook Boundary

Low-level interception of graphics, input, and window messages.

- [D3D11 Hook](https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/D3D11Hook.cpp): graphics-hook · Intercepts Direct3D 11 render calls. · `src/hooks/D3D11Hook.cpp`
- [D3D12 Hook](https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/D3D12Hook.cpp): graphics-hook · Intercepts Direct3D 12 render calls. · `src/hooks/D3D12Hook.cpp`
- [XInput Hook](https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/XInputHook.cpp): input-hook · Intercepts controller input. · `src/hooks/XInputHook.cpp`
- [DirectInput Hook](https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/DInputHook.cpp): input-hook · Intercepts legacy keyboard and mouse input. · `src/hooks/DInputHook.cpp`
- [Win Message Hook](https://github.com/joeyhodge/uevr/blob/ue57performance/src/hooks/WindowsMessageHook.cpp): window-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](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/VR.cpp): feature-stack · Main VR subsystem that ties tracking, overlays, and runtime selection together. · `src/mods/VR.cpp`
- [VR Runtime](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/runtimes/VRRuntime.hpp): runtime-abstraction · Selects and drives OpenVR or OpenXR backends. · `src/mods/vr/runtimes/VRRuntime.hpp`
- [OpenVR](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/runtimes/OpenVR.cpp): vr-backend · OpenVR integration layer. · `src/mods/vr/runtimes/OpenVR.cpp`
- [OpenXR](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/runtimes/OpenXR.cpp): vr-backend · OpenXR integration layer. · `src/mods/vr/runtimes/OpenXR.cpp`
- [D3D11 Comp](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/D3D11Component.cpp): graphics-path · VR rendering path for Direct3D 11. · `src/mods/vr/D3D11Component.cpp`
- [D3D12 Comp](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/D3D12Component.cpp): graphics-path · VR rendering path for Direct3D 12. · `src/mods/vr/D3D12Component.cpp`
- [Overlay](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/vr/OverlayComponent.cpp): ui-layer · In-game menu and VR overlay rendering. · `src/mods/vr/OverlayComponent.cpp`

### Extensibility

Lua and C++ plugin surfaces plus example consumers.

- [Plugin Loader](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/PluginLoader.cpp): plugin-api · C++ plugin surface for mod authors. · `src/mods/PluginLoader.cpp`
- [Lua Loader](https://github.com/joeyhodge/uevr/blob/ue57performance/src/mods/LuaLoader.cpp): script-runtime · Embeds Lua and exposes runtime scripting. · `src/mods/LuaLoader.cpp`
- [Lua Bindings](https://github.com/joeyhodge/uevr/blob/ue57performance/lua-api/lib/src/ScriptContext.cpp): bindings · Exports engine, ImGui, JSON, filesystem, and input types to scripts. · `lua-api/lib/src/ScriptContext.cpp`
- [Example Plugin](https://github.com/joeyhodge/uevr/blob/ue57performance/examples/example_plugin/Plugin.cpp): sample-extension · Reference C++ plugin implementation. · `examples/example_plugin/Plugin.cpp`

## Connections

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