@nimbus2d/core 0.0.1

package/src/core/Timeline/Track.js

@@ -0,0 +1,202 @@
+// ============================================================================
+// Nimbus2D - Track 属性轨道
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 绑定目标对象 + 属性路径（支持 'position.x' 多级路径）
+//   2. 管理多个 Clip（按 startTime 排序）
+//   3. evaluate(time) 找到当前时间所在的 Clip 并应用属性值
+//   4. 提供 endTime getter 返回轨道总时长
+//   5. 提供 addClip/removeClip/clearClips 管理 Clip
+//
+// 设计决策：
+//   - 不继承任何类：Track 是绑定 + 管理的中间层
+//   - 属性路径解析：构造时拆分 '.' 一次，避免每帧 split
+//   - addClip 后排序：保证 evaluate 时按时间顺序查找（首命中即应用）
+//   - evaluate 只应用第一个匹配的 Clip（同时间不叠加），避免属性冲突
+//   - 属性设置 try-catch：目标对象被销毁或属性不可写时避免崩溃
+//   - destroy 时清空所有引用：避免内存泄漏
+//   - 销毁幂等：通过 _isDestroyed 标志避免重复销毁
+//
+// 四期新增（任务 1.6/4.3）：Timeline 动画引擎的属性轨道
+// ============================================================================
+
+import { Clip } from './Clip.js'
+import { TimelineError } from './TimelineTypes.js'
+
+class Track {
+  /**
+   * 创建属性轨道
+   * @param {Object} target - 目标对象（必须非 null/undefined）
+   * @param {string} propertyPath - 属性路径（如 'position.x'、'alpha'）
+   * @throws {TimelineError} 参数校验失败
+   */
+  constructor(target, propertyPath) {
+    // 校验 target
+    if (target === null || target === undefined) {
+      throw new TimelineError('Track.target 不可为 null/undefined', 'TRACK_INVALID_TARGET')
+    }
+    // 校验 propertyPath
+    if (typeof propertyPath !== 'string' || propertyPath.length === 0) {
+      throw new TimelineError('Track.propertyPath 必须为非空字符串', 'TRACK_INVALID_PATH')
+    }
+
+    /** @type {Object} 目标对象 */
+    this._target = target
+
+    /** @type {string} 原始属性路径（保留用于调试） */
+    this._propertyPath = propertyPath
+
+    /** @type {string[]} 属性路径分段（如 ['position', 'x']） */
+    this._propertyParts = propertyPath.split('.')
+
+    /** @type {Clip[]} 动画片段列表（按 startTime 升序） */
+    this._clips = []
+
+    /** @type {boolean} 是否已销毁 */
+    this._isDestroyed = false
+  }
+
+  // --------------------------------------------------------------------------
+  // Clip 管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 添加动画片段
+   * @param {Clip} clip - 动画片段
+   * @returns {Track} this（链式）
+   * @throws {TimelineError} clip 不是 Clip 实例
+   */
+  addClip(clip) {
+    if (this._isDestroyed) return this
+    if (!(clip instanceof Clip)) {
+      throw new TimelineError('addClip 参数必须是 Clip 实例', 'TRACK_INVALID_CLIP')
+    }
+    this._clips.push(clip)
+    // 按 startTime 升序排序，保证 evaluate 时首命中即正确片段
+    this._clips.sort((a, b) => a.startTime - b.startTime)
+    return this
+  }
+
+  /**
+   * 移除动画片段
+   * @param {Clip} clip - 动画片段
+   * @returns {boolean} 是否移除成功
+   */
+  removeClip(clip) {
+    if (this._isDestroyed) return false
+    const index = this._clips.indexOf(clip)
+    if (index === -1) return false
+    this._clips.splice(index, 1)
+    return true
+  }
+
+  /**
+   * 清空所有动画片段
+   */
+  clearClips() {
+    if (this._isDestroyed) return
+    this._clips.length = 0
+  }
+
+  /**
+   * 获取片段数量
+   * @returns {number}
+   */
+  get clipCount() {
+    return this._clips.length
+  }
+
+  /**
+   * 获取轨道结束时间（所有 Clip 中最晚的 endTime）
+   * @returns {number}
+   */
+  get endTime() {
+    if (this._clips.length === 0) return 0
+    let max = 0
+    for (const clip of this._clips) {
+      const end = clip.endTime
+      if (end > max) max = end
+    }
+    return max
+  }
+
+  // --------------------------------------------------------------------------
+  // 评估
+  // --------------------------------------------------------------------------
+
+  /**
+   * 评估轨道在指定时间的值并应用到目标属性
+   * @param {number} time - 当前时间（秒）
+   */
+  evaluate(time) {
+    // 已销毁或无片段：不应用
+    if (this._isDestroyed || this._clips.length === 0) return
+    // 校验 time 是否为有效数字（防御 NaN/非数字输入导致不必要的循环遍历）
+    // NaN 时所有 clip 的比较都会返回 false，循环无意义，提前返回提升性能
+    if (typeof time !== 'number' || Number.isNaN(time)) return
+
+    // 查找当前时间所在的 Clip（首个 startTime <= time < endTime 的 Clip）
+    for (const clip of this._clips) {
+      if (time >= clip.startTime && time < clip.endTime) {
+        // 计算本地进度
+        const localTime = time - clip.startTime
+        const progress = localTime / clip.duration
+        // 应用缓动插值
+        const value = clip.evaluate(progress)
+        // 写入目标属性
+        this._setPropertyValue(value)
+        return
+      }
+    }
+
+    // 边界处理：time 超过最后一个 Clip 的 endTime 时，应用最终值
+    // 场景：seek(duration) 或 _complete() 时 time = duration = 最后一个 Clip 的 endTime
+    // 此时半开区间 [startTime, endTime) 不匹配，需要显式应用最终值
+    // 确保动画结束后目标属性保持最终值（而非上一帧的中间值）
+    const lastClip = this._clips[this._clips.length - 1]
+    if (time >= lastClip.endTime) {
+      this._setPropertyValue(lastClip.to)
+    }
+    // 其他情况（time 在 Clip 间隔中）：不修改属性，保持上一帧值
+  }
+
+  /**
+   * 设置目标属性值（带属性路径解析）
+   * @param {*} value - 值
+   * @private
+   */
+  _setPropertyValue(value) {
+    try {
+      let obj = this._target
+      // 遍历到倒数第二级
+      for (let i = 0; i < this._propertyParts.length - 1; i++) {
+        obj = obj[this._propertyParts[i]]
+        // 中间属性为 null/undefined：无法继续访问，直接返回
+        if (obj === null || obj === undefined) return
+      }
+      // 设置最后一级属性
+      const lastKey = this._propertyParts[this._propertyParts.length - 1]
+      obj[lastKey] = value
+    } catch (e) {
+      // 目标对象被销毁或属性不可写：忽略，避免崩溃
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 销毁
+  // --------------------------------------------------------------------------
+
+  /**
+   * 销毁轨道（幂等，可重复调用）
+   * 清空所有 Clip 引用 + 目标对象引用，避免内存泄漏
+   */
+  destroy() {
+    if (this._isDestroyed) return
+    this._isDestroyed = true
+    this._clips.length = 0
+    this._target = null
+    this._propertyParts.length = 0
+  }
+}
+
+export { Track }

package/src/core/Timeline/index.js

@@ -0,0 +1,22 @@
+// ============================================================================
+// Nimbus2D - Timeline 模块统一导出
+// ----------------------------------------------------------------------------
+// 导出 Timeline 动画引擎的公开 API：
+//   - Timeline：时间线主类
+//   - Track：属性轨道
+//   - Clip：动画片段
+//   - Easing：缓动函数库
+//   - BUILTIN_EASINGS：内置缓动函数表（只读）
+//   - TimelineEventType/TimelineState：枚举
+//   - TimelineError：错误类
+//   - TimelineDefaultConfig：默认配置
+//
+// 四期新增（任务 1.6/4.5）：Timeline 模块入口
+// ============================================================================
+
+export { Timeline } from './Timeline.js'
+export { Track } from './Track.js'
+export { Clip } from './Clip.js'
+export { Easing, BUILTIN_EASINGS } from './Easing.js'
+export { TimelineEventType, TimelineState, TimelineError } from './TimelineTypes.js'
+export { TimelineDefaultConfig } from './DefaultConfig.js'

package/src/errors/ConfigError.js

@@ -0,0 +1,47 @@
+// ============================================================================
+// Nimbus2D - 配置系统错误类
+// ----------------------------------------------------------------------------
+// 包含 ConfigError 和 ConfigPathError
+// ============================================================================
+
+import { NimbusError } from './NimbusError.js'
+
+/**
+ * 配置系统错误基类
+ * @extends NimbusError
+ */
+class ConfigError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='CONFIG_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'CONFIG_ERROR', cause = null) {
+    super(message, code, 'ConfigSystem', cause)
+  }
+}
+
+/**
+ * 配置路径错误
+ * 配置路径无效或不存在时抛出
+ * @extends ConfigError
+ */
+class ConfigPathError extends ConfigError {
+  /**
+   * 构造函数
+   * @param {string} path - 无效的配置路径
+   */
+  constructor(path) {
+    super(`配置路径无效：${path}`, 'CONFIG_PATH_ERROR')
+    /** @type {string} 无效的配置路径 */
+    this._path = path
+  }
+
+  /** @type {string} 无效的配置路径 */
+  get path() {
+    return this._path
+  }
+}
+
+export { ConfigError, ConfigPathError }

package/src/errors/LifecycleError.js

@@ -0,0 +1,58 @@
+// ============================================================================
+// Nimbus2D - 生命周期错误类
+// ----------------------------------------------------------------------------
+// 包含 LifecycleError 和 LifecycleStateError
+// ============================================================================
+
+import { NimbusError } from './NimbusError.js'
+
+/**
+ * 生命周期错误基类
+ * @extends NimbusError
+ */
+class LifecycleError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='LIFECYCLE_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'LIFECYCLE_ERROR', cause = null) {
+    super(message, code, 'Lifecycle', cause)
+  }
+}
+
+/**
+ * 生命周期状态错误
+ * Lifecycle 状态转换不合法时抛出
+ * @extends LifecycleError
+ */
+class LifecycleStateError extends LifecycleError {
+  /**
+   * 构造函数
+   * @param {string} currentState - 当前状态
+   * @param {string[]} expectedStates - 期望状态列表
+   */
+  constructor(currentState, expectedStates) {
+    super(
+      `生命周期状态错误：当前 ${currentState}，期望 ${expectedStates.join(' 或 ')}`,
+      'LIFECYCLE_STATE'
+    )
+    /** @type {string} 当前状态 */
+    this._currentState = currentState
+    /** @type {string[]} 期望状态列表 */
+    this._expectedStates = expectedStates
+  }
+
+  /** @type {string} 当前状态 */
+  get currentState() {
+    return this._currentState
+  }
+
+  /** @type {string[]} 期望状态列表 */
+  get expectedStates() {
+    return this._expectedStates
+  }
+}
+
+export { LifecycleError, LifecycleStateError }

package/src/errors/NimbusError.js

@@ -0,0 +1,43 @@
+// ============================================================================
+// Nimbus2D - 错误基类
+// ----------------------------------------------------------------------------
+// 所有 Nimbus2D 错误的基类，附加 code、module、cause 字段
+//
+// 设计决策：
+//   - 不重写 Error.name（文档 §11.5），使用专属 getter 获取模块信息
+//   - 构造函数使用位置参数：constructor(message, code, module, cause)
+//   - code 默认 'NIMBUS_ERROR'，module 默认 'unknown'
+// ============================================================================
+
+/**
+ * Nimbus2D 错误基类
+ * @extends Error
+ */
+class NimbusError extends Error {
+  /**
+   * 构造函数
+   * @param {string} message - 错误信息
+   * @param {string} [code='NIMBUS_ERROR'] - 错误码
+   * @param {string} [module='unknown'] - 所属模块名
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'NIMBUS_ERROR', module = 'unknown', cause = null) {
+    super(message)
+    /** @type {string} 错误码 */
+    this.code = code
+    /** @type {string} 所属模块名 */
+    this.module = module
+    /** @type {Error|null} 原始错误 */
+    this.cause = cause
+  }
+
+  /**
+   * 转换为字符串（含错误码和模块信息）
+   * @returns {string}
+   */
+  toString() {
+    return `[${this.module}:${this.code}] ${this.message}`
+  }
+}
+
+export { NimbusError }

package/src/errors/PluginError.js

@@ -0,0 +1,138 @@
+// ============================================================================
+// Nimbus2D - 插件系统错误类
+// ----------------------------------------------------------------------------
+// 包含 PluginError、PluginNotFoundError、PluginDuplicateError、
+// PluginDependencyError、PluginStateError
+// 注意：使用 pluginName getter（不重写 Error.name）
+// ============================================================================
+
+import { NimbusError } from './NimbusError.js'
+
+/**
+ * 插件系统错误基类
+ * @extends NimbusError
+ */
+class PluginError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='PLUGIN_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'PLUGIN_ERROR', cause = null) {
+    super(message, code, 'PluginSystem', cause)
+  }
+}
+
+/**
+ * 插件未找到错误
+ * @extends PluginError
+ */
+class PluginNotFoundError extends PluginError {
+  /**
+   * 构造函数
+   * @param {string} pluginName - 插件名称
+   */
+  constructor(pluginName) {
+    super(`插件未找到：${pluginName}`, 'PLUGIN_NOT_FOUND')
+    /** @type {string} 插件名称 */
+    this._pluginName = pluginName
+  }
+
+  /** @type {string} 插件名称 */
+  get pluginName() {
+    return this._pluginName
+  }
+}
+
+/**
+ * 插件重复注册错误
+ * @extends PluginError
+ */
+class PluginDuplicateError extends PluginError {
+  /**
+   * 构造函数
+   * @param {string} pluginName - 插件名称
+   */
+  constructor(pluginName) {
+    super(`插件重复注册：${pluginName}`, 'PLUGIN_DUPLICATE')
+    /** @type {string} 插件名称 */
+    this._pluginName = pluginName
+  }
+
+  /** @type {string} 插件名称 */
+  get pluginName() {
+    return this._pluginName
+  }
+}
+
+/**
+ * 插件依赖未满足错误
+ * @extends PluginError
+ */
+class PluginDependencyError extends PluginError {
+  /**
+   * 构造函数
+   * @param {string} pluginName - 插件名称
+   * @param {string} reason - 依赖未满足原因
+   */
+  constructor(pluginName, reason) {
+    super(`插件 ${pluginName} 依赖未满足：${reason}`, 'PLUGIN_DEPENDENCY')
+    /** @type {string} 插件名称 */
+    this._pluginName = pluginName
+    /** @type {string} 依赖未满足原因 */
+    this._reason = reason
+  }
+
+  /** @type {string} 插件名称 */
+  get pluginName() {
+    return this._pluginName
+  }
+
+  /** @type {string} 依赖未满足原因 */
+  get reason() {
+    return this._reason
+  }
+}
+
+/**
+ * 插件状态错误
+ * @extends PluginError
+ */
+class PluginStateError extends PluginError {
+  /**
+   * 构造函数
+   * @param {string} pluginName - 插件名称
+   * @param {string} currentState - 当前状态
+   * @param {string} expectedState - 期望状态
+   */
+  constructor(pluginName, currentState, expectedState) {
+    super(
+      `插件 ${pluginName} 状态错误：当前 ${currentState}，期望 ${expectedState}`,
+      'PLUGIN_STATE'
+    )
+    /** @type {string} 插件名称 */
+    this._pluginName = pluginName
+    /** @type {string} 当前状态 */
+    this._currentState = currentState
+    /** @type {string} 期望状态 */
+    this._expectedState = expectedState
+  }
+
+  /** @type {string} 插件名称 */
+  get pluginName() {
+    return this._pluginName
+  }
+
+  /** @type {string} 当前状态 */
+  get currentState() {
+    return this._currentState
+  }
+
+  /** @type {string} 期望状态 */
+  get expectedState() {
+    return this._expectedState
+  }
+}
+
+export { PluginError, PluginNotFoundError, PluginDuplicateError, PluginDependencyError, PluginStateError }

package/src/errors/ResourceError.js

@@ -0,0 +1,166 @@
+// ============================================================================
+// Nimbus2D - 资源系统错误类
+// ----------------------------------------------------------------------------
+// 包含 ResourceError、ResourceNotFoundError、ResourceDuplicateError、
+// ResourceStateError、ResourceLoadError、AdapterError、ResourceDestroyedError
+// ============================================================================
+
+import { NimbusError } from './NimbusError.js'
+
+/**
+ * 资源系统错误基类
+ * @extends NimbusError
+ */
+class ResourceError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='RESOURCE_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'RESOURCE_ERROR', cause = null) {
+    super(message, code, 'AssetManager', cause)
+  }
+}
+
+/**
+ * 资源未找到错误
+ * @extends ResourceError
+ */
+class ResourceNotFoundError extends ResourceError {
+  /**
+   * 构造函数
+   * @param {string} resourceId - 资源 ID
+   */
+  constructor(resourceId) {
+    super(`资源未找到：${resourceId}`, 'RESOURCE_NOT_FOUND')
+    /** @type {string} 资源 ID */
+    this._resourceId = resourceId
+  }
+
+  /** @type {string} 资源 ID */
+  get resourceId() {
+    return this._resourceId
+  }
+}
+
+/**
+ * 资源重复注册错误
+ * @extends ResourceError
+ */
+class ResourceDuplicateError extends ResourceError {
+  /**
+   * 构造函数
+   * @param {string} resourceId - 资源 ID
+   */
+  constructor(resourceId) {
+    super(`资源重复注册：${resourceId}`, 'RESOURCE_DUPLICATE')
+    /** @type {string} 资源 ID */
+    this._resourceId = resourceId
+  }
+
+  /** @type {string} 资源 ID */
+  get resourceId() {
+    return this._resourceId
+  }
+}
+
+/**
+ * 资源状态错误
+ * @extends ResourceError
+ */
+class ResourceStateError extends ResourceError {
+  /**
+   * 构造函数
+   * @param {string} resourceId - 资源 ID
+   * @param {string} currentState - 当前状态
+   * @param {string} expectedState - 期望状态
+   */
+  constructor(resourceId, currentState, expectedState) {
+    super(
+      `资源 ${resourceId} 状态错误：当前 ${currentState}，期望 ${expectedState}`,
+      'RESOURCE_STATE'
+    )
+    /** @type {string} 资源 ID */
+    this._resourceId = resourceId
+    /** @type {string} 当前状态 */
+    this._currentState = currentState
+    /** @type {string} 期望状态 */
+    this._expectedState = expectedState
+  }
+
+  /** @type {string} 资源 ID */
+  get resourceId() {
+    return this._resourceId
+  }
+
+  /** @type {string} 当前状态 */
+  get currentState() {
+    return this._currentState
+  }
+
+  /** @type {string} 期望状态 */
+  get expectedState() {
+    return this._expectedState
+  }
+}
+
+/**
+ * 资源加载失败错误
+ * @extends ResourceError
+ */
+class ResourceLoadError extends ResourceError {
+  /**
+   * 构造函数
+   * @param {string} resourceId - 资源 ID
+   * @param {Error} cause - 原始错误
+   */
+  constructor(resourceId, cause) {
+    super(`资源加载失败：${resourceId}`, 'RESOURCE_LOAD', cause)
+    /** @type {string} 资源 ID */
+    this._resourceId = resourceId
+  }
+
+  /** @type {string} 资源 ID */
+  get resourceId() {
+    return this._resourceId
+  }
+}
+
+/**
+ * 适配器错误
+ * @extends ResourceError
+ */
+class AdapterError extends ResourceError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, cause = null) {
+    super(message, 'ADAPTER_ERROR', cause)
+  }
+}
+
+/**
+ * 资源系统已销毁错误
+ * @extends ResourceError
+ */
+class ResourceDestroyedError extends ResourceError {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    super('资源系统已销毁', 'RESOURCE_DESTROYED')
+  }
+}
+
+export {
+  ResourceError,
+  ResourceNotFoundError,
+  ResourceDuplicateError,
+  ResourceStateError,
+  ResourceLoadError,
+  AdapterError,
+  ResourceDestroyedError
+}