AnimationTrack

AnimationTrack : Instance

Overview

This object manages the execution of animations applied to an Animator.

It can only be obtained by calling the Animator's LoadAnimation() method.

Properties

Animation

Animation

This property returns the Animation object set in the AnimationTrack. (Read-only)

Code Samples

print(AnimationTrack.Animation)

BlendByInertialization

boolean

A property that sets whether to use inertia-based blending (Inertialization). When set to true, it provides a more natural transition effect by using inertia during animation transitions.

Code Samples

IsPlaying

boolean

This property returns whether the animation track is running. (Read-only)

Code Samples

AnimationTrack:Play()

if AnimationTrack.IsPlaying then
    print("DoSomething")
end

Length

number

This property returns the total duration of the animation track in seconds. (Read-only)

Code Samples

print(AnimationTrack.Length)

Looped

boolean

This property specifies whether the animation automatically loops after completion.

This property must be set before running the animation to work normally. Changing its value during execution may cause the animation to stop and not return to the default animation after it finishes.

Code Samples

AnimationTrack.Looped = true

Priority

Enum.AnimationPriority

This property specifies which animation takes precedence when multiple animations are running simultaneously.

Enum.AnimationPriority is divided into seven levels, from the highest, Action4, to the lowest, Core. Properly setting the animation priority ensures smooth blending when multiple animations are played simultaneously.

For example, Setting the AnimationTrack's Priority to Movement immediately stops the animation when a movement action occurs. Conversely, setting it to Action allows the animation to continue playing even during moving.

The default is Action.

Code Samples

AnimationTrack.Priority = Enum.AnimationPriority.Movement

AnimationTrack:Play()

Speed

number

This is a read-only property that shows the current playback speed of the AnimationTrack. If you change the playback speed using the AdjustSpeed() method, this property reflects the updated speed.

Code Samples

print(AnimationTrack.Speed)

TimePosition

number

This property indicates how far the AnimationTrack has played through the original animation, in seconds.

Setting this value lets you move to a specific point in the animation. However, the AnimationTrack must be playing to set TimePosition. If you set the playback speed to 0 using AdjustSpeed() and then adjust TimePosition, you can stop the animation at the desired point.

Code Samples

AnimationTrack:Play()
AnimationTrack:AdjustSpeed(0)
AnimationTrack.TimePosition = 1.5

UpperBodyAnimation

boolean

This property determines whether the animation is applied only to the upper body when played. When set to true, the animation will affect only the upper body, allowing lower body movements (such as walking or running) to continue while upper body actions are animated.

Code Samples

Methods

AdjustSpeed

Controls the playback speed of the animation.

The default animation speed is specified when AnimationTrack:Play() is called, but can be modified separately during playback.

Parameters

number InSpeed	The playback speed.

Return

void

Code Samples

local AnimationTrack = Hum:LoadAnimation(Animation)
AnimationTrack:AdjustSpeed(0.3)

AnimationTrack:Play()
wait(1)
-- It can also be modified while the animation is playing.
AnimationTrack:AdjustSpeed(1)

AdjustWeight

Changes the animation weight.

The weight does not change immediately. It gradually changes from the current weight to the target weight over the time specified by fadeTime. When multiple animations with the same priority are playing simultaneously, poses are blended according to the weight of each AnimationTrack.

Parameters

number InWeight	The animation weight to change to. (The default is 1.)
number InFadeTime	The time it takes to transition from the existing weight to the new weight. (The default is 0.1.)

Return

void

Code Samples

AnimationTrack:Play()
AnimationTrack:AdjustWeight(0.5, 0.2)

GetMarkerReachedSignal

Returns an event that fires upon reaching a specific marker at a certain keyframe during animation playback.

Parameters

string InName	The name of the marker.

Return

ScriptSignal	The returned event.

Code Samples

local function OnAnimationEvent()
    print("OnAnimationEvent")
end
AnimationTrack:GetMarkerReachedSignal("SomeKeyName"):connect(OnAnimationEvent)

Play

Runs the animation track.

InFadeTime controls how long it takes for the weight to gradually increase as the animation plays, providing a gradual transition effect.

InSpeed lets you scale the playback speed of your animations, making them run faster or slower than the default speed.

Parameters

number InFadeTime	The time it takes for the animation weight to increase (The default is 0.1).
number InWeight	The weight at which the animation will play. (The default is 1.)
number InSpeed	The playback speed. (The default is 1.)

Return

void

Code Samples

local Players = game:GetService("Players")

local Character = Players.LocalPlayer.Character
local Humanoid = Character:WaitForChild("Humanoid")

local Animation = Instance.new("Animation")
Animation.AnimationId = "ovdrassetid://18850100" -- WinAnimation01

local Animator = Humanoid:FindFirstChild("Animator")
local AnimationTrack = Animator:LoadAnimation(Animation)

AnimationTrack:Play()

Stop

Stops the currently playing animation track.

When called, the animation weight decreases to 0 over the specified time. After the fade-out finishes, the animation's influence completely disappears.

Parameters

number InFadeTime	The time it takes for the animation weight to decrease to 0. (The default is 0.1.)

Return

void

Code Samples

AnimationTrack:Stop()

Events

DidLoop

This event is executed each time a looping animation track completes a loop.

It occurs immediately after the loop ends in the next update and is not called for non-looping animations.

Parameters

Code Samples

AnimationTrack.Looped = true

local function OnLoopAnimation()
    print("The animation looped!")
end
AnimationTrack.DidLoop:Connect(OnLoopAnimation)

AnimationTrack:Play()

Ended

This event is executed when the animation track has finished playing.

It is called when animation playback has finished, the fade-out is complete, and the target has returned to a neutral pose. You can use it to perform follow-up processing after the animation is completely cleaned up or to clean up the AnimationTrack.

Parameters

Code Samples

local function OnEnded()
    print("The animation has ended!")
end
AnimationTrack.Ended:Connect(OnEnded)

KeyframeReached

(Deprecated) This event is executed each time a keyframe with a specified name is reached during animation playback

We recommend using GetMarkerReachedSignal.

Parameters

string KeyframeName	The keyframe name.

Code Samples

local function OnKeyframeReached(keyframeName)
    print(keyframeName)
end
AnimationTrack.KeyframeReached:Connect(OnKeyframeReached)

Stopped

This event is executed when the animation track stops playing.

Even after this event fires, the animation can continue to affect the target while the fade-out is in progress. To check when the animation's influence has completely disappeared, use the Ended event.

Parameters

Code Samples

local function OnStopped()
    print("The animation has been stopped!")
end
AnimationTrack.Stopped:Connect(OnStopped)

See also

Character Animation