roblox-animations

Roblox 动画参考

核心对象

对象	用途
Animation	资源引用 — 保存 AnimationId
Animator	位于 Humanoid 或 AnimationController 内；加载并驱动动画轨道
AnimationController	在非角色绑定中替代 Humanoid
AnimationTrack	由 LoadAnimation 返回；控制播放

---

在哪里运行动画代码

场景	脚本类型	位置
本地玩家角色	LocalScript	StarterCharacterScripts
NPC／服务器拥有的模型	Script	模型内或 ServerScriptService

切勿通过 Script 播放玩家角色动画 — 它们无法正确复制到本地客户端。

---

加载和播放动画

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

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

---

循环播放与单次播放

属性	循环播放	单次播放
track.Looped	true	false
设置位置	Animation Editor（循环切换）	Animation Editor
在运行时覆盖	track.Looped = false	track.Looped = true
自动停止	否 — 必须调用 track:Stop()	是 — 一个周期后

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

---

动画优先级与混合

优先级决定发生关节冲突时由哪个动画轨道生效。较高优先级会覆盖较低优先级。

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

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

当两个动画轨道具有相同优先级时，可通过权重调整各自的影响程度：

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

---

Humanoid 与 AnimationController

Humanoid（角色和类人 NPC）

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

AnimationController（道具、载具、生物）

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

---

替换默认角色动画

角色中的 Animate LocalScript 保存着动画引用。在 CharacterAdded 时修改其中的 AnimationId 值。

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

---

停止所有正在播放的动画

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

---

播放快速参考

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

---

仅上半身动画

优先级混合会影响动画触及的所有关节。若要让角色仅用手臂播放挥手动画，同时双腿播放跑步／待机动画，该动画本身必须只为上半身骨骼设置关键帧（在 Animation Editor 中让下半身关节不设置关键帧）。没有可在运行时屏蔽关节的 API — 解决方法在动画资源中，而非脚本中。

---

常见错误

错误	修复方法
在 Script 中播放角色动画	在 StarterCharacterScripts 中使用 LocalScript
对 Humanoid 调用 LoadAnimation（已弃用）	改为对 Animator 调用
两个动画在相同关节上互相冲突	设置不同的 Priority 值
Stopped 立即触发	动画长度为零或 Looped 设置错误
GetMarkerReachedSignal 从不触发	标记名称拼写错误，或添加标记后没有重新上传动画
其他客户端看不到 NPC 动画	通过 Script（服务器）而非 LocalScript 播放
AnimationController 动画轨道无法播放	AnimationController 内缺少 Animator 子对象