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 starts 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. Once playback ends, the duplicated ActionSequence instance used for execution is automatically removed, and any events connected to the ActionSequence, as well as child objects configured under it such as Parts, VFX, and scripts, are also cleaned up.

Properties

Methods

ChangeSpeedRate

You can change the playback speed of a currently playing ActionSequence using the ChangeSpeedRate method.

Parameters

string InActionSequenceID	The name of the ActionSequence to play.
number InSpeedRate	Sets the playback speed multiplier for the ActionSequence. Valid values range from 0.1 to 5.

Return

void

Code Samples

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

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.

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.

Track	Behavior
Animation Track	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.
Sound Track	The existing sound (A) fades out based on TransitionTime.
CameraShake Track	The existing track (A) ends immediately, and the new track (B) starts.
Camera FOV Track	The existing track (A) ends immediately, and the new track (B) starts.
Camera Zoom Track	The existing track (A) ends immediately, and the new track (B) starts.
Control Track	The existing track (A) ends immediately, and the new track (B) starts.
Collision Track	The existing track (A) ends immediately, and the new track (B) starts.
Event Track	The existing track (A) ends immediately, and the new track (B) starts.
Trigger Track	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.

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	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.)
number SpeedRate	Sets the playback speed multiplier for the ActionSequence. Valid values range from 0.1 to 5.

Return

void

Code Samples

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)

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

local ActionRunner = Humanoid:GetActionRunner()

ActionRunner:Stop("SomeActionName")

StopAll

Stops all currently running ActionSequences.

Parameters

Return

void

Code Samples

local ActionRunner = Humanoid:GetActionRunner()

ActionRunner:StopAll()

Events

Ended

This event fires when a running ActionSequence completes normally.

Parameters

Code Samples

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

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

ActionSequenceRunning ActionSequences