roblox-animations

用途

本技能是一份 Roblox 动画系统参考，用于在 Humanoid 角色或非 Humanoid 模型上播放、停止或混合动画，并处理相关事件与优先级。

核心对象

Animation：资源引用，保存 AnimationId。
Animator：位于 Humanoid 或 AnimationController 内部，负责加载和驱动轨道。
AnimationController：用于非角色骨架，替代 Humanoid。
AnimationTrack：由 LoadAnimation 返回，控制播放。

动画代码应放置的位置

本地玩家角色：LocalScript，放在 StarterCharacterScripts。
NPC / 服务器拥有的模型：Script，放在模型内部或 ServerScriptService。注意：绝不要用 Script 播放玩家角色动画——它们无法正确复制到本地客户端。

加载与播放动画

示例（StarterCharacterScripts 中的 LocalScript）：

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.1s)，权重 1，速度 1
track:Play(0.1, 1, 0.5)          -- fadeTime, weight, speed

track:AdjustSpeed(1.5)           -- 播放中改变速度
track:AdjustWeight(0.5, 0.2)     -- 权重 0.5，0.2s 内淡入

track:Stop()                      -- 默认淡出 (0.1s)
track:Stop(0.5)                   -- 0.5s 内淡出

AnimationTrack 事件

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

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

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

循环与单次播放

track.Looped：循环为 true，单次为 false。
在动画编辑器中设置（循环开关）。
可在运行时覆盖：track.Looped = false 或 true。
循环动画不会自动停止，必须调用 track:Stop()；单次动画在一个周期后自动停止。

强制循环动画只播放一次：

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()     -- 在共享关节上覆盖 idle
attackTrack:Play()  -- 在其拥有的关节上叠加混合

当两个轨道共享相同优先级时，权重调整影响程度：

trackA:Play(0, 0.6)  -- 权重 0.6
trackB:Play(0, 0.4)  -- 权重 0.4 — 在共享关节上混合

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

-- StarterCharacterScripts 中的 LocalScript
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  默认 0.1   — 淡入秒数
-- weight    默认 1.0   — 关节影响 (0–1)
-- speed     默认 1.0   — 播放速率

track.TimePosition   -- 当前位置（秒，可读写）
track.Length         -- 总时长（秒）
track.IsPlaying      -- 布尔值
track.Looped         -- 布尔值（允许运行时覆盖）
track.Priority       -- Enum.AnimationPriority
track.WeightCurrent  -- 当前实际混合权重
track.WeightTarget   -- 淡入后的目标权重

仅上半身动画

优先级混合会影响动画触及的所有关节。要让挥手只作用于手臂而腿部由 run/idle 驱动，动画本身必须只对上半身骨骼打关键帧（在动画编辑器中让下半身关节不打关键帧）。没有运行时 API 可以遮罩关节——解决方案在动画资源中，而非脚本中。

常见错误

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