工坊手册

主题

AnimatedUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • SpaceUnit（3 属性 / 9 函数）
      • BasePart（23 属性 / 9 函数）
        • WorldUnit（29 属性 / 15 函数 / 6 事件）
          • [AnimatedUnit]（3 函数）

继承成员 ​

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

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

适用场景 ​

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

使用要点 ​

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

注意事项 ​

AnimatedUnit 只对模型资源内部真实存在的动画片段生效。当前官方预设资源列表没有可直接用于作者验证的 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

播放模型上指定名称的动画，该接口仅服务端可调用。传入的动画名称需与模型资源中定义的动画名一致，可选的 params 参数表可用于进一步指定播放相关配置。

参数类型说明
animNameString动画名称
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

停止当前正在播放的模型动画。

返回值 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