API Unreal and Runtime

API: Unreal and Runtime

This reference applies to PleasureLib 0.5.0. Examples assume a runtime named pleasureLib; see Getting Started.

Unreal values and objects

runtime:unwrap(value)

Attempts to unwrap UE4SS wrapper objects by calling get() or Get() when available. Primitive values are returned unchanged.

runtime:is_valid(object)

Defensively checks whether a UE object looks usable. It first tries IsValid() and then checks whether GetFullName() can be called. Returns a boolean.

runtime:safe_to_string(value)

Converts a value to a string through pcall. Returns a safe fallback string if the value cannot be printed.

runtime:full_name(object)

Returns GetFullName() for a valid object, then falls back to GetName(), and finally returns an empty string.

Object lookup

runtime:find_object(path)

Calls StaticFindObject defensively and caches valid results per runtime. It tries both common UE4SS call styles:

StaticFindObject(nil, nil, path, false)
StaticFindObject(path)

Returns a valid object or nil.

runtime:find_all_of(class_name)

Calls FindAllOf(class_name) when available. Always returns a table; failures and unavailable UE4SS functions produce an empty table.

for _, page in ipairs(pleasureLib:find_all_of("W_SettingsPage_Game_C")) do
    pleasureLib:debug_log(pleasureLib:full_name(page))
end

Runtime object capture

runtime:capture_new_objects(options, on_complete)

Records a UObject baseline and reports matching objects that appear during a short sampling window. This is useful after opening a menu, spawning an actor, loading a save, or triggering an interaction.

Option	Type	Default	Description
filter(object)	function	Include all	Include only when it returns exactly true.
key(object)	function	full_name	Produces the stable identity used for comparison.
sample_delays_ms	number[]	{50,150,300,500}	Sampling times after the baseline.
finish_delay_ms	number	Last sample + 50	Completion callback time.

The completion callback receives sorted entries shaped as:

{ key = "stable identity", object = object }

Example:

local capture = pleasureLib:capture_new_objects({
    filter = function(object)
        local name = pleasureLib:full_name(object)
        return string.find(name, "BP_Item", 1, true) ~= nil
    end,
}, function(results)
    for _, entry in ipairs(results) do
        pleasureLib:log(entry.key)
    end
end)

Returns a handle with cancel() when capture starts. Returns nil when ForEachUObject or the completion callback is unavailable.

if capture then capture.cancel() end

Timing

runtime:delay(ms, fn)

Schedules fn with ExecuteWithDelay. Returns true when scheduled or false when the callback is invalid or the UE4SS helper is unavailable.

runtime:delay_game_thread(ms, fn)

Schedules a protected callback on the game thread when possible. It prefers ExecuteInGameThreadWithDelay, then uses ExecuteWithDelay together with ExecuteInGameThread, and finally runs a protected delayed callback when the game-thread helper is missing. Returns whether it was scheduled.

Hooks

runtime:register_hook(path, handler[, post_handler])

Calls UE4SS RegisterHook through pcall. Returns true on success. When registration fails or RegisterHook is unavailable, it logs a readable error and returns false.

The optional third argument is forwarded as UE4SS's post-handler. This is required for a true post-hook on native /Script/ functions.

pleasureLib:register_hook(
    "/Script/Engine.PlayerController:ClientRestart",
    function(context)
        pleasureLib:debug_log("pre-hook")
    end,
    function(context)
        pleasureLib:debug_log("post-hook")
    end
)

For native settings registration, see Native Game Settings.