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 aLocalScript) 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

1local function playAnimationFromServer(character, animation)
2 local humanoid = character:FindFirstChildOfClass("Humanoid")
3 if humanoid then
4 -- need to use animation object for server access
5 local animator = humanoid:FindFirstChildOfClass("Animator")
6 if animator then
7 local animationTrack = animator:LoadAnimation(animation)
8 animationTrack:Play()
9 return animationTrack
10 end
11 end
12end
13
14local animation = Instance.new("Animation")
15animation.AnimationId = "rbxassetid://507765644"
16
17local character = script.Parent
18
19playAnimationFromServer(character, animation)

Summary

Properties

Events


Fires when the Animator starts playing an AnimationTrack.

Methods

ApplyJointVelocities(motors: Variant): void  

Computes relative velocities between parts and apply them to Motor6D.Part1. These relative velocity calculations and assignments happen in the order provided.


Returns the list of currently playing AnimationTracks|AnimationTracks.


Loads an Animation onto an Animator, returning an AnimationTrack. Used to load animations on locally controlled models (such as player characters) from the server.

StepAnimations(deltaTime: number): 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.

Properties

PreferLodEnabled

Events

AnimationPlayed

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

Parameters

animationTrack: AnimationTrack

AnimationPlayedCoreScript

Roblox Script Security

Parameters

animationTrack: AnimationTrack

AnimationStreamTrackPlayed

Roblox Script Security

Parameters

animationTrack: AnimationStreamTrack

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 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

GetPlayingAnimationTracksCoreScript

Roblox Script Security

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 aLocalScript) 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.


Code Samples

Animating a Model Locally

1local function playAnimationFromServer(character, animation)
2 local humanoid = character:FindFirstChildOfClass("Humanoid")
3 if humanoid then
4 -- need to use animation object for server access
5 local animator = humanoid:FindFirstChildOfClass("Animator")
6 if animator then
7 local animationTrack = animator:LoadAnimation(animation)
8 animationTrack:Play()
9 return animationTrack
10 end
11 end
12end
13
14local animation = Instance.new("Animation")
15animation.AnimationId = "rbxassetid://507765644"
16
17local character = script.Parent
18
19playAnimationFromServer(character, animation)

LoadAnimationCoreScript

Roblox Script Security

Parameters

animation: Animation

LoadStreamAnimation

Roblox Script Security

Parameters


StepAnimations

void
Plugin Security

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 paramater 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

1local RunService = game:GetService("RunService")
2
3local function studioPreviewAnimation(model, animation)
4 -- find the AnimationController and Animator
5 local animationController = model:FindFirstChildOfClass("Humanoid")
6 or model:FindFirstChildOfClass("AnimationController")
7 local animator = animationController and animationController:FindFirstChildOfClass("Animator")
8 if not animationController or not animator then
9 return
10 end
11
12 -- load the Animation to create an AnimationTrack
13 local track = animationController:LoadAnimation(animation)
14 track:Play()
15
16 -- preview the animation
17 local startTime = tick()
18 while (tick() - startTime) < track.Length do
19 local step = RunService.Heartbeat:wait()
20 animator:StepAnimations(step)
21 end
22
23 -- stop the animation
24 track:Stop(0)
25 animator:StepAnimations(0)
26
27 -- reset the joints
28 for _, descendant in pairs(model:GetDescendants()) do
29 if descendant:IsA("Motor6D") then
30 local joint = descendant
31 joint.CurrentAngle = 0
32 joint.Transform = CFrame.new()
33 end
34 end
35end
36
37local character = script.Parent
38
39local animation = Instance.new("Animation")
40animation.AnimationId = "rbxassetid://507765644"
41
42studioPreviewAnimation(character, animation)