@nimbus2d/core 0.0.1

package/src/core/SceneManager/SlideTransition.js

@@ -0,0 +1,113 @@
+// ============================================================================
+// Nimbus2D - 滑动过渡效果
+// ----------------------------------------------------------------------------
+// 源场景滑出，目标场景滑入。支持四个方向：left/right/up/down。
+//
+// 继承关系：
+//   Transition → SlideTransition
+// ============================================================================
+
+import { Transition } from './Transition.js'
+
+class SlideTransition extends Transition {
+  /**
+   * 构造函数
+   * @param {Object} [options={}] - 选项
+   * @param {string} [options.direction='left'] - 滑动方向（left/right/up/down）
+   */
+  constructor(options = {}) {
+    super(options)
+
+    /** @type {string} 滑动方向 */
+    this._direction = options.direction || 'left'
+  }
+
+  /**
+   * 执行滑动过渡
+   * @param {import('./Scene.js').Scene} fromScene - 源场景
+   * @param {import('./Scene.js').Scene} toScene - 目标场景
+   * @returns {Promise<void>}
+   */
+  async execute(fromScene, toScene) {
+    // 触发开始回调
+    if (this._onTransitionStart) this._onTransitionStart()
+
+    // 获取画布尺寸
+    const width = (fromScene && fromScene.stage && fromScene.stage.parent) ? fromScene.stage.parent.width : 800
+    const height = (fromScene && fromScene.stage && fromScene.stage.parent) ? fromScene.stage.parent.height : 600
+
+    // 设置目标场景初始位置
+    if (toScene && toScene.stage) {
+      switch (this._direction) {
+        case 'left':
+          toScene.stage.x = width
+          toScene.stage.y = 0
+          break
+        case 'right':
+          toScene.stage.x = -width
+          toScene.stage.y = 0
+          break
+        case 'up':
+          toScene.stage.x = 0
+          toScene.stage.y = height
+          break
+        case 'down':
+          toScene.stage.x = 0
+          toScene.stage.y = -height
+          break
+      }
+    }
+
+    // 同时滑动：源场景滑出，目标场景滑入
+    await this._animate(this._duration, (progress) => {
+      if (fromScene && fromScene.stage) {
+        switch (this._direction) {
+          case 'left':
+            fromScene.stage.x = -progress * width
+            break
+          case 'right':
+            fromScene.stage.x = progress * width
+            break
+          case 'up':
+            fromScene.stage.y = -progress * height
+            break
+          case 'down':
+            fromScene.stage.y = progress * height
+            break
+        }
+      }
+
+      if (toScene && toScene.stage) {
+        switch (this._direction) {
+          case 'left':
+            toScene.stage.x = width * (1 - progress)
+            break
+          case 'right':
+            toScene.stage.x = -width * (1 - progress)
+            break
+          case 'up':
+            toScene.stage.y = height * (1 - progress)
+            break
+          case 'down':
+            toScene.stage.y = -height * (1 - progress)
+            break
+        }
+      }
+    })
+
+    // 确保最终位置
+    if (fromScene && fromScene.stage) {
+      fromScene.stage.x = 0
+      fromScene.stage.y = 0
+    }
+    if (toScene && toScene.stage) {
+      toScene.stage.x = 0
+      toScene.stage.y = 0
+    }
+
+    // 触发结束回调
+    if (this._onTransitionEnd) this._onTransitionEnd()
+  }
+}
+
+export { SlideTransition }

package/src/core/SceneManager/Transition.js

@@ -0,0 +1,102 @@
+// ============================================================================
+// Nimbus2D - 过渡效果基类
+// ----------------------------------------------------------------------------
+// 所有过渡效果必须继承此基类，提供 execute 方法契约。
+//
+// 设计决策：
+//   - 独立设计（不继承任何类）
+//   - 支持 4 种缓动函数：linear/easeIn/easeOut/easeInOut
+//   - 子类重写 execute(fromScene, toScene) 实现过渡逻辑
+// ============================================================================
+
+/**
+ * 缓动函数映射表
+ * @type {Object<string, Function>}
+ */
+const EASING_FUNCTIONS = {
+  /** 线性（匀速） */
+  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)
+}
+
+class Transition {
+  /**
+   * 构造函数
+   * @param {Object} [options={}] - 选项
+   * @param {number} [options.duration=500] - 持续时间（ms）
+   * @param {string} [options.easing='easeInOut'] - 缓动函数
+   * @param {Function} [options.onTransitionStart] - 开始回调
+   * @param {Function} [options.onTransitionEnd] - 结束回调
+   */
+  constructor(options = {}) {
+    /** @type {number} 持续时间（ms） */
+    this._duration = options.duration || 500
+
+    /** @type {string} 缓动函数名称 */
+    this._easing = EASING_FUNCTIONS[options.easing] ? options.easing : 'easeInOut'
+
+    /** @type {Function|null} 开始回调 */
+    this._onTransitionStart = options.onTransitionStart || null
+
+    /** @type {Function|null} 结束回调 */
+    this._onTransitionEnd = options.onTransitionEnd || null
+  }
+
+  /**
+   * 执行过渡（子类重写）
+   * @param {import('./Scene.js').Scene} fromScene - 源场景
+   * @param {import('./Scene.js').Scene} toScene - 目标场景
+   * @returns {Promise<void>}
+   */
+  async execute(fromScene, toScene) {
+    // 基类空实现，子类必须重写
+  }
+
+  /**
+   * 应用缓动函数
+   * @param {number} t - 进度值 [0, 1]
+   * @param {string} [easing] - 缓动函数名
+   * @returns {number} 缓动后的值
+   * @protected
+   */
+  _applyEasing(t, easing) {
+    const fn = EASING_FUNCTIONS[easing || this._easing]
+    return fn ? fn(t) : EASING_FUNCTIONS.easeInOut(t)
+  }
+
+  /**
+   * 等待指定时长（带缓动动画辅助）
+   * @param {number} duration - 时长（ms）
+   * @param {Function} onFrame - 每帧回调 (progress: number) => void
+   * @returns {Promise<void>}
+   * @protected
+   */
+  _animate(duration, onFrame) {
+    return new Promise((resolve) => {
+      const startTime = performance.now()
+
+      const tick = () => {
+        const elapsed = performance.now() - startTime
+        const rawProgress = Math.min(elapsed / duration, 1)
+        const easedProgress = this._applyEasing(rawProgress)
+
+        onFrame(easedProgress)
+
+        if (rawProgress < 1) {
+          requestAnimationFrame(tick)
+        } else {
+          resolve()
+        }
+      }
+
+      requestAnimationFrame(tick)
+    })
+  }
+}
+
+export { Transition }

package/src/core/SceneManager/ZoomTransition.js

@@ -0,0 +1,119 @@
+// ============================================================================
+// Nimbus2D - ZoomTransition 缩放转场效果
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 实现缩放转场动画（源场景缩小消失 + 目标场景放大出现）
+//   2. 支持 scaleFrom/scaleTo 配置源场景缩放范围
+//   3. 目标场景从 0 缩放到 1，并同步淡入
+//   4. 复用 _animate/_applyEasing 提供缓动效果
+//
+// 继承关系：
+//   Transition → ZoomTransition
+//
+// 设计决策：
+//   - 继承现有 Transition 基类（execute 契约），复用 _animate/_applyEasing
+//   - 源场景缩放范围可配置（scaleFrom→scaleTo），目标场景固定 0→1
+//   - 同步淡入淡出 alpha 增强转场视觉效果
+//   - 完成后恢复 stage 的 scale/alpha 到正常值（避免状态残留）
+//
+// 四期新增（任务 1.5/3.2）：对标 Phaser 的 ZoomTransition
+// ============================================================================
+
+import { Transition } from './Transition.js'
+
+class ZoomTransition extends Transition {
+  /**
+   * 构造函数
+   * @param {Object} [options={}] - 选项（继承自 Transition）
+   * @param {number} [options.scaleFrom=1] - 源场景起始缩放（默认 1，正常大小）
+   * @param {number} [options.scaleTo=0] - 源场景结束缩放（默认 0，完全缩小）
+   */
+  constructor(options = {}) {
+    super(options)
+
+    /** @type {number} 源场景起始缩放 */
+    this._scaleFrom = options.scaleFrom ?? 1
+
+    /** @type {number} 源场景结束缩放 */
+    this._scaleTo = options.scaleTo ?? 0
+  }
+
+  /**
+   * 执行缩放转场
+   * @param {import('./Scene.js').Scene} fromScene - 源场景
+   * @param {import('./Scene.js').Scene} toScene - 目标场景
+   * @returns {Promise<void>}
+   */
+  async execute(fromScene, toScene) {
+    // 触发开始回调
+    if (this._onTransitionStart) this._onTransitionStart()
+
+    /** @type {import('pixi.js').Container|null} 源场景 stage */
+    const fromStage = fromScene ? fromScene.stage : null
+    /** @type {import('pixi.js').Container|null} 目标场景 stage */
+    const toStage = toScene ? toScene.stage : null
+
+    // 设置目标场景初始状态（缩放为 0，alpha 为 0，完全不可见）
+    if (toStage) {
+      toStage.scale.set(0, 0)
+      toStage.alpha = 0
+    }
+
+    // 设置源场景初始状态（缩放为 scaleFrom，alpha 为 1，完全可见）
+    if (fromStage) {
+      fromStage.scale.set(this._scaleFrom, this._scaleFrom)
+      fromStage.alpha = 1
+    }
+
+    try {
+      // 执行缩放动画
+      await this._animate(this._duration, (progress) => {
+        // 源场景：从 scaleFrom 缩放到 scaleTo，同步淡出
+        if (fromStage) {
+          /** @type {number} 当前源场景缩放值（线性插值） */
+          const fromScale = this._scaleFrom + (this._scaleTo - this._scaleFrom) * progress
+          fromStage.scale.set(fromScale, fromScale)
+          fromStage.alpha = 1 - progress
+        }
+
+        // 目标场景：从 0 放大到 1，同步淡入
+        if (toStage) {
+          toStage.scale.set(progress, progress)
+          toStage.alpha = progress
+        }
+      })
+    } finally {
+      // 无论动画成功或失败，都恢复 stage 到正常状态
+      this._restoreStages(fromStage, toStage)
+    }
+
+    // 触发结束回调
+    if (this._onTransitionEnd) this._onTransitionEnd()
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法：状态恢复
+  // --------------------------------------------------------------------------
+
+  /**
+   * 恢复 stage 的 scale/alpha 到正常值
+   * 避免转场异常时 stage 状态残留（scale=0 或 alpha=0 导致场景不可见）
+   * @param {import('pixi.js').Container|null} fromStage - 源场景 stage
+   * @param {import('pixi.js').Container|null} toStage - 目标场景 stage
+   * @private
+   */
+  _restoreStages(fromStage, toStage) {
+    // 源场景：恢复到正常显示状态（转场结束后源场景会被 stop，但状态仍需恢复）
+    if (fromStage) {
+      fromStage.scale.set(1, 1)
+      fromStage.alpha = 1
+    }
+    // 目标场景：恢复到正常显示状态（scale=1, alpha=1）
+    if (toStage) {
+      toStage.scale.set(1, 1)
+      toStage.alpha = 1
+    }
+  }
+}
+
+export { ZoomTransition }

package/src/core/SceneManager/index.js

@@ -0,0 +1,12 @@
+// ============================================================================
+// Nimbus2D - SceneManager 模块统一导出
+// ============================================================================
+
+export { SceneManager } from './SceneManager.js'
+export { Scene } from './Scene.js'
+export { SceneState } from './SceneState.js'
+export { Transition } from './Transition.js'
+export { FadeTransition } from './FadeTransition.js'
+export { SlideTransition } from './SlideTransition.js'
+export { MaskTransition } from './MaskTransition.js'
+export { ZoomTransition } from './ZoomTransition.js'

package/src/core/SpriteGPULayer/SpriteGPULayer.js

@@ -0,0 +1,321 @@
+// ============================================================================
+// Nimbus2D - SpriteGPULayer GPU 批量精灵容器
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 继承 PIXI.Container，将添加到其中的 Sprite 自动合批 GPU 渲染
+//   2. 按纹理分组管理 Sprite，便于统计 batch 数量
+//   3. 通过 EventBus 广播渲染和容量事件
+//   4. 提供 setTexture 批量替换纹理的能力
+//
+// 设计决策：
+//   - 继承 PIXI.Container：利用 PixiJS v8 BatchRenderer 自动合批，无需手动实现
+//   - 按纹理分组：以 Texture 实例为 Map key（Map 支持对象 key，O(1) 查找）
+//   - 渲染事件：重写 render()，先调用 super.render() 后发射事件（确保渲染完成）
+//   - 容量事件：addSprite 时检测纹理组容量达上限立即发射
+//   - EventBus 注入：通过 setEventBus 注入，避免构造函数耦合
+//
+// 四期新增（任务 1.1）：对标 Phaser 的 SpriteGPULayer
+// ============================================================================
+
+import { Container, Sprite } from 'pixi.js'
+import { SpriteGPULayerEventType, SpriteGPULayerError } from './SpriteGPULayerTypes.js'
+
+class SpriteGPULayer extends Container {
+  /**
+   * 构造函数
+   * @param {Object} [options={}] - 配置
+   * @param {number} [options.maxBatchSize=4096] - 单 batch 最大 Sprite 数
+   *        超过此值时发射 gpu:spriteBatch:full 事件（仅提示，不阻止添加）
+   * @param {string} [options.label] - 容器标签（用于事件识别）
+   */
+  constructor(options = {}) {
+    super()
+
+    /**
+     * 单 batch 最大 Sprite 数
+     * @type {number}
+     * @private
+     */
+    this._maxBatchSize = options.maxBatchSize ?? 4096
+
+    /**
+     * 容器标签（用于事件识别，优先使用 options.label，其次 PIXI.label）
+     */
+    if (options.label) {
+      this.label = options.label
+    }
+
+    /**
+     * 管理的 Sprite 列表
+     * @type {Sprite[]}
+     * @private
+     */
+    this._sprites = []
+
+    /**
+     * 按纹理分组的 Sprite 集合
+     * key: Texture 实例（Map 支持对象 key）
+     * value: Set<Sprite>
+     * @type {Map<import('pixi.js').Texture, Set<Sprite>>}
+     * @private
+     */
+    this._textureGroups = new Map()
+
+    /**
+     * 事件总线（通过 setEventBus 注入）
+     * @type {import('../../core/EventBus/EventBus.js').EventBus|null}
+     * @private
+     */
+    this._eventBus = null
+
+    /**
+     * 是否已销毁（与 PIXI 的 destroyed 字段独立，用于我们的销毁逻辑）
+     * @type {boolean}
+     * @private
+     */
+    this._isDestroyed = false
+  }
+
+  // --------------------------------------------------------------------------
+  // Sprite 管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 添加 Sprite 到 GPU 层
+   * 同纹理 Sprite 由 PixiJS BatchRenderer 自动合批为单个 draw call
+   *
+   * @param {Sprite} sprite - Sprite 实例
+   * @returns {SpriteGPULayer} this（链式调用）
+   * @throws {SpriteGPULayerError} sprite 不是 PIXI.Sprite 实例
+   */
+  addSprite(sprite) {
+    if (this._isDestroyed) return this
+
+    // 参数校验：必须是 PIXI.Sprite 实例
+    if (!(sprite instanceof Sprite)) {
+      throw new SpriteGPULayerError('addSprite 参数必须是 PIXI.Sprite 实例')
+    }
+
+    // 防止重复添加：若已存在则直接返回（幂等）
+    if (this._sprites.indexOf(sprite) !== -1) {
+      return this
+    }
+
+    /** @type {import('pixi.js').Texture|null} Sprite 的纹理 */
+    const texture = sprite.texture
+    if (!texture) {
+      throw new SpriteGPULayerError('Sprite 必须有纹理')
+    }
+
+    // 1. 添加到管理列表
+    this._sprites.push(sprite)
+
+    // 2. 按纹理分组（以 Texture 实例为 key）
+    let group = this._textureGroups.get(texture)
+    if (!group) {
+      group = new Set()
+      this._textureGroups.set(texture, group)
+    }
+    group.add(sprite)
+
+    // 3. 添加到 PIXI.Container（实际合批由 PixiJS BatchRenderer 自动处理）
+    this.addChild(sprite)
+
+    // 4. 检测纹理组是否达到上限，发射容量事件
+    if (group.size >= this._maxBatchSize) {
+      this._emitEvent(SpriteGPULayerEventType.BATCH_FULL, {
+        name: this.label,
+        textureGroupSize: group.size,
+        maxBatchSize: this._maxBatchSize
+      })
+    }
+
+    return this
+  }
+
+  /**
+   * 从 GPU 层移除 Sprite
+   * @param {Sprite} sprite - Sprite 实例
+   * @returns {boolean} 是否移除成功
+   */
+  removeSprite(sprite) {
+    if (this._isDestroyed) return false
+    if (!(sprite instanceof Sprite)) return false
+
+    // 1. 从管理列表移除
+    const index = this._sprites.indexOf(sprite)
+    if (index === -1) return false
+    this._sprites.splice(index, 1)
+
+    // 2. 从纹理分组移除（处理 texture 被外部修改的情况）
+    this._removeSpriteFromGroups(sprite)
+
+    // 3. 从 PIXI.Container 移除
+    this.removeChild(sprite)
+
+    return true
+  }
+
+  /**
+   * 批量替换所有 Sprite 的纹理
+   * 替换后所有 Sprite 共享同一纹理，重新分组为单个纹理组
+   *
+   * @param {import('pixi.js').Texture} texture - 新纹理
+   */
+  setTexture(texture) {
+    if (this._isDestroyed) return
+    if (!texture) return
+
+    // 遍历设置新纹理
+    for (let i = 0; i < this._sprites.length; i++) {
+      this._sprites[i].texture = texture
+    }
+
+    // 重新分组：纹理统一后所有 Sprite 在同一组
+    this._textureGroups.clear()
+    if (this._sprites.length > 0) {
+      const newGroup = new Set(this._sprites)
+      this._textureGroups.set(texture, newGroup)
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 统计与查询
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取 GPU 层统计信息
+   * @returns {{ spriteCount: number, batchCount: number, maxBatchSize: number, textureGroupCount: number }}
+   */
+  getStats() {
+    return {
+      spriteCount: this._sprites.length,
+      batchCount: this._textureGroups.size,
+      maxBatchSize: this._maxBatchSize,
+      textureGroupCount: this._textureGroups.size
+    }
+  }
+
+  /** @type {boolean} 是否已销毁 */
+  get isDestroyed() {
+    return this._isDestroyed
+  }
+
+  // --------------------------------------------------------------------------
+  // EventBus 注入
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注入事件总线
+   * 由 Scene 或用户调用，注入后才能发射 gpu:spriteBatch:* 事件
+   *
+   * @param {import('../../core/EventBus/EventBus.js').EventBus} eventBus - 事件总线实例
+   */
+  setEventBus(eventBus) {
+    this._eventBus = eventBus
+  }
+
+  // --------------------------------------------------------------------------
+  // 渲染钩子（重写 PIXI.Container.render）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 重写 PIXI.Container.render
+   * 先调用 super.render(renderer) 完成 PIXI 标准渲染流程，
+   * 然后发射 gpu:spriteBatch:rendered 事件（仅在 EventBus 已注入时）
+   *
+   * @param {import('pixi.js').Renderer} renderer - 渲染器
+   */
+  render(renderer) {
+    // 先完成 PIXI 标准渲染（含可见性检查、变换、子节点渲染等）
+    super.render(renderer)
+
+    // 渲染完成后发射事件（仅当 EventBus 已注入）
+    if (this._eventBus) {
+      this._emitEvent(SpriteGPULayerEventType.RENDERED, {
+        name: this.label,
+        spriteCount: this._sprites.length,
+        batchCount: this._textureGroups.size
+      })
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 发射事件（内部方法）
+   * @param {string} eventType - 事件类型
+   * @param {Object} payload - 事件数据
+   * @private
+   */
+  _emitEvent(eventType, payload) {
+    if (this._eventBus) {
+      this._eventBus.emit(eventType, payload)
+    }
+  }
+
+  /**
+   * 从纹理分组中移除 Sprite（内部方法）
+   *
+   * 处理 sprite.texture 被外部修改导致用当前 texture 找不到原组的情况：
+   *   1. 先用 sprite.texture 快速查找（O(1)）—— 覆盖正常场景
+   *   2. 快速查找失败时遍历所有组（O(n)）—— 覆盖 texture 被外部修改场景
+   *
+   * 这样保证 _textureGroups 中不会残留 sprite 引用，避免内存泄漏
+   *
+   * @param {Sprite} sprite - Sprite 实例
+   * @private
+   */
+  _removeSpriteFromGroups(sprite) {
+    // 1. 先用当前 texture 快速查找（正常场景，O(1)）
+    const texture = sprite.texture
+    if (texture) {
+      const group = this._textureGroups.get(texture)
+      if (group && group.has(sprite)) {
+        group.delete(sprite)
+        // 纹理组为空时清理，避免 Map 无限增长
+        if (group.size === 0) {
+          this._textureGroups.delete(texture)
+        }
+        return
+      }
+    }
+
+    // 2. 快速查找失败，遍历所有组查找（texture 被外部修改场景，O(n)）
+    for (const [key, group] of this._textureGroups) {
+      if (group.has(sprite)) {
+        group.delete(sprite)
+        if (group.size === 0) {
+          this._textureGroups.delete(key)
+        }
+        return
+      }
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 销毁
+  // --------------------------------------------------------------------------
+
+  /**
+   * 销毁 GPU 层
+   * 清理所有内部引用和 PIXI 资源
+   * @param {import('pixi.js').DestroyOptions|boolean} [options] - PIXI 销毁选项
+   */
+  destroy(options) {
+    if (this._isDestroyed) return
+    this._isDestroyed = true
+
+    // 清理内部引用
+    this._sprites.length = 0
+    this._textureGroups.clear()
+    this._eventBus = null
+
+    // 调用 PIXI.Container.destroy 销毁子节点和资源
+    super.destroy(options)
+  }
+}
+
+export { SpriteGPULayer }