@nimbus2d/core 0.0.1

package/src/core/SpriteGPULayer/SpriteGPULayerTypes.js

@@ -0,0 +1,49 @@
+// ============================================================================
+// Nimbus2D - SpriteGPULayer 类型定义
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 定义 SpriteGPULayer 相关的事件类型枚举
+//   2. 定义 SpriteGPULayer 错误类
+//
+// 四期新增（任务 1.1）：GPU 批量精灵容器的类型定义
+// ============================================================================
+
+import { NimbusError } from '../../errors/NimbusError.js'
+
+// ----------------------------------------------------------------------------
+// 事件类型枚举
+// ----------------------------------------------------------------------------
+
+/**
+ * SpriteGPULayer 事件类型
+ * @enum {string}
+ */
+const SpriteGPULayerEventType = {
+  /** 纹理组 Sprite 数量达到 maxBatchSize 上限时发射 */
+  BATCH_FULL: 'gpu:spriteBatch:full',
+  /** SpriteGPULayer 渲染完成后发射 */
+  RENDERED: 'gpu:spriteBatch:rendered'
+}
+
+// ----------------------------------------------------------------------------
+// 错误类
+// ----------------------------------------------------------------------------
+
+/**
+ * SpriteGPULayer 错误基类
+ * 所有 SpriteGPULayer 错误构造函数设置 module='SpriteGPULayer'
+ * @extends NimbusError
+ */
+class SpriteGPULayerError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='SPRITE_GPU_LAYER_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'SPRITE_GPU_LAYER_ERROR', cause = null) {
+    super(message, code, 'SpriteGPULayer', cause)
+  }
+}
+
+export { SpriteGPULayerEventType, SpriteGPULayerError }

package/src/core/SpriteGPULayer/index.js

@@ -0,0 +1,11 @@
+// ============================================================================
+// Nimbus2D - SpriteGPULayer 模块入口
+// ----------------------------------------------------------------------------
+// 导出 GPU 批量精灵容器的所有公开 API
+// ============================================================================
+
+// GPU 批量精灵容器主类
+export { SpriteGPULayer } from './SpriteGPULayer.js'
+
+// 类型定义（事件枚举 + 错误类）
+export { SpriteGPULayerEventType, SpriteGPULayerError } from './SpriteGPULayerTypes.js'

package/src/core/Timeline/Clip.js

@@ -0,0 +1,101 @@
+// ============================================================================
+// Nimbus2D - Clip 动画片段
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 封装单个属性动画片段（startTime/duration/from/to/easing）
+//   2. 提供 evaluate(progress) 方法计算指定进度处的值
+//   3. 仅支持数值类型插值（from/to 必须为 number）
+//   4. 提供 endTime getter 返回片段结束时间
+//
+// 设计决策：
+//   - 不继承任何类：Clip 是纯数据 + 行为的简单对象
+//   - 公开属性（startTime/duration/from/to/easing）：便于 Track 直接访问
+//   - evaluate 方法内部使用 Easing.get 获取缓动后的进度
+//   - 输入校验：duration 必须 > 0，from/to 必须为 number
+//   - 防御性编程：progress 范围约束 [0,1]，避免越界值
+//   - 构造函数参数校验：抛出 TimelineError，便于调用方定位问题
+//
+// 四期新增（任务 1.6/4.2）：Timeline 动画引擎的动画片段
+// ============================================================================
+
+import { Easing } from './Easing.js'
+import { TimelineError } from './TimelineTypes.js'
+
+class Clip {
+  /**
+   * 创建动画片段
+   * @param {Object} options - 片段配置
+   * @param {number} options.startTime - 起始时间（秒，>=0）
+   * @param {number} options.duration - 持续时间（秒，>0）
+   * @param {number} options.from - 起始值（必须为 number）
+   * @param {number} options.to - 结束值（必须为 number）
+   * @param {string} [options.easing='linear'] - 缓动函数名（参考 Easing.list()）
+   * @throws {TimelineError} 参数校验失败
+   */
+  constructor(options) {
+    // 参数对象校验
+    if (!options || typeof options !== 'object') {
+      throw new TimelineError('Clip 配置必须为对象', 'CLIP_INVALID_OPTIONS')
+    }
+
+    // 校验 startTime（必须为非负数）
+    if (typeof options.startTime !== 'number' || options.startTime < 0 || Number.isNaN(options.startTime)) {
+      throw new TimelineError('Clip.startTime 必须 >= 0', 'CLIP_INVALID_START_TIME')
+    }
+
+    // 校验 duration（必须为正数）
+    if (typeof options.duration !== 'number' || options.duration <= 0 || Number.isNaN(options.duration)) {
+      throw new TimelineError('Clip.duration 必须 > 0', 'CLIP_INVALID_DURATION')
+    }
+
+    // 校验 from/to（必须为 number，允许 NaN 检查）
+    if (typeof options.from !== 'number' || Number.isNaN(options.from) ||
+        typeof options.to !== 'number' || Number.isNaN(options.to)) {
+      throw new TimelineError('Clip.from/to 必须为有效 number', 'CLIP_INVALID_FROM_TO')
+    }
+
+    /** @type {number} 起始时间（秒） */
+    this.startTime = options.startTime
+
+    /** @type {number} 持续时间（秒） */
+    this.duration = options.duration
+
+    /** @type {number} 起始值 */
+    this.from = options.from
+
+    /** @type {number} 结束值 */
+    this.to = options.to
+
+    /** @type {string} 缓动函数名（未知名称会在 evaluate 时回退到 linear） */
+    this.easing = typeof options.easing === 'string' ? options.easing : 'linear'
+  }
+
+  /**
+   * 获取片段结束时间（startTime + duration）
+   * @returns {number}
+   */
+  get endTime() {
+    return this.startTime + this.duration
+  }
+
+  /**
+   * 评估片段在指定进度处的值
+   * @param {number} progress - 进度 [0,1]（越界值会被自动约束）
+   * @returns {number} 插值结果（from + (to - from) * easing(progress)）
+   */
+  evaluate(progress) {
+    // 校验 progress 是否为有效数字（防御 NaN/非数字输入导致插值结果为 NaN）
+    // NaN 时回退到 0（等同于片段起始值 from）
+    if (typeof progress !== 'number' || Number.isNaN(progress)) {
+      progress = 0
+    }
+    // 进度范围约束 [0,1]
+    const clampedProgress = progress < 0 ? 0 : progress > 1 ? 1 : progress
+    // 应用缓动函数（未知名称回退到 linear）
+    const easedProgress = Easing.get(this.easing, clampedProgress)
+    // 线性插值
+    return this.from + (this.to - this.from) * easedProgress
+  }
+}
+
+export { Clip }

package/src/core/Timeline/DefaultConfig.js

@@ -0,0 +1,41 @@
+// ============================================================================
+// Nimbus2D - Timeline 默认配置
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 提供 Timeline 模块的默认配置常量
+//   2. 集中管理可调参数，避免硬编码
+//
+// 设计决策：
+//   - 使用 Object.freeze 冻结，防止运行时篡改
+//   - 所有默认值集中管理，便于后续扩展和维护
+//   - 与 Camera/SpriteGPULayer 等模块的 DefaultConfig 风格保持一致
+//
+// 四期新增（任务 1.6/4.5）：Timeline 模块默认配置
+// ============================================================================
+
+/**
+ * Timeline 默认配置
+ * @type {Object}
+ * @readonly
+ */
+const TimelineDefaultConfig = Object.freeze({
+  /** 默认是否循环 */
+  loop: false,
+
+  /** 默认循环次数（Infinity 表示无限） */
+  loopCount: Infinity,
+
+  /** 默认是否反向播放 */
+  autoReverse: false,
+
+  /** 默认完成后自动销毁 */
+  autoDestroy: false,
+
+  /** 默认缓动函数名（参考 Easing.list()） */
+  defaultEasing: 'linear',
+
+  /** 默认片段持续时间（秒） */
+  defaultClipDuration: 1
+})
+
+export { TimelineDefaultConfig }

package/src/core/Timeline/Easing.js

@@ -0,0 +1,176 @@
+// ============================================================================
+// Nimbus2D - Easing 缓动函数库
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 提供 10 个内置缓动函数（linear/easeIn/easeOut/easeInOut 等）
+//   2. 提供 get(name, t) 查询方法（未知名称回退到 linear）
+//   3. 提供 register(name, fn) 注册自定义缓动函数
+//   4. 提供 unregister(name) 注销自定义缓动函数（仅允许注销自定义，不可注销内置）
+//   5. 提供 has(name) 查询 + list() 列出所有缓动函数名
+//
+// 设计决策：
+//   - 内置缓动函数表使用 Object.freeze 冻结，防止运行时篡改
+//   - 自定义缓动函数存储在独立的 _customEasings 表，可动态增删
+//   - get() 方法对输入 t 做 [0,1] 范围约束，避免越界值导致缓动函数异常
+//   - register() 方法对 name 和 fn 类型校验，避免无效函数污染查询表
+//   - unregister() 方法禁止注销内置缓动函数，保证基础能力稳定
+//   - easeOutBounce 实现中避免修改入参 t（使用局部变量替代）
+//
+// 四期新增（任务 1.6/4.1）：Timeline 动画引擎的缓动函数库
+// ============================================================================
+
+/**
+ * 内置缓动函数表（冻结，不可变）
+ * 每个函数签名：(t: number) => number，输入 t ∈ [0,1]，输出缓动后的值
+ * @type {Object<string, Function>}
+ */
+const BUILTIN_EASINGS = Object.freeze({
+  /** 线性（匀速） */
+  linear: (t) => t,
+
+  /** 二次缓入（先慢后快） */
+  easeIn: (t) => t * t,
+
+  /** 二次缓出（先快后慢） */
+  easeOut: (t) => t * (2 - t),
+
+  /** 二次缓入缓出（先慢后快再慢） */
+  easeInOut: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+
+  /** 三次缓入（更陡的先慢后快） */
+  easeInCubic: (t) => t * t * t,
+
+  /** 三次缓出（更陡的先快后慢） */
+  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
+
+  /** 三次缓入缓出（更陡的 S 形曲线） */
+  easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2),
+
+  /** 弹性缓入（震荡进入） */
+  easeInElastic: (t) => {
+    // 边界值直接返回，避免 sin 计算精度问题
+    if (t === 0 || t === 1) return t
+    return -Math.pow(2, 10 * (t - 1)) * Math.sin((t - 1.1) * 5 * Math.PI)
+  },
+
+  /** 弹性缓出（震荡结束） */
+  easeOutElastic: (t) => {
+    // 边界值直接返回，避免 sin 计算精度问题
+    if (t === 0 || t === 1) return t
+    return Math.pow(2, -10 * t) * Math.sin((t - 0.1) * 5 * Math.PI) + 1
+  },
+
+  /** 弹跳缓出（模拟球落地弹跳） */
+  easeOutBounce: (t) => {
+    // 使用局部变量避免修改入参 t
+    if (t < 1 / 2.75) {
+      return 7.5625 * t * t
+    }
+    if (t < 2 / 2.75) {
+      const localT = t - 1.5 / 2.75
+      return 7.5625 * localT * localT + 0.75
+    }
+    if (t < 2.5 / 2.75) {
+      const localT = t - 2.25 / 2.75
+      return 7.5625 * localT * localT + 0.9375
+    }
+    const localT = t - 2.625 / 2.75
+    return 7.5625 * localT * localT + 0.984375
+  }
+})
+
+/**
+ * 自定义缓动函数表（可变，用户通过 register/unregister 管理）
+ * @type {Object<string, Function>}
+ */
+const _customEasings = {}
+
+/**
+ * Easing 缓动函数库
+ * 提供内置缓动函数查询 + 自定义缓动函数注册
+ */
+const Easing = {
+  /**
+   * 获取缓动后的值
+   * @param {string} name - 缓动函数名
+   * @param {number} t - 进度值 [0,1]
+   * @returns {number} 缓动后的值（未知名称回退到 linear，无效 t 回退到 0）
+   */
+  get(name, t) {
+    // 校验 t 是否为有效数字（防御 NaN/非数字输入导致缓动函数返回 NaN）
+    if (typeof t !== 'number' || Number.isNaN(t)) {
+      t = 0
+    }
+    // 输入 t 范围约束 [0,1]，避免越界值导致缓动函数异常
+    const clampedT = t < 0 ? 0 : t > 1 ? 1 : t
+    // 优先查找自定义表，其次内置表，最后回退到 linear
+    const fn = _customEasings[name] || BUILTIN_EASINGS[name] || BUILTIN_EASINGS.linear
+    return fn(clampedT)
+  },
+
+  /**
+   * 注册自定义缓动函数
+   * @param {string} name - 缓动函数名（不可与内置重名）
+   * @param {Function} fn - 缓动函数 (t: number) => number
+   * @returns {boolean} 是否注册成功（与内置重名或参数无效时返回 false）
+   */
+  register(name, fn) {
+    // 校验 name 类型
+    if (typeof name !== 'string' || name.length === 0) {
+      return false
+    }
+    // 校验 fn 类型
+    if (typeof fn !== 'function') {
+      return false
+    }
+    // 禁止覆盖内置缓动函数
+    if (Object.prototype.hasOwnProperty.call(BUILTIN_EASINGS, name)) {
+      return false
+    }
+    _customEasings[name] = fn
+    return true
+  },
+
+  /**
+   * 注销自定义缓动函数
+   * @param {string} name - 缓动函数名
+   * @returns {boolean} 是否注销成功（不存在或为内置时返回 false）
+   */
+  unregister(name) {
+    if (!Object.prototype.hasOwnProperty.call(_customEasings, name)) {
+      return false
+    }
+    delete _customEasings[name]
+    return true
+  },
+
+  /**
+   * 判断缓动函数是否已注册（含内置）
+   * @param {string} name - 缓动函数名
+   * @returns {boolean}
+   */
+  has(name) {
+    return Object.prototype.hasOwnProperty.call(BUILTIN_EASINGS, name) ||
+           Object.prototype.hasOwnProperty.call(_customEasings, name)
+  },
+
+  /**
+   * 列出所有缓动函数名（含内置和自定义）
+   * @returns {string[]}
+   */
+  list() {
+    return [...Object.keys(BUILTIN_EASINGS), ...Object.keys(_customEasings)]
+  },
+
+  /**
+   * 清空所有自定义缓动函数（不影响内置）
+   * 主要用于测试隔离
+   */
+  clearCustom() {
+    for (const key of Object.keys(_customEasings)) {
+      delete _customEasings[key]
+    }
+  }
+}
+
+export { Easing, BUILTIN_EASINGS }