Class ScriptSystemExtensions

Namespace

Stride.CommunityToolkit.Engine

Assembly

Stride.CommunityToolkit.dll

Provides extension methods for the ScriptSystem to facilitate time-based operations, including delays and frame-based executions. These extensions are useful for managing time in game logic, such as delaying actions or executing logic over a period of time.

public static class ScriptSystemExtensions

Inheritance

object

ScriptSystemExtensions

Examples

Example 1: Delaying an action for 2 seconds in game time (affected by time warp):

await scriptSystem.DelayWarped(2.0f);
// Action will be delayed for 2 in-game seconds, accounting for any time warp factors.

Example 2: Running a continuous action for 5 seconds of real time (unaffected by time warp):

await scriptSystem.ExecuteInTime(5.0f, elapsed =>
{
    // Perform action based on the elapsed time in real seconds.
    DebugText.Print($"Time elapsed: {elapsed} seconds");
});

Example 3: Delaying an action for 3 real-time seconds (unaffected by time warp):

await scriptSystem.Delay(3.0f);
// Action will be delayed for exactly 3 real seconds.

Remarks

These extensions allow you to control how game logic interacts with time, whether you need frame-based operations or time delays. The methods are useful for both real-time and in-game time-based operations.

Methods

AddAction(ScriptSystem, Action, TimeSpan, long)

Adds a micro thread function to the scriptSystem that executes after waiting specified delay.

public static MicroThread AddAction(this ScriptSystem scriptSystem, Action action, TimeSpan delay, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

action Action

The micro thread function to execute.

delay TimeSpan

The amount of time to wait for.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem or action is null.

ArgumentOutOfRangeException

If delay is less than zero.

AddAction(ScriptSystem, Action, TimeSpan, TimeSpan, long)

Adds a micro thread function to the scriptSystem that executes after waiting specified delay and repeats execution.

public static MicroThread AddAction(this ScriptSystem scriptSystem, Action action, TimeSpan delay, TimeSpan repeatEvery, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

action Action

The micro thread function to execute.

delay TimeSpan

The amount of time to wait for.

repeatEvery TimeSpan

The amount of time to wait for between repetition.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem or action is null.

ArgumentOutOfRangeException

If delay or repeatEvery is less than zero.

AddOnEventAction<T>(ScriptSystem, EventKey<T>, Action<T>, long)

Adds a micro thread function to the scriptSystem that executes when the event is published.

public static MicroThread AddOnEventAction<T>(this ScriptSystem scriptSystem, EventKey<T> eventKey, Action<T> action, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

eventKey EventKey<T>

The event to wait for.

action Action<T>

The micro thread function to execute.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Type Parameters

T

The type of the event handler parameter.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem, eventKey or action is null.

AddOnEventAction<T>(ScriptSystem, EventReceiver<T>, Action<T>, long)

Adds a micro thread function to the scriptSystem that executes when the event is published.

public static MicroThread AddOnEventAction<T>(this ScriptSystem scriptSystem, EventReceiver<T> receiver, Action<T> action, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

receiver EventReceiver<T>

The event reciever to listen to for.

action Action<T>

The micro thread function to execute.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Type Parameters

T

The type of the event handler parameter.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem, receiver or action is null.

AddOnEventTask<T>(ScriptSystem, EventKey<T>, Func<T, Task>, long)

Adds a micro thread function to the scriptSystem that executes when the event is published.

public static MicroThread AddOnEventTask<T>(this ScriptSystem scriptSystem, EventKey<T> eventKey, Func<T, Task> action, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

eventKey EventKey<T>

The event to wait for.

action Func<T, Task>

The micro thread function to execute.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Type Parameters

T

The type of the event handler parameter.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem, eventKey or action is null.

AddOnEventTask<T>(ScriptSystem, EventReceiver<T>, Func<T, Task>, long)

Adds a micro thread function to the scriptSystem that executes when the event is published.

public static MicroThread AddOnEventTask<T>(this ScriptSystem scriptSystem, EventReceiver<T> receiver, Func<T, Task> action, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

receiver EventReceiver<T>

The event reciever to listen to for.

action Func<T, Task>

The micro thread function to execute.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Type Parameters

T

The type of the event handler parameter.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem, receiver or action is null.

AddOverTimeAction(ScriptSystem, Action<float>, TimeSpan, long)

Adds a micro thread function to the scriptSystem that executes after waiting specified delay and repeats execution.

public static MicroThread AddOverTimeAction(this ScriptSystem scriptSystem, Action<float> action, TimeSpan duration, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

action Action<float>

The micro thread function to execute. The parameter is the progress over time from 0.0f to 1.0f.

duration TimeSpan

The duration of the time to execute the micro thread function for.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem or action is null.

ArgumentOutOfRangeException

If duration is less than zero.

AddTask(ScriptSystem, Func<Task>, TimeSpan, long)

Adds a micro thread function to the scriptSystem that executes after waiting specified delay.

public static MicroThread AddTask(this ScriptSystem scriptSystem, Func<Task> action, TimeSpan delay, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

action Func<Task>

The micro thread function to execute.

delay TimeSpan

The amount of time to wait for.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem or action is null.

ArgumentOutOfRangeException

If delay is less than zero.

AddTask(ScriptSystem, Func<Task>, TimeSpan, TimeSpan, long)

Adds a micro thread function to the scriptSystem that executes after waiting specified delay and repeats execution.

public static MicroThread AddTask(this ScriptSystem scriptSystem, Func<Task> action, TimeSpan delay, TimeSpan repeatEvery, long priority = 0)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

action Func<Task>

The micro thread function to execute.

delay TimeSpan

The amount of time to wait for.

repeatEvery TimeSpan

The amount of time to wait for between repetition.

priority long

The priority of the micro thread action being added.

Returns

MicroThread

The MicroThread.

Remarks

If the action is a ScriptComponent instance method the micro thread will be automatically stopped if the ScriptComponent or Entity is removed.

Exceptions

ArgumentNullException

If scriptSystem or action is null.

ArgumentOutOfRangeException

If delay or repeatEvery is less than zero.

CancelAll(ICollection<MicroThread>)

Cancels all MicroThread and clears the microThreads collection.

public static void CancelAll(this ICollection<MicroThread> microThreads)

Parameters

microThreads ICollection<MicroThread>

A collection of MicroThread to cancel.

Exceptions

ArgumentNullException

If microThreads is null.

Delay(ScriptSystem, float)

Waits for a specified amount of real time (not accounting for any time warp factors).

public static Task Delay(this ScriptSystem script, float seconds)

Parameters

script ScriptSystem

The ScriptSystem instance used to execute the delay.

seconds float

The number of seconds to delay execution.

Returns

Task

A Task representing the delay.

Remarks

This delay operates in real time without considering the game's time warp.

DelayWarped(ScriptSystem, float)

Waits for a specified amount of time, adjusting for any time warp factors.

public static Task DelayWarped(this ScriptSystem script, float seconds)

Parameters

script ScriptSystem

The ScriptSystem instance used to execute the delay.

seconds float

The number of seconds to delay execution.

Returns

Task

A Task representing the delay.

Remarks

This delay takes into account the game's time warp factor, using the WarpElapsed property of UpdateTime.

ExecuteInTime(ScriptSystem, float, Action<float>)

Executes an action every frame for a specified duration, using real time (not accounting for any time warp factors).

public static Task ExecuteInTime(this ScriptSystem script, float seconds, Action<float> action)

Parameters

script ScriptSystem

The ScriptSystem instance used to execute the action.

seconds float

The duration in seconds for which the action will be executed.

action Action<float>

The action to perform on each frame, which receives the elapsed time as a parameter.

Returns

Task

A Task representing the action execution.

Remarks

This method operates in real time, without considering the game's time warp.

ExecuteInWarpedTime(ScriptSystem, float, Action<float>)

Executes an action every frame for a specified duration, adjusting for any time warp factors.

public static Task ExecuteInWarpedTime(this ScriptSystem script, float seconds, Action<float> action)

Parameters

script ScriptSystem

The ScriptSystem instance used to execute the action.

seconds float

The duration in seconds for which the action will be executed.

action Action<float>

The action to perform on each frame, which receives the elapsed time as a parameter.

Returns

Task

A Task representing the action execution.

Remarks

This method accounts for the game's WarpElapsed time factor during execution.

WaitFor(ScriptSystem, TimeSpan)

Waits for the specified delay delay .

public static Task WaitFor(this ScriptSystem scriptSystem, TimeSpan delay)

Parameters

scriptSystem ScriptSystem

The ScriptSystem.

delay TimeSpan

The amount of time to wait.

Returns

Task

The Task to await.