Animator

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [Animator]（1 属性 / 2 函数 / 1 事件）

继承成员

1 个来源 / 4 属性 / 25 函数 / 6 事件

• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

动画控制器负责为角色单位加载动画资源、创建 AnimationTrack，并查询当前正在播放的动画轨道。

适用场景

需要为 HumanUnit、EggyUnit 等公开暴露 Animator 属性的角色单位播放骨骼动画时使用。

使用要点

先从角色单位的 Animator 属性取得实例，再调用 animator:LoadAnimation(资源 URI) 获取 AnimationTrack，最后通过轨道的 Play、Stop 等方法控制播放。

注意事项

HumanUnit、EggyUnit 等角色通常已通过 Animator 属性公开可用实例，应优先直接获取，避免重复创建。Meta 允许创建 Animator；确需创建时必须把 Parent 设为拥有骨骼或动画组件的宿主 Unit，否则无法驱动动画。AnimatedUnit 使用自身的 PlayAnimation/StopAnimation 接口，当前公开 Meta 未声明其 Animator 属性。LoadAnimation 的 animationId 参数使用 official://animation/{id} 格式（如 official://animation/100001）。

代码示例

从 HumanUnit 获取 Animator 并播放动画

-- @runtime server
local World = game:GetService("World")

-- 角色通常已公开 Animator 属性，优先复用已有实例
local human = World:CreateUnit("HumanUnit", {
    Position = Vector3.New(0, 0, 0),
    Scale = Vector3.New(1, 1, 1),
})

local animator = human.Animator
if animator == nil then return end
local track = animator:LoadAnimation("official://animation/100001")
track.Priority = Enums.AnimationPriority.Action
track.Looped = true
track:Play()

属性 (1)

Name	类型	默认值	说明
Parent	Unit	-	Parent 属性用于设置或获取该 Animator 所驱动的父 Unit。父级 Unit 通常是拥有骨骼、动画组件或其他可被动画驱动的实体，Animator 通过该属性与目标 Unit 建立层级关联。

关联类型

• Unit

事件 (1)

AnimationPlayed

签名：AnimationPlayed(animationTrack: AnimationTrack) 触发：local

当动画开始播放时触发，携带被播放的 AnimationTrack 实例。

回调参数	类型	说明
animationTrack	AnimationTrack	开始播放的动画轨道

示例代码

监听角色动画开始播放

-- @runtime server
local World = game:GetService("World")
local human = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local animator = human.Animator
if animator == nil then return end

animator.AnimationPlayed:Once(function(animationTrack)
    print("动画开始播放:", animationTrack.Animation.Name)
end)
animator:LoadAnimation("official://animation/100001"):Play()

函数 (2)

LoadAnimation

签名：LoadAnimation(contentId: String|Animation) -> AnimationTrack (动画轨道对象)

加载动画资源并返回一个可播放的 AnimationTrack。如果同一个 contentId 已经加载过，则返回缓存的实例。

参数	类型	说明
contentId	String	Animation

返回值 AnimationTrack (动画轨道对象)

示例代码

加载动画资源并播放

-- @runtime server
local World = game:GetService("World")
local human = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local animator = human.Animator
if animator == nil then return end

-- animationId 必须用 official://animation/{id} 格式
local track = animator:LoadAnimation("official://animation/100001")
track:Play()

GetPlayingAnimationTracks

签名：GetPlayingAnimationTracks() -> AnimationTrack[] (AnimationTrack 数组)

返回当前所有正在播放的 AnimationTrack 数组。

返回值 AnimationTrack[] (AnimationTrack 数组)

示例代码

读取角色当前播放的动画轨道

-- @runtime server
local World = game:GetService("World")
local human = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local animator = human.Animator
if animator == nil then return end

local track = animator:LoadAnimation("official://animation/100001")
track:Play()
for _, playingTrack in ipairs(animator:GetPlayingAnimationTracks()) do
    print("正在播放:", playingTrack.Animation.Name)
end