工坊手册

主题

AnimatedUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • SpaceUnit（2 属性 / 9 函数）
      • BasePart（24 属性 / 9 函数）
        • WorldUnit（31 属性 / 16 函数 / 6 事件）
          • [AnimatedUnit]（3 函数）

继承成员 ​

4 个来源 / 61 属性 / 59 函数 / 12 事件

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

适用场景 ​

用于在场景中放置带动画片段的机关门、装饰物或模型道具，由服务端触发播放/停止，并在需要时读取动画状态。

使用要点 ​

先在编辑器或资源流程中准备带模型动画片段的 AnimatedUnit，再由服务端通过 World:FindFirstChild 获取实例并调用 PlayAnimation/StopAnimation；GetAnimationState 用于读取当前动画状态。

注意事项 ​

AnimatedUnit 支持模型资源内部真实存在的动画片段名称，也支持单独上传且与模型骨骼匹配的动画资源 ID。当前官方预设资源列表没有可直接用于作者验证的 AnimatedUnit，普通“带动画外观”的预设也可能仍是 WorldUnit；在编辑器/资源流程提供可用实例前，不应使用虚构的 official://mesh ID 作为可运行示例。角色动画通常应走 EggyUnit/HumanUnit 上的 Animator。PlayAnimation 和 StopAnimation 支持双端调用：服务端调用同步所有客户端，客户端调用仅本端生效。

代码示例 ​

服务端播放模型动画并读取状态 ​

lua
-- @runtime server
local World = game:GetService("World")
local animatedUnit = World:FindFirstChild("MyAnimatedUnit", true)
if animatedUnit == nil or not animatedUnit:IsA("AnimatedUnit") then
    print("请先在编辑器或资源流程中准备带动画片段的 AnimatedUnit")
    return
end

animatedUnit:PlayAnimation("idle", { looped = true, speed = 1.0 })
local state = animatedUnit:GetAnimationState()
if state ~= nil then
    print("动画状态:", state)
end

animatedUnit:StopAnimation()

关联类型 ​

函数 (3) ​

PlayAnimation ​

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

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

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

返回值 void

示例代码

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

lua
-- @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() -> void

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

返回值 void

示例代码

停止 AnimatedUnit 当前动画

lua
-- @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 (动画状态 { animName, startTime, looped, speed, isPlaying, playToken, serverTime })

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

返回值 Map (动画状态 { animName, startTime, looped, speed, isPlaying, playToken, serverTime })

示例代码

读取 AnimatedUnit 动画状态

lua
-- @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