roblox-animations

---
name: roblox-animations
description: Use when working with Roblox animation systems including playing, stopping, or blending animations on Humanoid characters or non-Humanoid models, handling AnimationTrack events, replacing default character animations, or debugging animation priority and blending issues.
---

# Roblox Animations Reference

## Core Objects

| Object | Purpose |
|---|---|
| `Animation` | Asset reference — holds `AnimationId` |
| `Animator` | Lives inside Humanoid or AnimationController; loads and drives tracks |
| `AnimationController` | Replaces Humanoid for non-character rigs |
| `AnimationTrack` | Returned by `LoadAnimation`; controls playback |

---

## Where to Run Animation Code

| Scenario | Script Type | Location |
|---|---|---|
| Local player character | `LocalScript` | `StarterCharacterScripts` |
| NPC / server-owned model | `Script` | Inside model or `ServerScriptService` |

> Never play player character animations from a `Script` — they will not replicate correctly to the local client.

---

## Loading and Playing Animations

```lua
-- LocalScript in StarterCharacterScripts
local character = script.Parent
local animator = character:WaitForChild("Humanoid"):WaitForChild("Animator")

local animation = Instance.new("Animation")
animation.AnimationId = "rbxassetid://1234567890"

local track = animator:LoadAnimation(animation)

track:Play()                      -- default fade-in (0.1s), weight 1, speed 1
track:Play(0.1, 1, 0.5)          -- fadeTime, weight, speed

track:AdjustSpeed(1.5)           -- change speed while playing
track:AdjustWeight(0.5, 0.2)     -- weight 0.5, fade over 0.2s

track:Stop()                      -- default fade-out (0.1s)
track:Stop(0.5)                   -- fade out over 0.5s
```

---

## AnimationTrack Events

```lua
-- Fires after fade-out completes
track.Stopped:Connect(function()
    print("Animation finished")
end)

-- Use :Once for one-shot cleanup
track.Stopped:Once(function()
    cleanup()
end)

-- Fires when a named keyframe marker is reached
-- Marker names are set in the Roblox Animation Editor
track:GetMarkerReachedSignal("FootStep"):Connect(function(paramString)
    playFootstepSound()
end)
```

---

## Looped vs One-Shot

| Property | Looped | One-Shot |
|---|---|---|
| `track.Looped` | `true` | `false` |
| Set in | Animation Editor (loop toggle) | Animation Editor |
| Override at runtime | `track.Looped = false` | `track.Looped = true` |
| Stops automatically | No — must call `track:Stop()` | Yes — after one cycle |

```lua
-- Force a looped animation to play once
track.Looped = false
track:Play()
track.Stopped:Once(function() print("Done") end)
```

---

## Animation Priority and Blending

Priority controls which tracks win on contested joints. Higher priority overrides lower.

```
Idle < Movement < Action < Action2 < Action3 < Action4 < Core
```

```lua
idleTrack.Priority   = Enum.AnimationPriority.Idle
runTrack.Priority    = Enum.AnimationPriority.Movement
attackTrack.Priority = Enum.AnimationPriority.Action

idleTrack:Play()
runTrack:Play()     -- overrides idle on shared joints
attackTrack:Play()  -- blends on top for joints it owns
```

Weight adjusts influence when two tracks share the same priority:

```lua
trackA:Play(0, 0.6)  -- weight 0.6
trackB:Play(0, 0.4)  -- weight 0.4 — blended on shared joints
```

---

## Humanoid vs AnimationController

### Humanoid (characters and humanoid NPCs)

```lua
local animator = character:FindFirstChildOfClass("Humanoid"):FindFirstChildOfClass("Animator")
local track = animator:LoadAnimation(animation)
track:Play()
```

### AnimationController (props, vehicles, creatures)

```lua
local controller = model:FindFirstChildOfClass("AnimationController")
local animator = controller:FindFirstChildOfClass("Animator")
if not animator then
    animator = Instance.new("Animator")
    animator.Parent = controller
end
local track = animator:LoadAnimation(animation)
track:Play()
```

---

## Replacing Default Character Animations

The `Animate` LocalScript in the character holds animation references. Modify its `AnimationId` values on CharacterAdded.

```lua
-- LocalScript in StarterCharacterScripts
local animate = script.Parent:WaitForChild("Animate")

local function replaceAnim(slotName, newId)
    local slot = animate:FindFirstChild(slotName)
    if slot then
        local animObj = slot:FindFirstChildOfClass("Animation")
        if animObj then animObj.AnimationId = newId end
    end
end

replaceAnim("idle",  "rbxassetid://111111111")
replaceAnim("run",   "rbxassetid://222222222")
replaceAnim("jump",  "rbxassetid://333333333")
replaceAnim("fall",  "rbxassetid://444444444")
replaceAnim("climb", "rbxassetid://555555555")
```

Available slots: `idle`, `walk`, `run`, `jump`, `fall`, `climb`, `swim`, `swimidle`, `toolnone`, `toolslash`, `toollunge`.

---

## Stop All Playing Animations

```lua
local function stopAll(animator, fadeTime)
    for _, track in animator:GetPlayingAnimationTracks() do
        track:Stop(fadeTime or 0.1)
    end
end
```

---

## Quick Playback Reference

```lua
track:Play(fadeTime, weight, speed)
-- fadeTime  default 0.1   — blend-in seconds
-- weight    default 1.0   — joint influence (0–1)
-- speed     default 1.0   — playback rate

track.TimePosition   -- current position in seconds (read/write)
track.Length         -- total duration in seconds
track.IsPlaying      -- bool
track.Looped         -- bool (override allowed at runtime)
track.Priority       -- Enum.AnimationPriority
track.WeightCurrent  -- actual blended weight right now
track.WeightTarget   -- target weight after fade
```

---

## Upper-Body Only Animations

Priority blending affects **all joints** an animation touches. To play a wave only on the arms while legs animate from run/idle, the animation itself must be authored to only key upper-body bones (leave lower-body joints unkeyed in the Animation Editor). There is no runtime API to mask joints — the solution is in the animation asset, not the script.

---

## Common Mistakes

| Mistake | Fix |
|---|---|
| Playing character animations in a `Script` | Use `LocalScript` in `StarterCharacterScripts` |
| `LoadAnimation` called on `Humanoid` (deprecated) | Call on `Animator` instead |
| Two animations fighting on same joints | Assign different `Priority` values |
| `Stopped` fires immediately | Animation has zero length or wrong `Looped` setting |
| `GetMarkerReachedSignal` never fires | Marker name misspelled, or animation not re-uploaded after adding markers |
| NPC animation not visible to other clients | Play from a `Script` (server), not `LocalScript` |
| `AnimationController` track won't play | Missing `Animator` child inside `AnimationController` |