Timeline Module

Timeline 模块为动画提供了一个完整的时间轴控制系统，包括播放、时间计算和状态管理。它实现了一个 分层架构，具有清晰的关注点分离：状态管理、时间计算和更新策略。

概览

核心能力: - 统一的 Timeline 控制接口 – TimelineController 实现了 ITimelineTarget 以保持 API 一致性 - 多种时间更新模式 – 固定 Delta（确定性）和可变 Delta（平滑播放） - 动画状态管理 – 通过状态机进行播放、暂停、恢复、停止 - 时间数学工具 – 时间缩放、偏移和 Delta 计算 - 事件系统 – 用于响应时间/状态变化的观察者模式 - 回退预览模式 – 针对预览场景的检测 - 性能跟踪 – 帧计数和统计

快速开始

基本用法

import { TimelineController } from './timeline';

const timeline = new TimelineController({
  timeScale: 1.0,
  animationSpeed: 1.0,
  timeUpdateMode: 'fixed_delta',
  fixedDeltaTime: 0.016, // ~60 FPS
  maxDeltaTime: 0.05
});

// 播放控制
timeline.start(1.0); // 以 1x 速度开始
timeline.pause();
timeline.resume();
timeline.stop();

// 时间控制
timeline.setTime(5.0);
timeline.setSpeed(2.0); // 2x 速度
timeline.setTimeScale(0.5); // 半速

// 更新循环
function animate() {
  requestAnimationFrame(animate);
  const currentTime = timeline.update(performance.now());
  // 使用 currentTime 进行动画
}

事件监听器

timeline.addEventListener((event) => {
  switch (event.type) {
    case 'play':
      console.log('Animation started');
      break;
    case 'pause':
      console.log('Animation paused');
      break;
    case 'timeChange':
      console.log('Time changed:', event.data.time);
      break;
    case 'speedChange':
      console.log('Speed changed:', event.data.newSpeed);
      break;
  }
});

兼容性方法

TimelineController 还为现有代码提供了兼容性方法：

timeline.startAnimation(1.0);
timeline.pauseAnimation();
timeline.resumeAnimation();
timeline.stopAnimation();
timeline.setAnimationTime(5.0);
timeline.setAnimationSpeed(2.0);

特性

时间更新模式

Fixed Delta (fixed_delta) – 用于一致动画播放的确定性时间步长
Variable Delta (variable_delta) – 用于平滑播放的依赖帧率的时间步长

动画状态

Play – 以可选的速度倍率开始动画
Pause – 暂停动画（保留当前时间）
Resume – 从暂停状态恢复
Stop – 停止动画并重置帧计数

时间控制

Time Scaling – 调整播放速度 (1.0 = 正常, 2.0 = 2倍速, 0.5 = 0.5倍速)
Time Offset – 偏移时间轴原点
Animation Speed – 逐个动画的速度倍率
Direct Time Setting – 跳转到特定时间值

事件

状态变化事件 – play, pause, resume, stop
时间变化事件 – timeChange 当直接设置时间时触发
速度变化事件 – speedChange 当速度被修改时触发

高级特性

回退预览模式 – 针对预览场景的检测（当 frameTime < -0.5 时）
性能统计 – 帧计数、平均帧时间、播放状态
事件系统 – 带有错误处理的观察者模式
状态机 – 带有验证的清晰状态转换

架构

Timeline 模块使用 分层架构，具有清晰的关注点分离：

TimelineController – 编排所有 Timeline 功能的高级外观（façade）
AnimationState – 播放状态（播放中/暂停/停止）和速度的状态机
TimeCalculator – 时间计算引擎（缩放、偏移、Delta 计算）
TimeUpdateMode – Delta 计算的策略模式（固定 vs 可变）
Event System – 用于时间/状态变化通知的观察者模式

组件关系

TimelineController (外观)
├── AnimationState (状态机)
│   └── Event Listeners
├── TimeCalculator (时间数学运算)
│   └── TimeUpdateModeHelper (策略)
└── Event System (观察者)

详见 Architecture Guide 以了解详细的设计决策。

依赖

纯 TypeScript – 无外部依赖
无运行时要求 – 可在任何 JavaScript 环境中工作
解耦设计 – 独立于 Three.js/WebGPU 系统
Performance API – 使用 performance.now() 进行高精度计时

集成

Timeline 模块可与以下模块集成：

AnimationManager – 使用 Timeline 进行动态模型更新
RenderLoop – 可集成以进行基于帧的时间更新
Export Media – 用于视频录制和帧导出
Dynamic Point Clouds – 为 ONNX 驱动的动画提供时间值