Library:Unreal Engine/Reflection data
The runtime reflection data of Unreal Engine 4 and 5 (FName storage, the global UObject array, UObject, UStruct, UClass, UFunction and the property classes) that modding and dumping tools read from a running game, with where the layouts change by engine version.
Overview
Every Unreal object in a running game is a UObject; the engine keeps them in one global array and names them through a global name table. Modding tools (UE4SS, UEDumper, SDK generators) work by finding two globals in the game executable, GUObjectArray (often called GObjects) and the name table (GNames, or the function FName::ToString), and then walking structures at fixed offsets. All offsets below are for 64-bit builds; they come from layout files shipped by tools, not from Epic's headers, and a game with engine changes can differ (UE4SS ships per-game overrides).
Finding the engine version
- The executable's version resource (File version / Product version) usually reads
4.27.2.0or5.3.2.0; UE4SS documents this as the first thing to check, with the warning that it sometimes holds the game version or is empty. - UE4SS can be told the version in
UE4SS-settings.ini([EngineVersionOverride] MajorVersion, MinorVersion); when both are set it skips its own version scan. - Cooked packages carry object versions that narrow the release: see Format:Unreal package (uasset)#Identifying the engine version.
- Layout milestones by version: 4.20 chunked object array; 4.23 name pool; 4.25 FField/FProperty; 4.27 case-preserving build variant; 5.05 and 5.07 change FUObjectItem.
FName and the name table
An FName is an index into the name table plus a number suffix. Up to UE 4.22 the table is a TNameEntryArray; from 4.23 it is the FNamePool. Details are in the facts below (#Facts).
- Up to 4.22: GNames points to chunk pointers; each chunk holds 0x4000
FNameEntry*; the 8-bit name text sits at 0x10 in the entry (0xC in 4.22 per UEDumper). - 4.23 and later: the pool starts with a lock, the current block number and byte cursor, then an array of block pointers; the comparison index of an FName is
block << 16 | offset; every entry is a 2-byte header (wide flag, length) followed by the characters. - A name read that returns garbage usually means the wrong case-preserving setting: in a case-preserving build (4.27 editor-style builds) FName is 12 bytes (comparison index, display index, number), UObject grows to 0x30 and entry offsets use a 4-byte stride.
The global object array
GUObjectArray is an FUObjectArray whose member ObjObjects (offset 0x10 in all 64-bit layouts read) is the array of FUObjectItem (24 bytes each: object pointer, flags, cluster root, serial). Before 4.20 it is a flat FFixedUObjectArray; from 4.20 it is the chunked FChunkedFixedUObjectArray (chunks of 64 Ki items; UEDumper's source comments that 4.20 used 65 Ki). Item i is Objects[i / 0x10000] + (i % 0x10000) * 0x18. A valid array has at least a few hundred and at most a few million elements, which is a quick sanity check when a candidate address is tested. Some servers built with STATS enlarge the item to 32 bytes.
UObject, UStruct, UClass, UFunction
A UObject starts with the vtable at 0, then ObjectFlags (0x8), InternalIndex (0xC, the index into the global array), the class pointer (0x10), the FName (0x18) and the outer pointer (0x20); size 0x28 from 4.12 through 5.x. UField adds Next at 0x28. UStruct holds SuperStruct, the child list and the property chain; UClass derives from it, then UFunction and UScriptStruct.
UProperty versus FProperty
Up to 4.24 properties were UObjects (UProperty derived from UField) and UStruct::Children lists both functions and properties. From 4.25 properties are lightweight FField/FProperty objects that are not in the global object array: UStruct::ChildProperties (0x50) is the property list, Children holds only UFunctions, and every offset after UField moves by 8 (FProperty ArrayDim at 0x38 instead of 0x30). Tools that walk the global array to find properties must walk ChildProperties of each struct instead from 4.25 on. FField stores a pointer to an FFieldClass (name, id, cast flags) instead of using the UClass.
How tools find the globals
UE4SS and Patternsleuth scan the executable's code for byte patterns and resolve the RIP-relative operand of a mov/lea/call; UE4SS lets the user supply a Lua file per symbol (GUObjectArray.lua, FName_ToString.lua, FName_Constructor.lua, StaticConstructObject.lua, GMalloc.lua, optional GNatives.lua, GUObjectHashTables.lua, ConsoleManager.lua). Example patterns are in the facts below. Compilers other than MSVC (Clang builds) and modified engines usually need new patterns; a reference build of the same engine version with PDB symbols, packaged as a Shipping game, is the recommended way to derive them.
Per-game layout overrides
UE4SS reads MemberVariableLayout.ini and VTableLayout.ini: one [Class] section per class, Member = 0xOFFSET, and for bit fields Member = 0xOFFSET:bitindex:bitwidth:storagebytes (for example ClassUnique = 0xC8:0:31:4, bCooked = 0xC8:31:1:4); UEP_TotalSize gives the class size. Templates exist for every release from 4.07 to 5.08 (assets/MemberVarLayoutTemplates/, assets/VTableLayoutTemplates/) and custom configs for modified games.
See also
- Technique:Byte signature (AOB) scanning: how the signatures for GUObjectArray and FName::ToString are built and resolved.
Facts
The struct, behavior and signature facts attached to this page hold the offsets with their source files.
Pitfalls
- Section names in UE4SS templates say FProperty even for 4.07-4.24 where the class is a UProperty.
- Values for UObject-derived classes beyond UObjectBase differ between 4.2x releases (UClass has a different layout for 4.18-4.20, 4.21, 4.22-4.23, 4.24 and 4.25-4.27): do not assume one UClass layout per major version.
- Unverified: shipped games with a custom allocator or encrypted GObjects/GNames pointers (UEDumper has XOR-key switches for these) need game-specific work.