# ActionRunner

ActionRunner : `Instance`

## Overview

A controller object that manages the playback and stopping of ActionSequences.

It can be obtained by calling `Humanoid:GetActionRunner()`, and allows you to query currently playing ActionSequences or monitor their state through events.

When an action execution request occurs, the sequence execution always s**tarts on the server**, regardless of whether it was called from the Client or Server. **Script events within the ActionSequence are then connected**, and the sequence along with its child objects is **replicated to all clients**.

Once replication is complete, **the timeline is played on each client**, and direction elements such as animations, effects, and sounds are executed.

In other words, ActionSequence does not operate by being dynamically created or directly cloned via scripts at runtime. Instead, **it runs by duplicating predefined data at execution time** to perform the direction.

The server synchronizes the overall progression based on the sequence execution timing, and any **time differences between clients are automatically corrected**. Additionally, to maintain gameplay consistency, **core logic such as attack collision detection is handled on the server**.

ActionSequence runs until the defined playback range is completed. **When the direction ends**, the **duplicated ActionSequence instance used for execution is automatically removed**, and any events connected to the ActionSequence are also cleaned up.

## Properties

## Methods

### StopAll

Stops all currently running ActionSequences.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

ActionRunner:StopAll()
```

### Stop

Stops the ActionSequence with the specified ID.

The value you pass must match the name of the ActionSequence instance.

#### Parameters

| `string` InActionSequenceID | The ID of the ActionSequence to stop. |
| --------------------------- | ------------------------------------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

ActionRunner:Stop("SomeActionName")
```

### GetActionSequences

Retrieves the currently playing ActionSequences set in the ActionRunner.

Depending on the transition state, multiple ActionSequences may exist simultaneously, so the result is returned as an array.

The returned array is ordered from previously played ActionSequences to those that will be played next, and completed entries are automatically removed.

The GetActionSequences method can only be called on the server.

#### Parameters

#### Return

| `Value` | The list of ActionSequences. |
| ------- | ---------------------------- |

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

local Actions = ActionRunner:GetActionSequences() 
```

### Play

Plays the ActionSequence with the specified ID.

The Play method can only be called while the character is alive, and the provided value must match the name of the ActionSequence instance.

When Play is called, the original ActionSequence instance is **cloned into Humanoid.ActionRunner,** and the action is executed based on the cloned instance.

**When the direction ends**, the **duplicated ActionSequence instance used for execution is automatically removed**, and any events connected to the ActionSequence are also cleaned up.

#### Transition Playback

If the **TransitionTime value passed to the Play method is greater than 0**, ActionSequence plays with a smooth transition (blending) from the current action to the new action.\
(If TransitionTime is 0 or omitted, the current action A ends immediately without transition, and action B starts playing right away.)

When transition playback occurs, if action B is executed while action A is already playing, both actions are played **simultaneously for a certain period and gradually transition**. During the TransitionTime, blending occurs from A to B, after which A ends and only B remains.

<figure><img src="https://2064130887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhrvYlLq1mQAq0V0vwPsb%2Fuploads%2For9EUQRMJ8JdLBkJWulG%2FActionSequencer-Transition.png?alt=media&#x26;token=9cdeef9e-d662-4967-935a-79a35d81242e" alt=""><figcaption></figcaption></figure>

TransitionTime represents the **maximum duration** in which a transition can occur. The actual blending time may vary depending on the remaining playback time of A at the moment the transition starts and the total duration of B. In this case, the transition time is clamped to the shorter duration between the remaining time of A and the total duration of B.

This approach helps prevent abrupt transitions between actions and enables more natural direction.

#### Per-Track Transition Behavior

When TransitionTime is greater than 0, transitions are handled differently depending on the track type.

<table><thead><tr><th width="207.3333740234375">Track</th><th>Behavior</th></tr></thead><tbody><tr><td>Animation Track</td><td>Blending between A → B is performed based on TransitionTime. If multiple animations exist at the same time, the last animation is applied based on playback timing and track structure.</td></tr><tr><td>Sound Track</td><td>The existing sound (A) fades out based on TransitionTime.</td></tr><tr><td>CameraShake Track</td><td>The existing track (A) ends immediately, and the new track (B) starts.</td></tr><tr><td>Camera FOV Track</td><td>The existing track (A) ends immediately, and the new track (B) starts.</td></tr><tr><td>Camera Zoom Track</td><td>The existing track (A) ends immediately, and the new track (B) starts.</td></tr><tr><td>Control Track</td><td>The existing track (A) ends immediately, and the new track (B) starts.</td></tr><tr><td>Collision Track</td><td>The existing track (A) ends immediately, and the new track (B) starts.</td></tr><tr><td>Event Track</td><td>The existing track (A) ends immediately, and the new track (B) starts.</td></tr><tr><td>Trigger Track</td><td>The existing track (A) ends immediately, and the new track (B) starts. However, for triggers that have already been entered but not exited, the exit event is called immediately.</td></tr></tbody></table>

#### Notes

* **A maximum of two** ActionSequences can be played simultaneously.
* If a new action is executed while two ActionSequences are already playing, the oldest currently playing action will be terminated.

#### Parameters

| `string` InActionSequenceID | The name of the ActionSequence to play.                                                                                                                                                                                                                                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number` TransitionTime     | <p>If the <strong>TransitionTime value passed to the Play method is greater than 0</strong>, ActionSequence plays with a smooth transition (blending) from the current action to the new action. <br>(If TransitionTime is 0 or omitted, the current action A ends immediately without transition, and action B starts playing right away.)</p> |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

local ActionSequenceKey = "AttackAction"
local TransitionTime = 0.5 -- If greater than 0, it is processed as transition playback.

ActionRunner:Play(ActionSequenceKey, TransitionTime)
```

## Events

### Ended

This event fires when a running ActionSequence completes normally.

#### Parameters

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

-- self : The character model that executed the ActionSequence is passed.
-- key : The Key (name) of the finished ActionSequence is passed.
local function OnEnded(self, key)
    -- ...
end
ActionRunner.Ended:Connect(OnEnded) 
```

### Stopped

This event fires when an ActionSequence is interrupted by the `Stop()` or `StopAll()` method.

Additionally, regardless of whether transitions are used, this is invoked immediately for the currently playing action when a new action starts.

#### Parameters

#### Code Samples

```lua
local ActionRunner = Humanoid:GetActionRunner()

-- self : The character model that executed the ActionSequence is passed.
-- key : The Key (name) of the finished ActionSequence is passed.
local function OnStopped(self, key)
    -- ...
end
ActionRunner.Stopped:Connect(OnStopped) 
```

## See also

{% content-ref url="../../../manual/studio-manual/game-development/actionsequence" %}
[actionsequence](https://docs.overdare.com/manual/studio-manual/game-development/actionsequence)
{% endcontent-ref %}

{% content-ref url="../../../manual/studio-manual/game-development/actionsequence/running-actionsequences" %}
[running-actionsequences](https://docs.overdare.com/manual/studio-manual/game-development/actionsequence/running-actionsequences)
{% endcontent-ref %}