docs(Lua): document new delayed actions

Author: narknon

assets/Changelog.md

@@ -113,6 +113,35 @@ Added global functions for mod management ([UE4SS #1105](https://github.com/UE4S
 - `RestartMod(ModName)` - Restart another mod by name
 - `UninstallMod(ModName)` - Uninstall another mod by name
 
+Added comprehensive Delayed Action System for game-thread timer management ([UE4SS #XXXX](https://github.com/UE4SS-RE/RE-UE4SS/pull/XXXX))
+- New execution functions:
+  - `ExecuteInGameThreadWithDelay(delayMs, callback)` - Execute after delay, returns handle
+  - `ExecuteInGameThreadWithDelay(handle, delayMs, callback)` - UE Delay-style (only executes if handle not active)
+  - `RetriggerableExecuteInGameThreadWithDelay(handle, delayMs, callback)` - Resets timer if called again (debouncing)
+  - `LoopInGameThreadWithDelay(delayMs, callback)` - Repeating timer with handle
+  - `ExecuteInGameThreadAfterFrames(frames, callback)` - Frame-based delay (requires EngineTick)
+  - `LoopInGameThreadAfterFrames(frames, callback)` - Frame-based repeating timer
+  - `MakeActionHandle()` - Generate unique handle for use with delay functions
+- Timer control functions:
+  - `CancelDelayedAction(handle)` - Cancel a pending action
+  - `PauseDelayedAction(handle)` - Pause a timer
+  - `UnpauseDelayedAction(handle)` - Resume a paused timer
+  - `ResetDelayedActionTimer(handle)` - Restart with original delay
+  - `SetDelayedActionTimer(handle, newDelayMs)` - Change delay and restart
+  - `ClearAllDelayedActions()` - Cancel all actions for current mod
+- Query functions:
+  - `IsValidDelayedActionHandle(handle)` - Check if handle exists
+  - `IsDelayedActionActive(handle)` - Check if timer is running
+  - `IsDelayedActionPaused(handle)` - Check if timer is paused
+  - `GetDelayedActionRate(handle)` - Get configured delay
+  - `GetDelayedActionTimeRemaining(handle)` - Get remaining time
+  - `GetDelayedActionTimeElapsed(handle)` - Get elapsed time
+- New global variables: `EngineTickAvailable`, `ProcessEventAvailable`
+- New enum: `EGameThreadMethod` with `ProcessEvent` and `EngineTick` values
+- `ExecuteInGameThread` now accepts optional second parameter for execution method
+- Per-mod action ownership ensures mods can only control their own timers
+- **Deprecates:** `ExecuteAsync` and `LoopAsync` (still work but lack control features)
+
 **Updated Lua version to 5.4.7** ([UE4SS #887](https://github.com/UE4SS-RE/RE-UE4SS/pull/887))
 - This is necessary to compile with Clang.
 

assets/Mods/shared/Types.lua

@@ -383,11 +383,138 @@ function RegisterHook(UFunctionName, Callback) end
 ---@param PostId integer
 function UnregisterHook(UFunctionName, PreId, PostId) end
 
----Execute code inside the game thread using ProcessEvent.
+---Specifies which hook to use for game thread execution
+---@enum EGameThreadMethod
+EGameThreadMethod = {
+    ---Execute via the ProcessEvent hook. Called frequently (multiple times per frame).
+    ProcessEvent = 0,
+    ---Execute via the EngineTick hook. Called once per frame.
+    EngineTick = 1,
+}
+
+---True if EngineTick hook is available for frame-based delays
+---@type boolean
+EngineTickAvailable = false
+
+---True if ProcessEvent hook is available
+---@type boolean
+ProcessEventAvailable = false
+
+---Execute code inside the game thread.
 ---Will execute as soon as the game has time to execute.
 ---@param Callback fun()
 function ExecuteInGameThread(Callback) end
 
+---Execute code inside the game thread using a specific method.
+---@param Callback fun()
+---@param Method EGameThreadMethod
+function ExecuteInGameThread(Callback, Method) end
+
+---Execute callback after a delay in milliseconds. Returns a handle for control.
+---@param DelayMs integer Delay in milliseconds
+---@param Callback fun() Function to execute
+---@return integer handle Handle to control the action
+function ExecuteInGameThreadWithDelay(DelayMs, Callback) end
+
+---Execute callback after a delay, but only if the handle is not already active (UE Delay-style).
+---If the handle is already active, does nothing and returns the same handle.
+---@param Handle integer Existing handle to check/reuse
+---@param DelayMs integer Delay in milliseconds
+---@param Callback fun() Function to execute
+---@return integer handle The provided handle
+function ExecuteInGameThreadWithDelay(Handle, DelayMs, Callback) end
+
+---Execute callback after delay, resetting the timer if called again with the same handle.
+---Useful for debouncing.
+---@param Handle integer Handle to reset if active
+---@param DelayMs integer Delay in milliseconds
+---@param Callback fun() Function to execute
+---@return integer handle The provided handle
+function RetriggerableExecuteInGameThreadWithDelay(Handle, DelayMs, Callback) end
+
+---Execute callback repeatedly with a delay between each execution.
+---Returns a handle that can be used to cancel the loop.
+---@param DelayMs integer Delay in milliseconds between executions
+---@param Callback fun() Function to execute repeatedly
+---@return integer handle Handle to control the loop
+function LoopInGameThreadWithDelay(DelayMs, Callback) end
+
+---Execute callback after a number of frames (requires EngineTick hook).
+---@param Frames integer Number of frames to wait
+---@param Callback fun() Function to execute
+---@return integer handle Handle to control the action
+function ExecuteInGameThreadAfterFrames(Frames, Callback) end
+
+---Execute callback repeatedly after a number of frames (requires EngineTick hook).
+---@param Frames integer Number of frames between executions
+---@param Callback fun() Function to execute repeatedly
+---@return integer handle Handle to control the loop
+function LoopInGameThreadAfterFrames(Frames, Callback) end
+
+---Generate a unique action handle for use with delay functions.
+---@return integer handle A unique handle
+function MakeActionHandle() end
+
+---Cancel a pending delayed action.
+---@param Handle integer Handle returned from a delay function
+---@return boolean success True if the action was cancelled
+function CancelDelayedAction(Handle) end
+
+---Pause a delayed action, preserving remaining time.
+---@param Handle integer Handle returned from a delay function
+---@return boolean success True if the action was paused
+function PauseDelayedAction(Handle) end
+
+---Resume a paused delayed action.
+---@param Handle integer Handle returned from a delay function
+---@return boolean success True if the action was resumed
+function UnpauseDelayedAction(Handle) end
+
+---Reset a delayed action's timer to its original delay. Also unpauses if paused.
+---@param Handle integer Handle returned from a delay function
+---@return boolean success True if the timer was reset
+function ResetDelayedActionTimer(Handle) end
+
+---Set a new delay for a delayed action and restart the timer. Also unpauses if paused.
+---@param Handle integer Handle returned from a delay function
+---@param NewDelayMs integer New delay in milliseconds
+---@return boolean success True if the timer was updated
+function SetDelayedActionTimer(Handle, NewDelayMs) end
+
+---Cancel all delayed actions belonging to the current mod.
+---@return integer count Number of actions that were cancelled
+function ClearAllDelayedActions() end
+
+---Check if a handle refers to a valid delayed action.
+---@param Handle integer Handle to check
+---@return boolean valid True if the handle exists
+function IsValidDelayedActionHandle(Handle) end
+
+---Check if a delayed action is currently active (not paused, not cancelled).
+---@param Handle integer Handle to check
+---@return boolean active True if the action is active
+function IsDelayedActionActive(Handle) end
+
+---Check if a delayed action is currently paused.
+---@param Handle integer Handle to check
+---@return boolean paused True if the action is paused
+function IsDelayedActionPaused(Handle) end
+
+---Get the configured delay for a delayed action.
+---@param Handle integer Handle to check
+---@return integer delayMs Configured delay in milliseconds (or frames for frame-based), -1 if invalid
+function GetDelayedActionRate(Handle) end
+
+---Get the remaining time until a delayed action fires.
+---@param Handle integer Handle to check
+---@return integer remainingMs Remaining time in milliseconds (or frames for frame-based), -1 if invalid
+function GetDelayedActionTimeRemaining(Handle) end
+
+---Get the elapsed time since a delayed action was started/reset.
+---@param Handle integer Handle to check
+---@return integer elapsedMs Elapsed time in milliseconds (or frames for frame-based), -1 if invalid
+function GetDelayedActionTimeElapsed(Handle) end
+
 ---Returns a ThreadId object representing the id of the current thread.
 ---@return ThreadId
 function GetCurrentThreadId() end

docs/SUMMARY.md

@@ -19,6 +19,7 @@
   - [Table Definitions]()
     - [Key](./lua-api/table-definitions/key.md)
     - [ModifierKey](./lua-api/table-definitions/modifierkey.md)
+    - [EGameThreadMethod](./lua-api/table-definitions/egamethreadmethod.md)
     - [PropertyTypes](./lua-api/table-definitions/propertytypes.md)
     - [OffsetInternalInfo](./lua-api/table-definitions/offsetinternalinfo.md)
     - [ArrayPropertyInfo](./lua-api/table-definitions/arraypropertyinfo.md)
@@ -79,6 +80,7 @@
     - [NotifyOnNewObject](./lua-api/global-functions/notifyonnewobject.md)
     - [ExecuteWithDelay](./lua-api/global-functions/executewithdelay.md)
     - [ExecuteInGameThread](./lua-api/global-functions/executeingamethread.md)
+    - [Delayed Actions](./lua-api/global-functions/delayedactions.md)
     - [ExecuteAsync](./lua-api/global-functions/executeasync.md)
     - [LoopAsync](./lua-api/global-functions/loopasync.md)
     - [LoadAsset](./lua-api/global-functions/loadasset.md)