Executing, Cancelling, and Restarting Actions

v1.0

Executing Actions

This page deals with executing ActionExecutor objects via code. Check the Action on Events & Action Runner page on using the ready-to-use components with ActionExecutor objects on them.

Execute(this)

Calling Execute(this) is the most common way to execute Actions on an ActionExecutor. If the executor is able to begin or restart execution, it will do so.

The method will return a CancellationTokenSource, which you can cache if you'd like, though this is optional and in most cases not needed.

_cts = myExecutor.Execute(this);

ExecuteAsync()

If you need to wait the execution's completion before doing something else, you can use the ExecuteAsync() method. This pattern allows a class like ActionRunner to cleanly stop and restart actions, check for cancellation between loops, and ensure proper cleanup.

ActionRunner component uses this method to loop the ActionExecutor once it completes.

private CancellationTokenSource _cts;

async void StartActions()
{
    // Create a cancellation token source
    _cts = new CancellationTokenSource();
        
    // Execute with cancellation control
    var result = await myExecutor.ExecuteAsync(this, _cts.Token);
        
    if (result.WasCanceled)
        Debug.Log("Actions were canceled!");
}

Cancelling Actions

Once active, you can cancel an ActionExecutor in a few ways.

Async Cancellation

If you are running an ActionExecutor through ExecuteAsync() you can cancel it:

void StopActions()
    {
        _cts?.Cancel();
        _cts?.Dispose();
        _cts = null;
    }
    
    void OnDestroy()
    {
        _cts?.Cancel();
        _cts?.Dispose();
    }

Dispose of the CancellationTokenSource

If you did cache the CancellationTokenSource when calling Execute(this), you can cancel and dispose of it:

void StopActions()
{
    if (_cts != null)
    {
        _cts.Cancel();
        _cts.Dispose();
        _cts = null;
    }
}

Cancel All Actions

You can also call CancelAllActions() which calls OnCancel() on all tracked Actions. In most cases, this will stop the Actions immediately, though each Action may have different OnCancel() behavior.

myExecutor.CancelAllActions();

Emergency Shutdown

Generally used OnDestroy(), this will immediately shut down lifecycle processes, coroutines, and tracked actions.

This is only intended to be used when destroying an object or exiting playmode. Use the other methods in most cases!

void OnDestroy() => myExecutor.EmergencyShutdown();

StopActionSequenceAction

There's also an Action which stops all actions! Utilize this in an ActionExecutor flow to stop current sequences (on "this" ActionExecutor), all sequences (globally), or sequences on another specific target.

Restarting Actions

If the ActionExecutor allows restarts, and if the cooldown period has elapsed, then you can trigger a restart even if the actions have not yet completed.

Simply call Executor.RestartActions() to do this.

Actions can have special logic that is triggered via RestartActions(), and new instances of currently running actions can carry over cached values. ScaleAction, for example, will cache the baseScale and new instances created via OnRestart() will utilize the original cached value rather than saving the current — and perhaps mid-animation — value as a new base.