用途:在 Decentraland 场景中为对象添加动画。需先判断采用哪种方式:.glb 模型已烘焙的动画用 Animator;两个值之间的简单移动/旋转/缩放用 Tween;需要序列串联用 TweenSequence;需要逐帧控制或自定义数学用 engine.addSystem() 配合 dt。
GLTF 动画(Animator):通过 Animator.create(entity, { states: [...] }) 配置状态,支持骨骼、对象与形态键(morph target)动画。可用 Animator.playSingleAnimation(entity, 'walk') 播放单个动画,Animator.stopAllAnimations(entity) 停止全部,Animator.getClip(entity, 'Walk') 获取片段,并通过给多个状态设置 weight(0.0-1.0)混合动画。注意事项:在代码中自行编写 Animator 时,playSingleAnimation 对未出现在 states 中的片段会静默失败(无控制台警告),需先注册;若使用 GltfContainer 且未挂 Animator,渲染器会自动播放 GLB 中的一个片段;通过 Creator Hub Inspector 放置资源或使用资产包/智能物品时,states 已自动填充。若模型以错误片段生成,可添加 Animator.create 并设置默认片段 playing: true。让模型停留在第一帧(如关闭的门),可保持状态 playing: true 但 speed: 0、loop: false。从每帧调用者调用自定义片段切换辅助函数时,应记录 lastClip 并短路,避免每帧触发 CRDT 序列化开销;playSingleAnimation 非幂等,宜在一次性的转换事件中调用。
检测动画完成:非循环片段结束时引擎会把该状态的 playing 置回 false,用只读的 Animator.get() 轮询并检测 true→false 边沿即可,不要用 getClip() 或 getMutable() 每帧读取。需要支持播放完成检测的 DCL 2.0 桌面客户端,旧客户端该标志不会翻转,必要时保留 timers.setTimeout 兜底。
Tween:用 Tween.create(entity, { mode: Tween.Mode.Move/Rotate/Scale({start, end}), duration, easingFunction }) 创建,duration 单位为毫秒,一个实体同时只能有一个 Tween。辅助方法包括 Tween.setMove/setRotate/setScale/setMoveRotateScale(后者可只提供部分轴向,至少一个;未提供的轴保持不变)。连续 Tween:setMoveContinuous(entity, direction, speed, duration?) 速度为米/秒;setRotateContinuous 速度为度/秒,方向四元数只取旋转轴,负速度反向;setTextureMoveContinuous 速度为 UV 单位/秒。贴图滚动用于瀑布、传送带,setTextureMove 的 movementType 为第 5 个参数。控制:Tween.getMutable(entity).playing = false 暂停,.currentTime = 0 重置,Tween.deleteFrom(entity) 移除。运行时重新触发用 Tween.createOrReplace(TweenSequence 同理),并传 currentTime: 0。从当前位置移动或中途改向,可将 Transform.get(entity).position 作为 start,set* 辅助方法使用 createOrReplace 可平滑重定向。注意:Move 未设置 start 会被当作 (0,0,0),导致先瞬移到场景原点,必须始终提供 start。持续变化的目标(跟随玩家)应使用 setMoveContinuous,而非每帧重建 Move,否则会抖动;它没有终点,需自行按距离调用 Tween.deleteFrom 停止或传入可选的停止时长。
上述代码示例、版本行为与平台限制均来自公开资料,未提供的细节(如完整 API 列表、其他平台支持情况)暂未提供。