Animator

Show Deprecated

The main class responsible for the playback and replication of Animations. All replication of playing AnimationTracks is handled through the Animator instance.

It is created when Humanoid:LoadAnimation() or AnimationController:LoadAnimation() is called under a Humanoid or AnimationController for the first time.

For animation replication to function it is important for the Animator to be first created on the server.

Whether to load an Animation on the client or server

In order for AnimationTracks to replicate correctly, it's important to know when they should be loaded on the client (via a LocalScript) or on the server (via a Script).

If an Animator is a descendant of a Humanoid or AnimationController in a Player's Character then animations started on that Player's client will be replicated to the server and other clients.

If the Animator is not a descendant of a player character, its animations must be loaded and started on the server to replicate.

The Animator object must be initially created on the server and replicated to clients for animation replication to work at all. If an Animator is created locally, then AnimationTracks loaded with that Animator will not replicate.

Both Humanoid:LoadAnimation() and AnimationController:LoadAnimation() will create an Animator if one does not already exist. When calling LoadAnimation from LocalScripts you need to be careful to wait for the Animator to replicate from the server before calling LoadAnimation if you want character animations to replicate. You can do this with WaitForChild("Animator").

  • Animation Editor to explore this powerful built-in plugin for creating custom animations
  • Using Animations to learn how to add pre-built and custom animations to your game

Code Samples

Animating a Model Locally

local function playAnimationFromServer(character, animation)
local humanoid = character:FindFirstChildOfClass("Humanoid")
assert(humanoid, "No Humanoid found!")
local animator = humanoid:FindFirstChildOfClass("Animator")
assert(animator, "No Animator found!")
local animationTrack = animator:LoadAnimation(animation)
animationTrack:Play()
return animationTrack
end
playAnimationFromServer(script.Parent.Character, script.Parent.Animation)

Summary

Properties

Methods

Events

Properties

EvaluationThrottled

read only
not replicated
not browsable
write parallel

PreferLodEnabled

read parallel

RootMotion

read only
not replicated
not browsable
write parallel

RootMotionWeight

read only
not replicated
not browsable
write parallel

Methods

ApplyJointVelocities

void

Given the current set of AnimationTracks playing, and their current times and play speeds, compute relative velocities between the parts and apply them to Motor6D.Part1 (the part which Animator considers the "child" part). These relative velocity calculations and assignments happen in the order provided.

This method doesn't apply velocities for a given joint if both of the joint's parts are currently part of the same assembly, for example, if they are still connected directly or indirectly by Motors or Welds.

This method doesn't disable or remove the joints for you. You must disable or otherwise remove the rigid joints from the assembly before calling this method.

The given Motor6Ds are not required to be descendants of the DataModel. Removing the joints from the DataModel before calling this method is supported.

Parameters

motors: Variant

Returns

void

GetPlayingAnimationTracks

Returns the list of currently playing AnimationTracks|AnimationTracks.


Returns

LoadAnimation

LoadAnimation will load the given Animation onto an Animator, returning a playable AnimationTrack. When called on Animators within models that the client has network ownership of, ie. the local player's character or from BasePart:SetNetworkOwner(), this function also loads the animation for the server as well.

You should use this function directly instead of the similarly-named Humanoid:LoadAnimation() and AnimationController:LoadAnimation() functions. These are deprecated proxies of this function which also create an Animator if one does not exist; this can cause replication issues if you are not careful. For more information, see this announcement post

Should I load an Animation on the client or server?

In order for AnimationTracks to replicate correctly, it's important to know when they should be loaded on the client (via a LocalScript) or on the server (via a Script).

If an Animator is a descendant of a Humanoid or AnimationController in a Player's Character then animations started on that Player's client will be replicated to the server and other clients.

If the Animator is not a descendant of a player character, its animations must be loaded and started on the server to replicate.

The Animator object must be initially created on the server and replicated to clients for animation replication to work at all. If an Animator is created locally, then AnimationTracks loaded with that Animator will not replicate.

Both Humanoid:LoadAnimation() and AnimationController:LoadAnimation() will create an Animator if one does not already exist. When calling LoadAnimation from LocalScripts you need to be careful to wait for the Animator to replicate from the server before calling LoadAnimation if you want character animations to replicate. You can do this with WaitForChild("Animator").

Parameters

animation: Animation

The Animation to be used.


Returns

Code Samples

Animating a Model Locally

local function playAnimationFromServer(character, animation)
local humanoid = character:FindFirstChildOfClass("Humanoid")
assert(humanoid, "No Humanoid found!")
local animator = humanoid:FindFirstChildOfClass("Animator")
assert(animator, "No Animator found!")
local animationTrack = animator:LoadAnimation(animation)
animationTrack:Play()
return animationTrack
end
playAnimationFromServer(script.Parent.Character, script.Parent.Animation)

RegisterEvaluationParallelCallback

void

Parameters

callback: function

Returns

void

StepAnimations

void

Increments the AnimationTrack.TimePosition of all playing AnimationTracks that are loaded onto the Animator, applying the offsets to the model associated with the Animator. For use in the command bar or by plugins only.

The deltaTime parameter determines the number of seconds to increment on the animation's progress. Typically this function will be called in a loop to preview the length of an animation (see example).

Note that once animations have stopped playing, the model's joints will need to be manually reset to their original positions (see example).

This function is used to simulate playback of Animations when the game isn't running. This allows animations to be previewed without the consequences of running the game, such as scripts executing. If the function is called while the game is running, or by Scripts or LocalScripts, it will return an error.

Developers designing their own custom animation editors are advised to use this function to preview animations, as it is the method the official Roblox Animation Editor plugin uses.

Parameters

deltaTime: number

The amount of time in seconds animation playback is to be incremented by.


Returns

void

Code Samples

Preview Animation in Studio

local RunService = game:GetService("RunService")
local function studioPreviewAnimation(model, animation)
-- find the AnimationController and Animator
local animationController = model:FindFirstChildOfClass("Humanoid")
or model:FindFirstChildOfClass("AnimationController")
local animator = animationController and animationController:FindFirstChildOfClass("Animator")
if not animationController or not animator then
return
end
-- load the Animation to create an AnimationTrack
local track = animationController:LoadAnimation(animation)
track:Play()
-- preview the animation
local startTime = tick()
while (tick() - startTime) < track.Length do
local step = RunService.Heartbeat:wait()
animator:StepAnimations(step)
end
-- stop the animation
track:Stop(0)
animator:StepAnimations(0)
-- reset the joints
for _, descendant in pairs(model:GetDescendants()) do
if descendant:IsA("Motor6D") then
local joint = descendant
joint.CurrentAngle = 0
joint.Transform = CFrame.new()
end
end
end
local character = script.Parent
local animation = Instance.new("Animation")
animation.AnimationId = "rbxassetid://507765644"
studioPreviewAnimation(character, animation)

Events

AnimationPlayed

Fires for all AnimationTrack:Play() calls on AnimationTracks created and owned by the Animator.

Parameters

animationTrack: AnimationTrack