# vozdyxstuff/re-ue4ss architecture

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

- Interactive diagram: https://gitdiagram.com/vozdyxstuff/re-ue4ss
- Repository: https://github.com/vozdyxstuff/re-ue4ss

## Overview

#### Purpose and Deliverables
UE4SS is a native Unreal Engine 4/5 runtime extension for game modding, inspection, and reverse-engineering. It is deployed into a game’s Win64 binaries directory, typically through a proxy DLL, then exposes Lua and C++ mod APIs, Blueprint loading, reflection/property tooling, and code/mapping generators. Primary runtime sources are `UE4SS/src/main_ue4ss_rewritten.cpp`, `UE4SS/src/UE4SSProgram.cpp`, and `UE4SS/src/UE4SSRuntime.cpp`.

#### Injection and Runtime Bootstrap
A generated proxy DLL forwards a chosen Windows DLL’s exports while loading UE4SS into the game process. `UE4SS/proxy_generator/main.cpp` and `UE4SS/proxy_generator/proxy/CMakeLists.txt` define this proxy-generation/deployment boundary. The core program initializes crash handling, settings, signature resolution, hooks, and the runtime against the host Unreal process (`UE4SS/src/UE4SSProgram.cpp`, `UE4SS/src/UE4SSRuntime.cpp`, `UE4SS/src/Signatures.cpp`).

#### Unreal Compatibility and Memory Boundary
UE4SS bridges into an unknown game/engine binary through AOB signatures, version-specific layouts, and direct Unreal object access. `UE4SS/include/UnrealDef.hpp` supplies engine-facing definitions; `UE4SS/include/Signatures.hpp` represents address discovery; `UE4SS/include/UnrealCustom/CustomProperty.hpp` supports nonstandard reflected properties. Per-game overrides—settings, signatures, member-variable, and vtable layouts—are distributed under `assets/CustomGameConfigs/`; e.g., `assets/CustomGameConfigs/Satisfactory/UE4SS-settings.ini`.

#### Mod Execution Model
The mod layer supports Lua scripts and native C++ DLL mods through a shared mod abstraction: `UE4SS/include/Mod/Mod.hpp`, `UE4SS/src/Mod/LuaMod.cpp`, and `UE4SS/src/Mod/CppMod.cpp`. Runtime discovery/configuration loads bundled and user mod directories, with Lua scripts such as `assets/Mods/BPModLoaderMod/Scripts/main.lua` using the exposed API. The Lua boundary consists of interpreter/library setup and bindings for Unreal types, containers, hooks, scheduling, and custom properties (`UE4SS/src/LuaLibrary.cpp`, `UE4SS/src/LuaType/LuaUObject.cpp`, `UE4SS/include/LuaCustomMemberFunctions.hpp`).

#### UI, Inspection, and Diagnostics
An in-process ImGui UI provides console, debugger, profiler, dump controls, and live object/property viewing. The UI coordinator is `UE4SS/src/GUI/GUI.cpp`; rendering backends include DirectX 11 and GLFW/OpenGL (`UE4SS/src/GUI/DX11.cpp`, `UE4SS/src/GUI/GLFW3_OpenGL3.cpp`). Live View reads and edits loaded Unreal objects through reflection filters (`UE4SS/src/GUI/LiveView.cpp`, `UE4SS/include/GUI/LiveView/Filter/HasProperty.hpp`). Filesystem watching allows runtime reaction to asset/mod changes (`UE4SS/src/FilesystemWatcher.cpp`).

#### Generation and Dump Pipelines
Runtime reflection data can be converted into SDK headers, UHT-compatible headers, JSON, object text, and `.usmap` mappings. SDK generation is centered on `UE4SS/src/SDKGenerator/Generator.cpp` and `UE4SS/src/SDKGenerator/UEHeaderGenerator.cpp`; mapping generation is in `UE4SS/src/USMapGenerator/Generator.cpp`. These output-oriented stages are separated from the injected mod runtime but consume its discovered Unreal metadata.

#### Companion Tool and Build Infrastructure
`UVTD` is a separate native command-line tool for PDB/symbol analysis and generating Unreal virtual/member-variable/Lua-binding artifacts (`UVTD/src/main.cpp`, `UVTD/src/UVTD.cpp`, `UVTD/src/UnrealVirtualGenerator.cpp`). The repository is principally C++23/CMake, with xmake metadata and a Rust `patternsleuth_bind` dependency (`CMakeLists.txt`, `UE4SS/CMakeLists.txt`, `deps/first/patternsleuth_bind/src/lib.rs`). Material dependencies include Lua, PolyHook, Zydis, ImGui, GLFW, OpenGL/GLAD, Tracy, raw PDB parsing, and the Unreal pseudo-code submodule. Windows is the deployment target; Linux is supported for Windows cross-compilation via xwin or Wine/MSVC toolchains.

Main entry points: [`UE4SS/src/UE4SSRuntime.cpp`](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/UE4SSRuntime.cpp) (UE4SS runtime), [`UE4SS/include/UnrealDef.hpp`](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/include/UnrealDef.hpp) (Unreal memory bridge), [`UE4SS/src/UE4SSProgram.cpp`](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/UE4SSProgram.cpp) (Program bootstrap), [`UE4SS/proxy_generator/main.cpp`](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/proxy_generator/main.cpp) (Generated proxy DLL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Injection & Runtime"]
  node_proxy["Generated proxy DLL<br/>injection proxy<br/>[main.cpp]"]
  node_proxy_build["Proxy build definition<br/>CMake<br/>[CMakeLists.txt]"]
  node_entrypoint["UE4SS entrypoint<br/>runtime entry"]
  node_program["Program bootstrap<br/>runtime coordinator<br/>[UE4SSProgram.cpp]"]
  node_runtime["UE4SS runtime<br/>engine runtime<br/>[UE4SSRuntime.cpp]"]
  node_signatures["Signature resolution<br/>AOB discovery<br/>[Signatures.cpp]"]
  node_unreal_bridge["Unreal memory bridge<br/>engine definitions<br/>[UnrealDef.hpp]"]
  node_game_configs["Per-game overrides<br/>game configuration"]
end

subgraph group_mods["Mod APIs &amp; UI"]
  node_mod_abstraction["Mod abstraction<br/>mod API<br/>[Mod.hpp]"]
  node_lua_mod["Lua mods<br/>script mod runtime<br/>[LuaMod.cpp]"]
  node_cpp_mod["C++ DLL mods<br/>native mod runtime<br/>[CppMod.cpp]"]
  node_lua_bindings["Lua Unreal bindings<br/>Lua API layer<br/>[LuaLibrary.cpp]"]
  node_bundled_script["BPModLoader script<br/>bundled Lua mod<br/>[main.lua]"]
  node_ui["ImGui tools<br/>in-process UI<br/>[GUI.cpp]"]
  node_live_view["Live View<br/>reflection inspector<br/>[LiveView.cpp]"]
end

subgraph group_generation["Reflection Outputs"]
  node_sdk_generator["SDK/header generator<br/>reflection exporter<br/>[Generator.cpp]"]
  node_usmap_generator["USMap generator<br/>mapping exporter<br/>[Generator.cpp]"]
end

subgraph group_tooling["Companion Tooling"]
  node_uvtd["UVTD<br/>native CLI tool<br/>[main.cpp]"]
  node_build["CMake build<br/>build system<br/>[CMakeLists.txt]"]
  node_patternsleuth["patternsleuth_bind<br/>Rust dependency<br/>[lib.rs]"]
end

node_game{{"Host Unreal game<br/>process"}}

node_proxy_build -->|"builds"| node_proxy
node_proxy -->|"loads into"| node_game
node_proxy -->|"loads"| node_entrypoint
node_entrypoint -->|"starts"| node_program
node_program -->|"initializes"| node_runtime
node_program -->|"resolves addresses"| node_signatures
node_game_configs -.->|"overrides settings"| node_program
node_game_configs -.->|"supplies signatures/layouts"| node_signatures
node_signatures -->|"locates engine access"| node_unreal_bridge
node_runtime -->|"uses"| node_unreal_bridge
node_runtime -->|"hosts"| node_mod_abstraction
node_mod_abstraction -->|"implements"| node_lua_mod
node_mod_abstraction -->|"implements"| node_cpp_mod
node_lua_mod -->|"uses"| node_lua_bindings
node_bundled_script -->|"runs in"| node_lua_mod
node_lua_bindings -->|"binds"| node_unreal_bridge
node_runtime -->|"hosts"| node_ui
node_ui -->|"includes"| node_live_view
node_live_view -->|"inspects"| node_unreal_bridge
node_runtime -->|"provides metadata"| node_sdk_generator
node_runtime -->|"provides metadata"| node_usmap_generator
node_build -->|"configures"| node_proxy_build
node_build -->|"integrates"| node_patternsleuth
node_uvtd -.->|"generates artifacts for"| node_unreal_bridge

click node_proxy "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/proxy_generator/main.cpp"
click node_proxy_build "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/proxy_generator/proxy/CMakeLists.txt"
click node_entrypoint "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/main_ue4ss_rewritten.cpp"
click node_program "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/UE4SSProgram.cpp"
click node_runtime "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/UE4SSRuntime.cpp"
click node_signatures "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/Signatures.cpp"
click node_unreal_bridge "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/include/UnrealDef.hpp"
click node_mod_abstraction "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/include/Mod/Mod.hpp"
click node_lua_mod "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/Mod/LuaMod.cpp"
click node_cpp_mod "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/Mod/CppMod.cpp"
click node_lua_bindings "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/LuaLibrary.cpp"
click node_bundled_script "https://github.com/vozdyxstuff/re-ue4ss/blob/main/assets/Mods/BPModLoaderMod/Scripts/main.lua"
click node_ui "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/GUI/GUI.cpp"
click node_live_view "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/GUI/LiveView.cpp"
click node_sdk_generator "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/SDKGenerator/Generator.cpp"
click node_usmap_generator "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/USMapGenerator/Generator.cpp"
click node_uvtd "https://github.com/vozdyxstuff/re-ue4ss/blob/main/UVTD/src/main.cpp"
click node_build "https://github.com/vozdyxstuff/re-ue4ss/blob/main/CMakeLists.txt"
click node_patternsleuth "https://github.com/vozdyxstuff/re-ue4ss/blob/main/deps/first/patternsleuth_bind/src/lib.rs"

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_proxy,node_proxy_build,node_entrypoint,node_program,node_runtime,node_signatures,node_unreal_bridge,node_game_configs toneBlue
class node_mod_abstraction,node_lua_mod,node_cpp_mod,node_lua_bindings,node_bundled_script,node_ui,node_live_view toneAmber
class node_sdk_generator,node_usmap_generator toneMint
class node_uvtd,node_build,node_patternsleuth toneRose
class node_game toneNeutral
```

## Components

### Injection & Runtime

Loads UE4SS into the host game and establishes engine access.

- [Generated proxy DLL](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/proxy_generator/main.cpp): injection proxy · Forwards a selected Windows DLL while loading UE4SS. · `UE4SS/proxy_generator/main.cpp`
- [Proxy build definition](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/proxy_generator/proxy/CMakeLists.txt): CMake · `UE4SS/proxy_generator/proxy/CMakeLists.txt`
- [UE4SS entrypoint](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/main_ue4ss_rewritten.cpp): runtime entry · `UE4SS/src/main_ue4ss_rewritten.cpp`
- [Program bootstrap](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/UE4SSProgram.cpp): runtime coordinator · Initializes crash handling, settings, signatures, hooks, and runtime. · `UE4SS/src/UE4SSProgram.cpp`
- [UE4SS runtime](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/UE4SSRuntime.cpp): engine runtime · `UE4SS/src/UE4SSRuntime.cpp`
- [Signature resolution](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/Signatures.cpp): AOB discovery · Finds game addresses in unknown engine binaries. · `UE4SS/src/Signatures.cpp`
- [Unreal memory bridge](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/include/UnrealDef.hpp): engine definitions · Version-aware layouts and direct object access. · `UE4SS/include/UnrealDef.hpp`
- **Per-game overrides**: game configuration · Settings, signatures, member layouts, and vtable layouts.

### Mod APIs & UI

Executes mods and exposes in-process interaction tools.

- [Mod abstraction](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/include/Mod/Mod.hpp): mod API · Shared interface for Lua and native mods. · `UE4SS/include/Mod/Mod.hpp`
- [Lua mods](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/Mod/LuaMod.cpp): script mod runtime · `UE4SS/src/Mod/LuaMod.cpp`
- [C++ DLL mods](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/Mod/CppMod.cpp): native mod runtime · `UE4SS/src/Mod/CppMod.cpp`
- [Lua Unreal bindings](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/LuaLibrary.cpp): Lua API layer · Exposes Unreal types, containers, hooks, scheduling, and properties. · `UE4SS/src/LuaLibrary.cpp`
- [BPModLoader script](https://github.com/vozdyxstuff/re-ue4ss/blob/main/assets/Mods/BPModLoaderMod/Scripts/main.lua): bundled Lua mod · `assets/Mods/BPModLoaderMod/Scripts/main.lua`
- [ImGui tools](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/GUI/GUI.cpp): in-process UI · Console, debugger, profiler, dumps, and live object inspection. · `UE4SS/src/GUI/GUI.cpp`
- [Live View](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/GUI/LiveView.cpp): reflection inspector · Reads and edits loaded Unreal objects through filters. · `UE4SS/src/GUI/LiveView.cpp`

### Reflection Outputs

Converts discovered Unreal metadata into export formats.

- [SDK/header generator](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/SDKGenerator/Generator.cpp): reflection exporter · Produces SDK and UHT-compatible headers. · `UE4SS/src/SDKGenerator/Generator.cpp`
- [USMap generator](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UE4SS/src/USMapGenerator/Generator.cpp): mapping exporter · Produces .usmap mappings from reflection data. · `UE4SS/src/USMapGenerator/Generator.cpp`

### Companion Tooling

Build-time and offline analysis components.

- [UVTD](https://github.com/vozdyxstuff/re-ue4ss/blob/main/UVTD/src/main.cpp): native CLI tool · Analyzes PDB symbols and generates Unreal artifacts. · `UVTD/src/main.cpp`
- [CMake build](https://github.com/vozdyxstuff/re-ue4ss/blob/main/CMakeLists.txt): build system · C++23 build and dependency integration. · `CMakeLists.txt`
- [patternsleuth_bind](https://github.com/vozdyxstuff/re-ue4ss/blob/main/deps/first/patternsleuth_bind/src/lib.rs): Rust dependency · Signature-pattern dependency. · `deps/first/patternsleuth_bind/src/lib.rs`

### Other components

- **Host Unreal game**: process · Target Win64 game process.

## Connections

- Proxy build definition → Generated proxy DLL: builds
- Generated proxy DLL → Host Unreal game: loads into
- Generated proxy DLL → UE4SS entrypoint: loads
- UE4SS entrypoint → Program bootstrap: starts
- Program bootstrap → UE4SS runtime: initializes
- Program bootstrap → Signature resolution: resolves addresses
- Per-game overrides → Program bootstrap: overrides settings
- Per-game overrides → Signature resolution: supplies signatures/layouts
- Signature resolution → Unreal memory bridge: locates engine access
- UE4SS runtime → Unreal memory bridge: uses
- UE4SS runtime → Mod abstraction: hosts
- Mod abstraction → Lua mods: implements
- Mod abstraction → C++ DLL mods: implements
- Lua mods → Lua Unreal bindings: uses
- BPModLoader script → Lua mods: runs in
- Lua Unreal bindings → Unreal memory bridge: binds
- UE4SS runtime → ImGui tools: hosts
- ImGui tools → Live View: includes
- Live View → Unreal memory bridge: inspects
- UE4SS runtime → SDK/header generator: provides metadata
- UE4SS runtime → USMap generator: provides metadata
- CMake build → Proxy build definition: configures
- CMake build → patternsleuth_bind: integrates
- UVTD → Unreal memory bridge: generates artifacts for