AnimatedUnit

AnimatedUnit 是可播放模型内置动画片段的场景单位，适合机关、装饰物等非角色对象；类型本身属于 common，动画播放/停止接口在服务端调用时同步所有客户端，在客户端调用时仅本端生效，状态查询可用于读取当前播放状态。

概览

AnimatedUnit 是可播放模型内置动画片段的场景单位，适合机关、装饰物等非角色对象；类型本身属于 common，动画播放/停止接口在服务端调用时同步所有客户端，在客户端调用时仅本端生效，状态查询可用于读取当前播放状态。

继承自 WorldUnit；可通过 World:CreateUnit("AnimatedUnit", ...) 创建；返回单个单位

函数

PlayAnimation

签名：PlayAnimation(animName: String, params: Map?)

播放 AnimatedUnit 上的模型动画。通过 animName 指定要播放的动画名称，可选通过 params 传入附加的播放参数。在服务端调用时为权威播放，会同步到所有客户端；在客户端调用时仅在本端播放，不会同步到其他端。

参数	类型	说明
animName	String	模型内包含的动画名称或单独上传的动画资源 ID（需与模型骨骼匹配）
params	Map?	播放参数 { startTime, looped, speed }

服务端播放模型自带动画片段

-- @runtime server
-- 【服务端】AnimatedUnit 用于播放模型自身携带的动画片段
local World = game:GetService("World")
local animatedUnit = World:FindFirstChild("MyAnimatedUnit", true)
if animatedUnit == nil or not animatedUnit:IsA("AnimatedUnit") then return end

-- animName 必须是该模型资源内存在的动画片段名
animatedUnit:PlayAnimation("idle", {
    startTime = 0,
    looped = true,
    speed = 1.0,
})

StopAnimation

签名：StopAnimation()

停止 AnimatedUnit 当前正在播放的模型动画，不需要传入参数。在服务端调用时为权威停止，会同步到所有客户端；在客户端调用时仅停止本端播放，不会同步到其他端。

停止 AnimatedUnit 当前动画

-- @runtime server
-- 【服务端】停止模型当前播放的动画
local World = game:GetService("World")
local animatedUnit = World:FindFirstChild("MyAnimatedUnit", true)
if animatedUnit == nil or not animatedUnit:IsA("AnimatedUnit") then return end
animatedUnit:PlayAnimation("idle", { looped = true, speed = 1.0 })
animatedUnit:StopAnimation()

GetAnimationState

签名：GetAnimationState() -> Map

获取当前动画的播放状态信息，返回一个包含动画名称、开始时间、是否循环、播放速度、是否正在播放、播放令牌和服务器时间的映射表。

返回值 Map

读取 AnimatedUnit 动画状态

-- @runtime server
local World = game:GetService("World")
local animatedUnit = World:FindFirstChild("MyAnimatedUnit", true)
if animatedUnit == nil or not animatedUnit:IsA("AnimatedUnit") then return end
local state = animatedUnit:GetAnimationState()
if state ~= nil then
    print("动画状态:", state)
end