Note: Before diving in, we highly recommend that you first read the API introduction to gain a solid understanding of the foundational concepts. Also Understanding the Role of API is very essential for this library.
- StaticFindObject
- StaticLoadObject
- GetNameByIndex
- GetNameByIndexF
- GetObjectName
- GetObjectNameF
- ProcessEvent
- IsObjectOfClass
- GetObject
- FindObject
- LoadObject
- LoadAsset
- GetClassOffset
- GetObjectByIndex
- GetObjectsCount
- WorldToScreen
- LineTraceSingle
- RotationToVector
- StringToFName
- FindObjectsOfClass
- FreeArray
- Free
- FTextToFString
- FTextGet
- FStringGet
- TransformToMatrixWithScale
- GetGameVersionStr
- GetGameVersion
- GetEngineVersion
- GetEngine
- GetWorld
- GetGameInstance
- GetPersistantLevel
- GetActors
- GetActorsByLevel
- GetLocalPlayer
- GetPlayerController
- GetPlayerCameraManager
- GetLocalPawn
- GetCameraInfo
- GetViewMatrix
- GetViewTargetRootPos
- GetViewTargetPelvisPos
- GetViewTargetHeadPos
- GetAllActorsOfClass
Unreal Engine is a robust game engine developed by Epic Games. Renowned for its power and popularity, it's the driving force behind games like Fortnite, funding one of the world's largest open-source projects.
To effectively use this Lua library, a basic understanding of Unreal Engine's core concepts is crucial. Terms like UWorld, UObject, AActor, FName, FString, UFunction, UClass, and so on, are essential. We won't delve into Unreal Engine's architecture here, as it's beyond the scope of this documentation. However, once you're familiar with these terms, you'll be well-equipped to harness this library to manipulate the game architecture and create a wide array of features and behaviors.
For a deeper understanding, you might also find the Memory Library documentation helpful. Without it, this library's utility is somewhat limited.
We suggest reading Unreal Engine's official documentation for specific functions you plan to use, as many functions in this library are essentially wrappers for Unreal Engine's native functions. While these are already well-documented by Unreal Engine, note that not all functionalities in this library are documented there - some features are unique to this Lua Engine, such as utility or helper functions.
To make use of this library, you'll need to load it at the beginning of your Lua script as shown below:
local ue = require("unreal_engine", true)Doing so will load the library's functions into a Lua table named ue. Feel free to rename this variable as you want.
function StaticFindObject(
class: number[ptr],
outer: number[ptr],
objectName: string,
exact: bool = false
) -> number[ptr]|nilTries to find an object in memory.
class: the address of the class,outer: the address of the outer class, can be NULLobjectName: the name of the object to be found, e. g."Engine.World".exact: read official documentation
Returns the address of the object, if not found it will be nil.
local worldClass = ue.StaticFindObject(NULL, NULL, "Engine.World", false)
println("UWorld class:", ptrToStr(worldClass))function StaticLoadObject(
class: number[ptr],
name: string,
filename: string = nil,
outer: number[ptr] = 0,
loadFlags: number[int] = 0,
sandbox: number[ptr] = 0,
allowObjectReconciliation: bool = false,
instancingContext: number[ptr] = 0
) -> number[ptr]|nilLoads a static object in the Unreal Engine environment. This function is used to load objects of a specified class, by name.
class: The class of the object to be loaded.name: The name of the object.filename: Optional filename for the object.outer: Optional outer context for the object.loadFlags: Optional loading flags.sandbox: Optional sandbox for the object.allowObjectReconciliation: Optional flag for object reconciliation.instancingContext: Optional instancing context.
Returns the loaded object as pointer if successful, or nil if the loading fails.
local myObject = ue.StaticLoadObject(myClass, "/Game/Athena/MyObject")
if myObject then
-- Object loaded successfully
else
-- Failed to load the object
endfunction GetNameByIndex(nameIndex: number) -> string|nilRetrieves the name associated with the given index FName.
nameIndex: the index of the name.
Returns the name as a string if found, otherwise nil.
function GetNameByIndexF(index: number[int]) -> table[FStringMT]|nilBasically convets FName to FString.
Ensure you use the Free() method on the returned table after you don't need it anymore. Otherwise memory leaks will take place.
index: 64-bit integer reperesenting the index of the name, sinceFNameis 64-bits in the versions of Unreal Engine that Fortnite uses
Returns the a table associated with the FStringMT metatable or nil if the index is not valid.
This function could cause crashes for some invalid index values passed.
local nameIndex = 1
local nameStr = ue.GetNameByIndexF(nameIndex)
assert(nameStr, "Failed to get name")
println(nameStr:ToStr())function GetObjectName(object: number[ptr]) -> stringGets the name of the UObject in memory.
object: the address of the object.
Returns the name as a string.
function GetObjectNameF(object: number[ptr]) -> table[FStringMT]|nilGets the name of the UObject in memory as FString.
Ensure you use the Free() method on the returned table after you don't need it anymore. Otherwise memory leaks will take place.
object: the address of the object.
Returns the name as a FString table associated with FStringMT or nil if invalid.
function ProcessEvent(
object: number[ptr],
targetFunc: number[ptr],
params: number[ptr] = 0
) -> boolProcesses an event for a particular object and function.
object: the address of the object, should be a validUObject.targetFunc: the address of the function, should be a validUFunction.params: a pointer to the parameters in memory necessary for the event, can be 0 if the target function doesn't take or return any values.
Returns true if the event was processed, otherwise false.
local GameplayStatics = ue.GetObject("Engine.Default__GameplayStatics")
local GS_GetTimeSeconds = ue.GetObject("Engine.GameplayStatics:GetTimeSeconds")
function getTimeSeconds()
-- Setup the parameters for the function
local paramsUd, params = mem.Alloc(8 + 4)
mem.WritePtr(params, ue.GetWorld())
-- Process the function
if not GameplayStatics:ProcessEvent(GS_GetTimeSeconds:ptr(), params) then
return nil
end
-- Read and return the return value from GetTimeSeconds
return mem.ReadFloat(params + 8)
endfunction IsObjectOfClass(
object: number[ptr],
class: number[ptr]
) -> boolChecks if an object is an instance of a given class.
object: the address of the object, validUObject.class: the address of the class, validUClass.
Returns true if the object is of the given class, otherwise false.
function GetObject(objectName: string) -> userdata[UClassMT]|nilRetrieves the object associated with the given name. Simplified version of StaticFindObject.
objectName: the name of the object.
Returns the object as a userdata object UClassMT or nil if not found.
Alias for GetObject
function LoadObject(class: number[ptr], name: string) -> number[ptr]|nilA simplified wrapper for loading objects in the Unreal Engine environment. It loads objects of a specified class by name, without the additional parameters available in StaticLoadObject.
class: Pointer to the class of the object to be loaded.name: The name of the object.
Returns the loaded object's pointer if successful, or nil if the loading fails.
local myObject = ue.LoadObject(myClass, "MyObjectName")
if myObject then
-- Object loaded successfully
else
-- Failed to load the object
endfunction LoadAsset(name: number[int], showDelayTimes: bool = false) -> number[ptr]|nilLoads an Unreal Engine asset by its name (FName). This function returns the asset's pointer (UObject*).
name: TheFNameinteger representation of the asset's name (as anumber[int]).showDelayTimes: A boolean flag to indicate whether to display loading delay times in the console output of the game, default isfalse.
Returns the asset's pointer (UObject*) if the asset is successfully loaded. Returns nil if the asset could not be loaded.
local FNameInt = ...
local assetPtr = ue.LoadAsset(FNameInt)
if assetPtr then
-- Asset loaded successfully
else
println("Failed to load asset")
endfunction GetClassOffset(
className: string,
memberName: string
) -> number[int]|nilGets the offset of a class member.
className: the name of the class.memberName: the name of the class member.
Returns the memory offset as a number, nil if not found.
function GetObjectByIndex(index: number[int]) -> number[ptr]|nilRetrieves the UObject in GObjects at the given index.
index: the index of the object.
Returns the address of the object if there is a valid object at the given index, otherwise nil.
function GetObjectsCount() -> number[int]Gets the count of UObjects in memory (owned by GObjects).
None.
Returns the number of objects.
function WorldToScreen(worldLoc: vec3) -> vec2, boolConverts world coordinates to screen coordinates.
worldLoc: the world coordinates.
Returns the screen coordinates as a vec2 and a boolean indicating if the coordinates are on the screen.
function LineTraceSingle(
lineStart: vec3,
lineEnd: vec3,
traceChannel: number[int] = 0,
fetchResult: bool = false,
actorsToIgnore: table[TArray] = {}
) -> bool, table|nilPerforms a single line trace in the game world.
lineStart: the starting point of the line trace.lineEnd: the ending point of the line trace.traceChannel: the trace channel to use.fetchResult: whether to fetch the hit result.actorsToIgnore: table of actors to ignore during the trace,datafield must be anumber[ptr]pointing to the beginning of the array containing the pointers of the actors to ignore in memory,sizefield must be the number of actors to ignore.
Returns a boolean indicating if something was hit and an optional table containing hit details if fetchResult was true.
function RotationToVector(rotation: vec3) -> vec3Converts a rotation to a directional vector.
rotation: the rotation to convert.
Returns the directional vector.
function StringToFName(str: string) -> number[int]|nilConverts a string to an FName object.
str- The string to convert.
Returns an FName object, nil if not a valid FName.
function FindObjectsOfClass(class: number[ptr]) -> table[list[number[ptr]]]Finds all loaded objects of a given class in the game.
class- A pointer to theUClassrepresenting the Unreal class type to search for.
Returns a table containing all found objects of the given type as a list of number[ptr].
function FreeArray(array: table[TArrayMT]) -> noneFrees the memory occupied by a TArray (table with data, size, and capacity fields associated with TArrayMT) and sets the table's fields to nil.
array- The table representing a TArray to be freed.
None.
function Free(data: number[ptr]) -> noneFrees the memory using Unreal Engine's FMemory::Free function.
data- A pointer pointing to the memory to be freed.
None.
function FTextToFString(text: number[ptr]) -> table[FStringMT]|nilConverts an FText object to FString, represented as a table with data, size, and capacity fields (associated with FStringMT).
Ensure you use the Free() method on the returned table after you don't need it anymore. Otherwise memory leaks will take place.
text- A pointer to the FText object to convert.
Returns a table representing the FString or nil if invalid.
function FTextGet(text: number[ptr]) -> stringRetrieves the string content of an FText object.
text- A pointer to theFTextobject.
Returns the string content of the FText object.
function FStringGet(stringPtr: number[ptr], free: bool = false) -> string|nilRetrieves the string value from an FString object, optionally freeing its memory.
stringPtr: Pointer to theFStringobject.free: If set totrue, theFStringobject is freed after retrieval (default isfalse).
The string value from the FString object or nil if it is not invalid.
local result = ue.FStringGet(fstrPtr)
if result then
println("FString value:", result)
else
println("Invalid FString")
endfunction TransformToMatrixWithScale(transf: number[ptr]) -> table[matrix4x4]Converts an FTransform object to a matrix with scale.
transf- A pointer to the FTransform object.
Returns a 4x4 matrix table.
function GetGameVersionStr() -> stringRetrieves the full game version as a string.
None.
Returns the full game version as a string.
function GetGameVersion() -> number[float]Retrieves the game version as a float value.
None.
Returns the game version as a float.
function GetEngineVersion() -> number[float]Retrieves the Unreal Engine version as a float value.
None.
Returns the engine version as a float.
function GetEngine() -> number[ptr]|nilRetrieves a pointer to the game engine instance (GEngine).
None.
Returns a pointer to the game engine instance, or nil if not available.
function GetWorld() -> number[ptr]|nilRetrieves a pointer to the game world instance (GWorld).
None.
Returns a pointer to the game world instance, or nil if not available.
function GetGameInstance() -> number[ptr]|nilRetrieves a pointer to the game instance (GWorld->GameInstance).
None.
Returns a pointer to the game instance, or nil if not available.
function GetPersistantLevel() -> number[ptr]|nilRetrieves a pointer to the persistent level of the game world.
None.
Returns a pointer to the persistent level, or nil if not available.
function GetActors() -> table[TArrayMT]|nilRetrieves a TArray table containing all actors in the persistent level.
DO NOT free the returned array.
None.
Returns a table with data, size, and capacity fields (associated with TArrayMT), or nil if not available.
function GetActorsByLevel(level: number[ptr]) -> table[TArrayMT]|nilRetrieves a TArray table containing all actors in the specified level (ULevel).
DO NOT free the returned array.
level: Pointer to the level to fetch the actors of (ULevel).
Returns a table with data, size, and capacity fields (associated with TArrayMT), or nil if not available.
function GetLocalPlayer() -> number[ptr]|nilRetrieves a pointer to the local player.
None.
Returns a pointer to the local player, or nil if not available.
function GetPlayerController() -> number[ptr]|nilRetrieves a Lua pointer to the player controller.
None.
Returns a Lua pointer to the player controller, or nil if not available.
function GetPlayerCameraManager() -> number[ptr]|nilRetrieves a pointer to the player camera manager of the local player controller.
None.
Returns a pointer to the player camera manager, or nil if not available.
function GetLocalPawn() -> number[ptr]|nilRetrieves a pointer to the local player's pawn (controlled character).
None.
Returns a pointer to the local player's pawn, or nil if not available. It's available only inside matches when the local player is alive. So you can use it to check if you are in a match right now.
function GetCameraInfo() -> table|nilRetrieves information about the camera as a table.
None.
Returns a table containing fields Location (vec3), Rotation (vec3), and FOV (number[float]). Could be nil if not available.
function GetViewMatrix() -> table[matrix4x4]|nilRetrieves the view matrix for rendering.
None.
Returns the view matrix as a 4x4 matrix table, could be nil if not available.
function GetViewTargetRootPos() -> vec3|nilRetrieves the root position of the current view target.
None.
Returns the root position as a vec3, could be nil if not available..
function GetViewTargetPelvisPos() -> vec3|nilRetrieves the pelvis position of the current view target.
None.
Returns the pelvis position as a vec3, could be nil if not available..
function GetViewTargetHeadPos() -> vec3|nilRetrieves the head position of the current view target.
None.
Returns the head position as a vec3, could be nil if not available..
function GetAllActorsOfClass(actorClass: number[ptr]) -> table[list[number[ptr]]]|nilRetrieves all actors of a specified class in the game world.
actorClass: Pointer to the class of the actors to retrieve.
Returns a table containing all actors of the specified class. Returns nil if the operation fails or if the parameters are invalid.
local actors = ue.GetAllActorsOfClass(MyActorClass)
if actors then
for _, actor in ipairs(actors) do
-- Process each actor
end
else
println("Failed to retrieve actors")
endThe TArrayMT metatable provides functionalities for handling arrays in the Unreal Engine context.
Tables generated by this library, which are linked to TArrayMT, include the following fields:
data: A pointer directing to the memory location where the array elements reside.size: Indicates the length of the array, specifying the number of elements it contains.capacity: Specifies the pre-allocated space for the array, indicating the number of elements it can hold without requiring reallocation.
Shortcut for FreeArray
function TArrayMT:ReadData(elementSize: number[int]) -> table[list[number[int]]]|nilReads all the elements in the array and returns them as a Lua table.
elementSize: Specifies the size (in bytes) of each element in the array.
Returns a table as a list of integers representing each element if the array is valid; returns nil otherwise.
local arrayContent = myArray:ReadData(8)
if arrayContent then
-- Do something with the array content
else
println("The array is not valid.")
endThe FStringMT metatable extends TArrayMT and offers additional functionalities for handling Unreal Engine strings.
function FStringMT:ToStr() -> stringConverts the FString object to a Lua string.
None.
Returns the converted string.
local luaString = myFString:ToStr()function FStringMT:ToStrFree() -> stringConverts the FString object to a Lua string and frees the original FString object just like Free().
None.
Returns the converted string.
local luaString = myFString:ToStrFree()The UObjectMT metatable extends UserdataMT and provides functionalities for handling Unreal Engine objects.
function UObjectMT:As(metatableName: string) -> userdata[metatableName]|nilAttempts to cast the UObject to the specified class.
metatableName: The name of the metatable to which the original UObject userdata should be cast.
Returns the cast object if successful, otherwise returns nil.
local objectAsFunc = myObject:As("UFunctionMT")function UObjectMT:ProcessEvent(
func: number[ptr],
params: number[ptr] = 0
) -> boolAttempts to process an event (UFunction).
func: Pointer to theUFunctionobject in memory.params: Pointer to the parameters in memory, 0 if not specified.
Returns whether the event has been processed.
local processed = myObject:ProcessEvent(funcPtr, paramsPtr)function UObjectMT:IsOfClass(class: number[ptr]) -> boolReturns whether an object is of a class (UClass).
class: Pointer to the class object to check.
Returns true if the object is an instance of that class, otherwise false.
local isPlayer = myActor:IsOfClass(fortPlayerPawnClass)Alias for IsOfClass
function UObjectMT:GetObjectName() -> stringGet the object name as a string.
None.
Returns the object name as a Lua string.
local name = myObject:GetObjectName()
print(name)function UObjectMT:GetObjectNameF() -> table[FStringMT]|nilGet the object name as a FString.
Ensure you use the Free() method on the returned table after you don't need it anymore. Otherwise memory leaks will take place.
None.
Returns a table of FStringMT or nil if invalid.
local name = myObject:GetObjectNameF()
print(name:ToStrFree())The UClassMT metatable extends UObjectMT and offers additional functionalities for handling Unreal Engine class objects.
function UClassMT:GetField(field: string|number[int]) -> userdata[UClassMT]|nilRetrieves a field as a UClassMT object from a UClass object.
field: the name of the field in the class or the index of the field.
Returns the field as a UClassMT userdata object if found, otherwise nil.
local field = myClass:GetField("FieldName")
println(field:GetFieldName():ToStr())function UClassMT:GetFieldIndex(fieldName: string) -> number[int]Retrieves the index of a field within the UClass object.
fieldName: name of the field.
Returns the index as an integer, -1 if not found.
local fieldIndex = myClass:GetFieldIndex("FieldName")function UClassMT:GetOffset(fieldName: string) -> number[int]Retrieves the offset of a field.
fieldName: Name of the field to get.
Returns the memory offset of a field in a class as an integer.
local fieldOffset = myClass:GetOffset("FieldName")function UClassMT:GetBoolOffset(fieldName: string) -> number[int], number[int]|noneRetrieves the offset of a field and it's bit index if the field is a bit.
fieldName: Name of the field to get.
Returns the memory offset of a field in a class as an integer and the index of the bit as the second argument if it field is a bit.
local fieldOffset, fieldBit = myClass:GetBoolOffset("FieldName")function UClassMT:GetFunction(funcName: string) -> userdata[UFunctionMT]|nilRetrieves a function (method) of a UClass object.
funcName: Name of the function in the class.
Returns the function as a UFunctionMT userdata object.
local func = myClass:GetFunction("FuncName")function UClassMT:GetFieldName() -> table[FStringMT]|nilRetrieves the field name of a UClass object as FString.
Ensure you use the Free() method on the returned table after you don't need it anymore. Otherwise memory leaks will take place.
None.
Returns the field name as a FStringMT table or nil if invalid.
local fieldName = myField:GetFieldName()function UClassMT:GetFieldFName() -> FNameRetrieves the field FName of a UClass object.
None.
Returns the field's FName index as a number.
local fieldNameIndex = myField:GetFieldFName()function UClassMT:GetFieldOffset() -> number[int]Retrieves the field memory offset.
None.
Returns the field's memory offset an integer.
local fieldOffset = myField:GetFieldOffset()function UClassMT:GetNextField() -> userdata[UClassMT]|nilRetrieves the next field in the sequence as a UClassMT object.
None.
Returns the next field as a UClassMT userdata object or nil if there is no next.
local nextField = myField:GetNextField()The UFunctionMT metatable extends UClassMT and provides functionalities specifically for Unreal Engine function objects.
function UFunctionMT:GetNumParams() -> number[int]Retrieves the number of parameters that the UFunction object expects.
None.
Returns the number of parameters as an integer, if the function is not a void function, the return value is counted as a parameter.
local numParams = myFunction:GetNumParams()function UFunctionMT:GetPtr() -> number[ptr]Retrieves the memory address of the native function.
None.
Returns the memory address as a pointer.
local ptr = myFunction:GetPtr()