@nimbus2d/core 0.0.1

package/src/core/Timeline/Timeline.js

@@ -0,0 +1,458 @@
+// ============================================================================
+// Nimbus2D - Timeline 时间线主类
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 管理多条 Track，编排时间线动画
+//   2. 提供播放控制（play/pause/stop/seek）
+//   3. 支持循环（loop/loopCount）、反向播放（autoReverse）、自动销毁（autoDestroy）
+//   4. 通过 EventBus 广播时间线事件（play/pause/stop/seek/loop/complete/destroy）
+//   5. 每帧 update 推进所有 Track 的当前时间
+//
+// 设计决策：
+//   - 不继承任何类：Timeline 是独立的编排器
+//   - EventBus 注入：通过公开方法 setEventBus 注入（不放在构造函数）
+//     避免 Timeline 构造时强制依赖 EventBus，符合依赖注入最佳实践
+//   - 事件发射 try-catch：避免事件总线异常影响主流程
+//   - 销毁幂等：通过 _isDestroyed 标志避免重复销毁导致崩溃
+//   - autoReverse + loop 计数：正向到终点 + 反向到起点 = 1 次完整循环
+//     符合用户直觉（设置 loopCount=2 看到 2 次往返动画）
+//   - autoReverse + 非 loop：正向到终点 → 反向到起点 → 完成
+//   - duration 自动计算：addTrack/removeTrack 后重新计算总时长
+//   - currentTime 范围约束：[0, duration]，避免越界
+//   - 单 Track 异常隔离：try-catch 包裹 track.evaluate，避免影响其他 Track
+//
+// 四期新增（任务 1.6/4.4）：Timeline 动画引擎主类
+// ============================================================================
+
+import { Track } from './Track.js'
+import { TimelineEventType, TimelineState, TimelineError } from './TimelineTypes.js'
+
+class Timeline {
+  /**
+   * 创建 Timeline 实例
+   * @param {Object} [options={}] - 配置
+   * @param {boolean} [options.loop=false] - 是否循环
+   * @param {number} [options.loopCount=Infinity] - 循环次数（Infinity 表示无限）
+   * @param {boolean} [options.autoReverse=false] - 反向播放（到达终点后反向回到起点）
+   * @param {boolean} [options.autoDestroy=false] - 完成后自动销毁
+   */
+  constructor(options = {}) {
+    /** @type {Track[]} 轨道列表 */
+    this._tracks = []
+
+    /** @type {boolean} 是否播放中（含暂停状态） */
+    this._isPlaying = false
+
+    /** @type {boolean} 是否暂停 */
+    this._isPaused = false
+
+    /** @type {number} 当前时间（秒） */
+    this._currentTime = 0
+
+    /** @type {number} 总时长（秒，自动计算） */
+    this._duration = 0
+
+    /** @type {boolean} 是否循环 */
+    this._loop = options.loop ?? false
+
+    /** @type {number} 循环次数上限（必须为正数，否则降级到 Infinity） */
+    this._loopCount = (typeof options.loopCount === 'number' && options.loopCount > 0)
+      ? options.loopCount
+      : Infinity
+
+    /** @type {number} 当前已完成循环次数 */
+    this._currentLoop = 0
+
+    /** @type {boolean} 是否反向播放 */
+    this._autoReverse = options.autoReverse ?? false
+
+    /** @type {boolean} 完成后自动销毁 */
+    this._autoDestroy = options.autoDestroy ?? false
+
+    /** @type {number} 播放方向（1=正向，-1=反向） */
+    this._direction = 1
+
+    /** @type {EventBus|null} 事件总线（通过 setEventBus 注入） */
+    this._eventBus = null
+
+    /** @type {boolean} 是否已销毁 */
+    this._isDestroyed = false
+
+    /** @type {string} 当前状态（TimelineState 枚举值） */
+    this._state = TimelineState.IDLE
+  }
+
+  // --------------------------------------------------------------------------
+  // 轨道管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 添加轨道
+   * @param {Track} track - 属性轨道
+   * @returns {Timeline} this（链式）
+   * @throws {TimelineError} track 不是 Track 实例
+   */
+  addTrack(track) {
+    if (this._isDestroyed) return this
+    if (!(track instanceof Track)) {
+      throw new TimelineError('addTrack 参数必须是 Track 实例', 'TIMELINE_INVALID_TRACK')
+    }
+    this._tracks.push(track)
+    this._recalculateDuration()
+    return this
+  }
+
+  /**
+   * 移除轨道
+   * @param {Track} track - 属性轨道
+   * @returns {boolean} 是否移除成功
+   */
+  removeTrack(track) {
+    if (this._isDestroyed) return false
+    const index = this._tracks.indexOf(track)
+    if (index === -1) return false
+    this._tracks.splice(index, 1)
+    this._recalculateDuration()
+    return true
+  }
+
+  /**
+   * 清空所有轨道（不销毁 Track 实例，由调用方负责）
+   */
+  clearTracks() {
+    if (this._isDestroyed) return
+    this._tracks.length = 0
+    this._recalculateDuration()
+  }
+
+  /**
+   * 获取轨道数量
+   * @returns {number}
+   */
+  get trackCount() {
+    return this._tracks.length
+  }
+
+  // --------------------------------------------------------------------------
+  // 播放控制
+  // --------------------------------------------------------------------------
+
+  /**
+   * 开始播放
+   * 若已暂停则恢复播放；若已完成则从头开始播放
+   * @returns {Timeline} this（链式）
+   */
+  play() {
+    if (this._isDestroyed) return this
+    // 已在播放中（非暂停）：无操作
+    if (this._isPlaying && !this._isPaused) return this
+
+    // 从完成状态恢复：重置循环计数、方向、时间
+    if (this._state === TimelineState.COMPLETED) {
+      this._currentTime = 0
+      this._currentLoop = 0
+      this._direction = 1
+    }
+
+    this._isPlaying = true
+    this._isPaused = false
+    this._state = TimelineState.PLAYING
+    this._emit(TimelineEventType.PLAY, { timeline: this })
+    return this
+  }
+
+  /**
+   * 暂停播放
+   * @returns {Timeline} this（链式）
+   */
+  pause() {
+    if (this._isDestroyed) return this
+    // 未播放或已暂停：无操作
+    if (!this._isPlaying || this._isPaused) return this
+
+    this._isPaused = true
+    this._state = TimelineState.PAUSED
+    this._emit(TimelineEventType.PAUSE, { timeline: this })
+    return this
+  }
+
+  /**
+   * 停止播放并重置时间
+   * @returns {Timeline} this（链式）
+   */
+  stop() {
+    if (this._isDestroyed) return this
+    const wasPlaying = this._isPlaying
+
+    this._isPlaying = false
+    this._isPaused = false
+    this._currentTime = 0
+    this._currentLoop = 0
+    this._direction = 1
+    this._state = TimelineState.IDLE
+
+    // 仅在实际播放中触发 stop 事件
+    if (wasPlaying) {
+      this._emit(TimelineEventType.STOP, { timeline: this })
+    }
+    return this
+  }
+
+  /**
+   * 跳转到指定时间
+   * @param {number} time - 目标时间（秒）
+   * @returns {Timeline} this（链式）
+   */
+  seek(time) {
+    if (this._isDestroyed) return this
+    // 校验 time 是否为有效数字（防御 NaN/Infinity）
+    if (typeof time !== 'number' || Number.isNaN(time)) {
+      return this
+    }
+    // 范围约束 [0, duration]
+    const clampedTime = time < 0 ? 0 : time > this._duration ? this._duration : time
+    this._currentTime = clampedTime
+    this._evaluate()
+    this._emit(TimelineEventType.SEEK, { timeline: this, time: clampedTime })
+    return this
+  }
+
+  // --------------------------------------------------------------------------
+  // 状态查询
+  // --------------------------------------------------------------------------
+
+  /** @type {boolean} 是否播放中（不含暂停） */
+  get isPlaying() { return this._isPlaying && !this._isPaused }
+
+  /** @type {boolean} 是否暂停 */
+  get isPaused() { return this._isPaused }
+
+  /** @type {number} 总时长（秒） */
+  get duration() { return this._duration }
+
+  /** @type {number} 当前时间（秒） */
+  get currentTime() { return this._currentTime }
+
+  /** @type {number} 当前进度 [0,1] */
+  get progress() { return this._duration > 0 ? this._currentTime / this._duration : 0 }
+
+  /** @type {string} 当前状态（TimelineState 枚举值） */
+  get state() { return this._state }
+
+  /** @type {boolean} 是否已销毁 */
+  get isDestroyed() { return this._isDestroyed }
+
+  /** @type {number} 当前已完成循环次数 */
+  get currentLoop() { return this._currentLoop }
+
+  // --------------------------------------------------------------------------
+  // 帧更新
+  // --------------------------------------------------------------------------
+
+  /**
+   * 每帧更新（由外部主循环调用，如 Application.update 或 Scene.update）
+   * @param {number} delta - 帧间隔（秒）
+   */
+  update(delta) {
+    // 已销毁、未播放、已暂停：不推进
+    if (this._isDestroyed || !this._isPlaying || this._isPaused) return
+    // 校验 delta 是否为有效数字（防御 NaN/非数字输入导致 _currentTime 污染）
+    if (typeof delta !== 'number' || Number.isNaN(delta)) return
+
+    // 推进当前时间
+    this._currentTime += delta * this._direction
+
+    // === 边界处理 ===
+    if (this._direction > 0 && this._currentTime >= this._duration) {
+      // 正向到达终点
+      if (!this._handleForwardEnd()) return
+    } else if (this._direction < 0 && this._currentTime <= 0) {
+      // 反向到达起点
+      if (!this._handleBackwardEnd()) return
+    }
+
+    // 评估所有轨道
+    this._evaluate()
+  }
+
+  /**
+   * 处理正向到达终点
+   * @returns {boolean} true=继续播放，false=已结束（不再 evaluate）
+   * @private
+   */
+  _handleForwardEnd() {
+    this._currentTime = this._duration
+
+    // autoReverse 模式：切换为反向继续播放
+    if (this._autoReverse) {
+      this._direction = -1
+      // autoReverse 模式下：正向到终点不算一次完整循环
+      // 反向到起点后才算一次完整循环（在 _handleBackwardEnd 中计数）
+      // 若不循环：反向到起点后完成
+      // 若循环：反向到起点后计数 + 检查 loopCount
+      return true
+    }
+
+    // 非 autoReverse：循环检查
+    if (this._loop) {
+      this._currentLoop++
+      if (this._currentLoop >= this._loopCount) {
+        this._complete()
+        return false
+      }
+      // 重置时间到起点，继续下一轮循环
+      this._currentTime = 0
+      this._emit(TimelineEventType.LOOP, { timeline: this, loopCount: this._currentLoop })
+      return true
+    }
+
+    // 不循环：完成
+    this._complete()
+    return false
+  }
+
+  /**
+   * 处理反向到达起点（仅在 autoReverse 模式下触发）
+   * @returns {boolean} true=继续播放，false=已结束
+   * @private
+   */
+  _handleBackwardEnd() {
+    this._currentTime = 0
+
+    // autoReverse 模式：一次完整循环（正向+反向）完成
+    if (this._autoReverse) {
+      if (this._loop) {
+        // 计数 +1（正向+反向算一次循环）
+        this._currentLoop++
+        if (this._currentLoop >= this._loopCount) {
+          this._complete()
+          return false
+        }
+        // 切换为正向，继续下一轮循环
+        this._direction = 1
+        this._emit(TimelineEventType.LOOP, { timeline: this, loopCount: this._currentLoop })
+        return true
+      }
+      // autoReverse 但不循环：反向到起点后完成
+      this._complete()
+      return false
+    }
+
+    // 非 autoReverse 不会反向到达起点（_direction 应该是 1）
+    // 防御性处理：直接完成
+    this._complete()
+    return false
+  }
+
+  /**
+   * 评估所有轨道（带异常隔离）
+   * @private
+   */
+  _evaluate() {
+    for (const track of this._tracks) {
+      try {
+        track.evaluate(this._currentTime)
+      } catch (e) {
+        // 单个 Track 异常不影响其他 Track
+      }
+    }
+  }
+
+  /**
+   * 完成播放
+   * @private
+   */
+  _complete() {
+    // 设置到终点并应用最后一帧（确保最终状态正确）
+    this._currentTime = this._direction > 0 ? this._duration : 0
+    this._evaluate()
+    this._isPlaying = false
+    this._isPaused = false
+    this._direction = 1
+    this._state = TimelineState.COMPLETED
+    this._emit(TimelineEventType.COMPLETE, { timeline: this })
+    // 自动销毁
+    if (this._autoDestroy) {
+      this.destroy()
+    }
+  }
+
+  /**
+   * 重新计算总时长（所有 Track 中最晚的 endTime）
+   * @private
+   */
+  _recalculateDuration() {
+    let max = 0
+    for (const track of this._tracks) {
+      const end = track.endTime
+      if (end > max) max = end
+    }
+    this._duration = max
+    // 若 currentTime 超出新 duration，约束到新 duration
+    if (this._currentTime > this._duration) {
+      this._currentTime = this._duration
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // EventBus
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注入 EventBus（公开方法，由 Scene 或用户调用）
+   * @param {EventBus|null} eventBus - 事件总线，传 null 可断开
+   * @returns {Timeline} this（链式）
+   */
+  setEventBus(eventBus) {
+    if (this._isDestroyed) return this
+    this._eventBus = eventBus
+    return this
+  }
+
+  /**
+   * 发射事件（带异常捕获）
+   * @param {string} type - 事件类型
+   * @param {Object} data - 事件数据
+   * @private
+   */
+  _emit(type, data) {
+    if (!this._eventBus) return
+    try {
+      this._eventBus.emit(type, data)
+    } catch (e) {
+      // 事件总线异常忽略，避免影响主流程
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 销毁
+  // --------------------------------------------------------------------------
+
+  /**
+   * 销毁时间线（幂等，可重复调用）
+   * 停止播放 + 销毁所有 Track + 清空引用 + 发射 destroy 事件
+   */
+  destroy() {
+    if (this._isDestroyed) return
+    this._isDestroyed = true
+    this._isPlaying = false
+    this._isPaused = false
+    this._state = TimelineState.DESTROYED
+
+    // 销毁所有 Track（带异常隔离）
+    for (const track of this._tracks) {
+      try {
+        track.destroy()
+      } catch (e) {
+        // 单个 Track 销毁异常忽略
+      }
+    }
+    this._tracks.length = 0
+
+    // 发射销毁事件（在 eventBus 被置 null 之前）
+    this._emit(TimelineEventType.DESTROY, { timeline: this })
+    this._eventBus = null
+  }
+}
+
+export { Timeline }

package/src/core/Timeline/TimelineTypes.js

@@ -0,0 +1,89 @@
+// ============================================================================
+// Nimbus2D - Timeline 类型定义
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 定义 Timeline 相关的事件类型枚举（TimelineEventType）
+//   2. 定义 Timeline 状态枚举（TimelineState）
+//   3. 定义 Timeline 错误类（TimelineError）
+//
+// 设计决策：
+//   - 事件类型使用 Object.freeze 冻结，防止运行时被篡改
+//   - 状态枚举使用 Object.freeze 冻结
+//   - 错误类继承 NimbusError，附加 module='Timeline' 字段
+//   - 与 Camera/SceneManager 的类型定义风格保持一致
+//
+// 四期新增（任务 1.6）：Timeline 动画引擎的类型定义
+// ============================================================================
+
+import { NimbusError } from '../../errors/NimbusError.js'
+
+// ----------------------------------------------------------------------------
+// 事件类型枚举
+// ----------------------------------------------------------------------------
+
+/**
+ * Timeline 事件类型
+ * @enum {string}
+ * @readonly
+ */
+const TimelineEventType = Object.freeze({
+  /** 播放开始（play 调用） */
+  PLAY: 'timeline:play',
+  /** 暂停（pause 调用） */
+  PAUSE: 'timeline:pause',
+  /** 停止（stop 调用，currentTime 重置为 0） */
+  STOP: 'timeline:stop',
+  /** 跳转（seek 调用） */
+  SEEK: 'timeline:seek',
+  /** 循环（每次循环开始） */
+  LOOP: 'timeline:loop',
+  /** 完成（非循环模式到达终点，或循环次数到达） */
+  COMPLETE: 'timeline:complete',
+  /** 销毁（destroy 调用） */
+  DESTROY: 'timeline:destroy'
+})
+
+// ----------------------------------------------------------------------------
+// 状态枚举
+// ----------------------------------------------------------------------------
+
+/**
+ * Timeline 状态
+ * @enum {string}
+ * @readonly
+ */
+const TimelineState = Object.freeze({
+  /** 已创建（未播放） */
+  IDLE: 'idle',
+  /** 播放中 */
+  PLAYING: 'playing',
+  /** 暂停中 */
+  PAUSED: 'paused',
+  /** 已完成 */
+  COMPLETED: 'completed',
+  /** 已销毁 */
+  DESTROYED: 'destroyed'
+})
+
+// ----------------------------------------------------------------------------
+// 错误类
+// ----------------------------------------------------------------------------
+
+/**
+ * Timeline 错误基类
+ * 所有 Timeline 错误构造函数设置 module='Timeline'
+ * @extends NimbusError
+ */
+class TimelineError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='TIMELINE_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'TIMELINE_ERROR', cause = null) {
+    super(message, code, 'Timeline', cause)
+  }
+}
+
+export { TimelineEventType, TimelineState, TimelineError }