roblox-animations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roblox Animations Reference

Roblox 动画参考

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

对象	用途
`Animation`	资产引用 — 存储 `AnimationId`
`Animator`	存在于Humanoid或AnimationController内部，负责加载和驱动动画轨道
`AnimationController`	用于非角色 rig 时替代Humanoid
`AnimationTrack`	由 `LoadAnimation` 返回，控制动画播放

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.

场景	脚本类型	存放位置
本地玩家角色	`LocalScript`	`StarterCharacterScripts`
NPC / 服务端所属模型	`Script`	模型内部或 `ServerScriptService`

永远不要在
Script
中播放玩家角色动画——它们无法正确同步到本地客户端。

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

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()                      -- 默认淡入（0.1秒），权重1，速度1
track:Play(0.1, 1, 0.5)          -- 淡入时长, 权重, 速度

track:AdjustSpeed(1.5)           -- 播放过程中修改速度
track:AdjustWeight(0.5, 0.2)     -- 权重设为0.5，0.2秒内完成渐变

track:Stop()                      -- 默认淡出（0.1秒）
track:Stop(0.5)                   -- 0.5秒内完成淡出

AnimationTrack Events

AnimationTrack 事件

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)

lua

-- 淡出完成后触发
track.Stopped:Connect(function()
    print("Animation finished")
end)

-- 使用:Once实现一次性清理
track.Stopped:Once(function()
    cleanup()
end)

-- 到达命名关键帧标记时触发
-- 标记名称可在Roblox动画编辑器中设置
track:GetMarkerReachedSignal("FootStep"):Connect(function(paramString)
    playFootstepSound()
end)

Looped vs One-Shot

循环动画 vs 一次性动画

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)

属性	循环动画	一次性动画
`track.Looped`	`true`	`false`
设置位置	动画编辑器（循环开关）	动画编辑器
运行时覆盖	`track.Looped = false`	`track.Looped = true`
自动停止	否 — 必须调用 `track:Stop()`	是 — 播放完一个周期后自动停止

lua

-- 强制循环动画只播放一次
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

优先级控制存在关节冲突时哪条轨道生效，高优先级会覆盖低优先级。

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()     -- 共享关节部分会覆盖待机动画
attackTrack:Play()  -- 对应控制的关节会叠加混合在顶层

两条轨道优先级相同时可通过权重调整影响力：

lua

trackA:Play(0, 0.6)  -- 权重0.6
trackB:Play(0, 0.4)  -- 权重0.4 — 共享关节部分会按权重混合

Humanoid vs AnimationController

Humanoid 与 AnimationController 对比

Humanoid (characters and humanoid NPCs)

Humanoid（角色与人形NPC）

lua

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

lua

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

AnimationController (props, vehicles, creatures)

AnimationController（道具、载具、非人生物）

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

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

角色内的

Animate

LocalScript存储了动画引用，你可以在CharacterAdded事件触发时修改它的

AnimationId

值。

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

可用插槽：

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

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

lua

track:Play(fadeTime, weight, speed)
-- fadeTime  默认值0.1   — 淡入时长（秒）
-- weight    默认值1.0   — 关节影响力（取值范围0–1）
-- speed     默认值1.0   — 播放速率

track.TimePosition   -- 当前播放位置（秒，可读可写）
track.Length         -- 动画总时长（秒）
track.IsPlaying      -- 布尔值，标识是否正在播放
track.Looped         -- 布尔值，支持运行时修改
-- Priority -- 枚举Enum.AnimationPriority
track.WeightCurrent  -- 当前实际生效的混合权重
track.WeightTarget   -- 渐变完成后的目标权重

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.

优先级混合会影响动画涉及的所有关节。如果你想在播放跑步/待机动画（腿部运动）的同时仅在上半身播放挥手动画，必须在制作动画时仅为上半身骨骼设置关键帧（在动画编辑器中不设置下半身关节的关键帧）。目前没有运行时API可以屏蔽关节，该问题需要在动画资源层面解决，而非脚本层面。

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`

错误	解决方案
在 `Script` 中播放角色动画	在 `StarterCharacterScripts` 中使用 `LocalScript`
在 `Humanoid` 上调用 `LoadAnimation` （已废弃）	改为在 `Animator` 上调用
两个动画在相同关节上冲突	分配不同的 `Priority` 值
`Stopped` 事件立即触发	动画时长为0，或 `Looped` 设置错误
`GetMarkerReachedSignal` 永远不触发	标记名称拼写错误，或添加标记后未重新上传动画
其他客户端看不到NPC动画	在 `Script` （服务端）中播放，不要用 `LocalScript`
`AnimationController` 的轨道无法播放	`AnimationController` 内缺少 `Animator` 子对象