# praydog/uevr architecture

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

- Interactive diagram: https://gitdiagram.com/praydog/uevr
- Repository: https://github.com/praydog/uevr
- Video tour (about a minute): https://gitdiagram.com/praydog/uevr/video

## Overview

##### Project Type and Purpose
- UEVR is a C++-based “injector/mod” tool for Unreal Engine 4/5 games that enables VR support (OpenVR/OpenXR).
- It consists of:
– A standalone Injector GUI (UEVRInjector.exe)
– A DLL that is injected into the target game process
– A modular hook-and-mod system (DirectX, input, UE object hooks)
– A scripting layer (Lua via sol2) and plugin loader

A. Injector Frontend
– UEVRInjector.exe (.NET 6.0 GUI for process selection, runtime choice, pre-injection settings)
B. Injection Engine & Core Framework (DLL)
– ExceptionHandler
– Framework (init, config)
– ModsManager (loads all mods)
C. Hook Manager
– WindowsMessageHook
– XInputHook
– DInputHook
– D3D11Hook / D3D12Hook (intercepts render calls)
D. Mod Subsystems
1. Lua Scripting (lua-api)
- LuaLoader
- ScriptContext / ScriptState (sol2 bindings)
2. Plugin Loader (C++ plugin system)
- PluginLoader
3. UObject Hooks (SDKDumper, UObjectHook helpers)
4. VR-Specific Mods
- Bindings, CVarManager, OverlayComponent
- Runtime Adapters: OpenVR / OpenXR modules
- RenderTargetPoolHook, FakeStereoRenderingHooks
E. Rendering & Shaders
– Shader compile scripts + compiled .inc shaders
– VR runtime frame submission (via OpenVR/OpenXR APIs)
– OpenVR SDK
– OpenXR SDK
– Lua (embedded)
– sol2 (C++↔Lua binding)
– ImGui (in-game menu)
– DirectX 11/12, Windows APIs

1) User interacts with Injector GUI → selects target process + runtime → clicks “Inject.”
2) Injector GUI → invokes DLL injection into target game process.
3) Injected DLL → initializes Core Framework → registers ExceptionHandler.
4) Core → sets up Hook Manager → installs DirectX, input, and Windows message hooks.
5) Core → invokes ModsManager →
- LuaLoader loads & executes user Lua scripts → communicates back via bindings.
- PluginLoader discovers C++ plugins → registers hooks or UI callbacks.
- VR mods configure stereoscopic rendering mode.
7) VR Runtime Adapter (OpenVR/OpenXR) → submits left/right eye textures to HMD.
8) In-game ImGui menu (via uevr-imgui) → overlays on top of game render → receives input via hooked XInput / Windows message hooks.

##### Architectural Patterns
- Layered Architecture:
– Frontend (GUI)
– Injection/Core
– Hook Abstraction Layer
– Mod/Plugin Layer
– Rendering/VR Adapter
- Plugin Pattern: C++ plugin loader for extensibility
- Adapter Pattern: Abstract VR runtimes (OpenVR vs. OpenXR)
- Embedding & Binding: sol2 for Lua scripting integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Process
    subgraph "Host Process (Injector GUI)" 
        direction TB
        Injector["UEVRInjector.exe"]:::frontend
    end

    %% Target Process
    subgraph "Target Process (Injected DLL)"
        direction TB

        subgraph "Injection Engine & Core Framework"
            direction TB
            Main["Main.cpp"]:::core
            ExceptionHandler["ExceptionHandler"]:::core
            Framework["Framework"]:::core
            ModsManager["ModsManager"]:::core
        end

        subgraph "Hook Manager"
            direction TB
            WindowsMessageHook["WindowsMessageHook"]:::hook
            XInputHook["XInputHook"]:::hook
            DInputHook["DInputHook"]:::hook
            D3D11Hook["D3D11Hook"]:::hook
            D3D12Hook["D3D12Hook"]:::hook
        end

        subgraph "Mod Subsystems"
            direction TB

            subgraph "Lua Scripting"
                direction TB
                LuaLoader["LuaLoader"]:::mod
                ScriptContext["ScriptContext"]:::mod
                ScriptState["ScriptState"]:::mod
            end

            subgraph "Plugin Loader"
                direction TB
                PluginLoader["PluginLoader"]:::mod
            end

            subgraph "UObject Hooks"
                direction TB
                UObjectHook["UObjectHook"]:::mod
                SDKDumper["SDKDumper"]:::mod
            end

            subgraph "VR-Specific Mods"
                direction TB
                Bindings["Bindings"]:::mod
                CVarManager["CVarManager"]:::mod
                OverlayComponent["OverlayComponent"]:::mod
                FakeStereoRenderingHook["FakeStereoRenderingHook"]:::mod
                RenderTargetPoolHook["RenderTargetPoolHook"]:::mod
                D3D11Component["D3D11Component"]:::mod
                D3D12Component["D3D12Component"]:::mod

                subgraph "VR Runtime Adapters"
                    direction TB
                    OpenVR["OpenVR"]:::mod
                    OpenXR["OpenXR"]:::mod
                    VRRuntime["VRRuntime"]:::mod
                end
            end
        end

        subgraph "Rendering & Shaders"
            direction TB
            ShaderSource["alpha_luminance_sprite_ps.fx"]:::mod
            ShaderHeaders["ps.hpp/vs.hpp"]:::mod
            CompiledShaders["Compiled *.inc"]:::mod
            CompileScript["compile_shaders.bat"]:::mod
        end

        subgraph "In-Game ImGui Menu"
            direction TB
            ImGuiWin32["imgui_impl_win32"]:::mod
            ImGuiDX11["imgui_impl_dx11"]:::mod
            ImGuiDX12["imgui_impl_dx12"]:::mod
            UevrImconfig["uevr_imconfig.hpp"]:::mod
            ImGuiUtil["ImGui.hpp"]:::mod
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        OpenVRSDK["OpenVR SDK"]:::ext
        OpenXRSDK["OpenXR SDK"]:::ext
        LuaDep["Lua"]:::ext
        Sol2["sol2"]:::ext
        ImGuiCore["ImGui Core"]:::ext
        DirectX["DirectX & Windows APIs"]:::ext
    end

    %% Connections
    Injector -->|"Inject()"| Main
    Main -->|"init Framework()"| Framework
    Main -->|"register ExceptionHandler()"| ExceptionHandler
    Framework -->|"setup hooks"| WindowsMessageHook
    Framework -->|"setup hooks"| XInputHook
    Framework -->|"setup hooks"| DInputHook
    Framework -->|"setup hooks"| D3D11Hook
    Framework -->|"setup hooks"| D3D12Hook
    Framework -->|"invoke ModsManager()"| ModsManager

    ModsManager -->|"loads"| LuaLoader
    ModsManager -->|"loads"| PluginLoader
    ModsManager -->|"loads"| UObjectHook
    ModsManager -->|"loads"| Bindings
    ModsManager -->|"loads"| CVarManager

    LuaLoader -->|"creates"| ScriptContext
    LuaLoader -->|"creates"| ScriptState

    D3D11Hook -->|"intercept draw calls"| ShaderSource
    D3D12Hook -->|"intercept draw calls"| ShaderSource
    ShaderSource -->|"compiled by"| CompileScript
    CompileScript -->|"generates"| CompiledShaders

    D3D11Hook -->|"forward frames"| OpenVR
    D3D11Hook -->|"forward frames"| OpenXR
    D3D12Hook -->|"forward frames"| OpenVR
    D3D12Hook -->|"forward frames"| OpenXR

    OpenVR -->|"SubmitFrame()"| OpenVRSDK
    OpenXR -->|"SubmitFrame()"| OpenXRSDK

    ImGuiWin32 -->|"input via hooks"| WindowsMessageHook
    ImGuiDX11 -->|"render via hook"| D3D11Hook
    ImGuiDX12 -->|"render via hook"| D3D12Hook
    ImGuiUtil -->|"wraps ImGui"| ImGuiWin32

    ImGuiCore --- ImGuiWin32
    LiUevr["UevrInjector.exe"] -.-> Injector

    %% Click Events
    click ExceptionHandler "https://github.com/praydog/uevr/blob/master/src/ExceptionHandler.hpp"
    click Framework "https://github.com/praydog/uevr/blob/master/src/Framework.hpp"
    click Main "https://github.com/praydog/uevr/blob/master/src/Main.cpp"
    click ModsManager "https://github.com/praydog/uevr/blob/master/src/Mods.hpp"
    click WindowsMessageHook "https://github.com/praydog/uevr/blob/master/src/hooks/WindowsMessageHook.hpp"
    click XInputHook "https://github.com/praydog/uevr/blob/master/src/hooks/XInputHook.hpp"
    click DInputHook "https://github.com/praydog/uevr/blob/master/src/hooks/DInputHook.hpp"
    click D3D11Hook "https://github.com/praydog/uevr/blob/master/src/hooks/D3D11Hook.hpp"
    click D3D12Hook "https://github.com/praydog/uevr/blob/master/src/hooks/D3D12Hook.hpp"
    click LuaLoader "https://github.com/praydog/uevr/blob/master/src/mods/LuaLoader.hpp"
    click ScriptContext "https://github.com/praydog/uevr/blob/master/lua-api/lib/include/ScriptContext.hpp"
    click ScriptState "https://github.com/praydog/uevr/blob/master/lua-api/lib/include/ScriptState.hpp"
    click PluginLoader "https://github.com/praydog/uevr/blob/master/src/mods/PluginLoader.hpp"
    click UObjectHook "https://github.com/praydog/uevr/blob/master/src/mods/UObjectHook.hpp"
    click SDKDumper "https://github.com/praydog/uevr/blob/master/src/mods/uobjecthook/SDKDumper.hpp"
    click Bindings "https://github.com/praydog/uevr/blob/master/src/mods/vr/Bindings.hpp"
    click CVarManager "https://github.com/praydog/uevr/blob/master/src/mods/vr/CVarManager.hpp"
    click OverlayComponent "https://github.com/praydog/uevr/blob/master/src/mods/vr/OverlayComponent.hpp"
    click FakeStereoRenderingHook "https://github.com/praydog/uevr/blob/master/src/mods/vr/FFakeStereoRenderingHook.hpp"
    click RenderTargetPoolHook "https://github.com/praydog/uevr/blob/master/src/mods/vr/RenderTargetPoolHook.hpp"
    click D3D11Component "https://github.com/praydog/uevr/blob/master/src/mods/vr/D3D11Component.hpp"
    click D3D12Component "https://github.com/praydog/uevr/blob/master/src/mods/vr/D3D12Component.hpp"
    click OpenVR "https://github.com/praydog/uevr/blob/master/src/mods/vr/runtimes/OpenVR.hpp"
    click OpenXR "https://github.com/praydog/uevr/blob/master/src/mods/vr/runtimes/OpenXR.hpp"
    click VRRuntime "https://github.com/praydog/uevr/blob/master/src/mods/vr/runtimes/VRRuntime.hpp"
    click ShaderSource "https://github.com/praydog/uevr/blob/master/src/mods/vr/shaders/alpha_luminance_sprite_ps.fx"
    click ShaderHeaders "https://github.com/praydog/uevr/blob/master/src/mods/vr/shaders/ps.hpp"
    click CompileScript "https://github.com/praydog/uevr/blob/master/src/mods/vr/shaders/compile_shaders.bat"
    click ImGuiWin32 "https://github.com/praydog/uevr/blob/master/src/uevr-imgui/imgui_impl_win32.h"
    click ImGuiDX11 "https://github.com/praydog/uevr/blob/master/src/uevr-imgui/imgui_impl_dx11.h"
    click ImGuiDX12 "https://github.com/praydog/uevr/blob/master/src/uevr-imgui/imgui_impl_dx12.h"
    click UevrImconfig "https://github.com/praydog/uevr/blob/master/src/uevr-imgui/uevr_imconfig.hpp"
    click ImGuiUtil "https://github.com/praydog/uevr/blob/master/src/utility/ImGui.hpp"

    %% Styles
    classDef frontend fill:#FFD580,stroke:#E09E00,color:#000;
    classDef core fill:#A0D995,stroke:#4F8A10,color:#000;
    classDef hook fill:#74C0FC,stroke:#1B62A8,color:#000;
    classDef mod fill:#D18FEB,stroke:#812B82,color:#000;
    classDef ext fill:#E8E8E8,stroke:#999,color:#000,stroke-dasharray: 5 5;
```
