@nimbus2d/core 0.0.1

package/src/core/SceneManager/FadeTransition.js

@@ -0,0 +1,64 @@
+// ============================================================================
+// Nimbus2D - 淡入淡出过渡效果
+// ----------------------------------------------------------------------------
+// 淡出源场景（alpha 1 → 0），淡入目标场景（alpha 0 → 1）。
+//
+// 继承关系：
+//   Transition → FadeTransition
+// ============================================================================
+
+import { Transition } from './Transition.js'
+
+class FadeTransition extends Transition {
+  /**
+   * 构造函数
+   * @param {Object} [options={}] - 选项（继承自 Transition）
+   */
+  constructor(options = {}) {
+    super(options)
+  }
+
+  /**
+   * 执行淡入淡出过渡
+   * @param {import('./Scene.js').Scene} fromScene - 源场景
+   * @param {import('./Scene.js').Scene} toScene - 目标场景
+   * @returns {Promise<void>}
+   */
+  async execute(fromScene, toScene) {
+    // 触发开始回调
+    if (this._onTransitionStart) this._onTransitionStart()
+
+    // 确保目标场景可见且初始 alpha 为 0
+    if (toScene && toScene.stage) {
+      toScene.stage.alpha = 0
+    }
+
+    // 阶段1：淡出源场景（半段时间）
+    const halfDuration = this._duration / 2
+    if (fromScene && fromScene.stage) {
+      await this._animate(halfDuration, (progress) => {
+        fromScene.stage.alpha = 1 - progress
+      })
+    }
+
+    // 阶段2：淡入目标场景（半段时间）
+    if (toScene && toScene.stage) {
+      await this._animate(halfDuration, (progress) => {
+        toScene.stage.alpha = progress
+      })
+    }
+
+    // 确保最终状态
+    if (fromScene && fromScene.stage) {
+      fromScene.stage.alpha = 1
+    }
+    if (toScene && toScene.stage) {
+      toScene.stage.alpha = 1
+    }
+
+    // 触发结束回调
+    if (this._onTransitionEnd) this._onTransitionEnd()
+  }
+}
+
+export { FadeTransition }

package/src/core/SceneManager/MaskTransition.js

@@ -0,0 +1,234 @@
+// ============================================================================
+// Nimbus2D - MaskTransition 遮罩转场效果
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 实现遮罩转场动画（目标场景按遮罩形状逐渐显示）
+//   2. 支持 circle/rect/diamond 三种内置遮罩形状
+//   3. 支持 customMask 自定义遮罩函数（用户返回 Graphics 绘制逻辑）
+//   4. 复用同一 Graphics 实例避免每帧创建（性能优化）
+//   5. 完成后自动清理 Graphics 资源（避免内存泄漏）
+//
+// 继承关系：
+//   Transition → MaskTransition
+//
+// 设计决策：
+//   - 继承现有 Transition 基类（execute 契约），复用 _animate/_applyEasing
+//   - Graphics 复用：同一实例 clear() 后重绘，避免每帧 GC 压力
+//   - 遮罩挂载位置：优先挂载到 toStage.parent（pixi stage），降级到 toStage 本身
+//   - 资源清理：execute() 完成后自动销毁 Graphics，destroy() 提供强制清理入口
+//   - 视口尺寸获取：从 toStage.parent 降级到 800x600 默认值
+//
+// 四期新增（任务 1.5/3.1）：对标 Phaser 的 MaskTransition
+// ============================================================================
+
+import { Graphics } from 'pixi.js'
+import { Transition } from './Transition.js'
+
+class MaskTransition extends Transition {
+  /**
+   * 构造函数
+   * @param {Object} [options={}] - 选项（继承自 Transition）
+   * @param {string} [options.maskShape='circle'] - 遮罩形状（circle/rect/diamond）
+   * @param {Function} [options.customMask] - 自定义遮罩函数 (graphics, progress, viewWidth, viewHeight) => void
+   *        用户提供自定义绘制逻辑时，maskShape 参数被忽略
+   */
+  constructor(options = {}) {
+    super(options)
+
+    /** @type {string} 遮罩形状（circle/rect/diamond） */
+    this._maskShape = options.maskShape ?? 'circle'
+
+    /**
+     * 自定义遮罩函数
+     * 签名：(graphics, progress, viewWidth, viewHeight) => void
+     * 用户负责在函数内调用 graphics.clear() 并绘制遮罩形状
+     * @type {Function|null}
+     */
+    this._customMask = options.customMask ?? null
+
+    /**
+     * 复用的 Graphics 实例
+     * 整个转场过程复用同一实例，避免每帧创建销毁
+     * @type {Graphics|null}
+     * @private
+     */
+    this._maskGraphics = new Graphics()
+
+    /** @type {boolean} Graphics 是否已销毁（防重复销毁） */
+    this._graphicsDestroyed = false
+  }
+
+  /**
+   * 执行遮罩转场
+   * @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 toStage = toScene ? toScene.stage : null
+    /** @type {import('pixi.js').Container|null} 源场景 stage */
+    const fromStage = fromScene ? fromScene.stage : null
+
+    // 无目标场景时直接结束（无法应用遮罩）
+    if (!toStage) {
+      if (this._onTransitionEnd) this._onTransitionEnd()
+      return
+    }
+
+    // 获取视口尺寸（从 toStage.parent 降级到默认值 800x600）
+    const viewWidth = (toStage.parent && toStage.parent.width) ? toStage.parent.width : 800
+    const viewHeight = (toStage.parent && toStage.parent.height) ? toStage.parent.height : 600
+
+    // 将 Graphics 添加到显示列表（PIXI v8 要求 mask 必须在显示列表中）
+    // 优先添加到 toStage.parent（与 toStage 同级），降级到 toStage 本身
+    /** @type {import('pixi.js').Container} Graphics 挂载容器 */
+    const maskParent = toStage.parent || toStage
+    maskParent.addChild(this._maskGraphics)
+
+    // 应用遮罩到目标场景
+    toStage.mask = this._maskGraphics
+
+    try {
+      // 执行遮罩动画
+      await this._animate(this._duration, (progress) => {
+        // 绘制遮罩（每帧重绘）
+        this._drawMask(progress, viewWidth, viewHeight)
+        // 源场景同步淡出（增强转场视觉效果）
+        if (fromStage) {
+          fromStage.alpha = 1 - progress
+        }
+      })
+    } finally {
+      // 无论动画成功或失败，都清理遮罩资源并恢复源场景 alpha
+      // 避免异常情况下 fromStage.alpha 残留为 0 导致场景不可见
+      this._cleanupMask(toStage)
+      if (fromStage) {
+        fromStage.alpha = 1
+      }
+    }
+
+    // 触发结束回调
+    if (this._onTransitionEnd) this._onTransitionEnd()
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法：遮罩绘制
+  // --------------------------------------------------------------------------
+
+  /**
+   * 绘制遮罩（清空并重绘复用的 Graphics）
+   * @param {number} progress - 进度 0→1
+   * @param {number} viewWidth - 视口宽度
+   * @param {number} viewHeight - 视口高度
+   * @private
+   */
+  _drawMask(progress, viewWidth, viewHeight) {
+    // 自定义遮罩优先
+    if (typeof this._customMask === 'function') {
+      try {
+        this._customMask(this._maskGraphics, progress, viewWidth, viewHeight)
+      } catch (e) {
+        // 自定义遮罩异常时降级到 circle
+        this._drawBuiltinMask(progress, viewWidth, viewHeight)
+      }
+      return
+    }
+
+    this._drawBuiltinMask(progress, viewWidth, viewHeight)
+  }
+
+  /**
+   * 绘制内置遮罩（circle/rect/diamond）
+   * @param {number} progress - 进度 0→1
+   * @param {number} viewWidth - 视口宽度
+   * @param {number} viewHeight - 视口高度
+   * @private
+   */
+  _drawBuiltinMask(progress, viewWidth, viewHeight) {
+    this._maskGraphics.clear()
+
+    // 遮罩尺寸：取视口对角线长度乘以 progress，确保完全覆盖
+    /** @type {number} 对角线长度（保证任意形状都能覆盖整个视口） */
+    const maxSize = Math.sqrt(viewWidth * viewWidth + viewHeight * viewHeight) * progress
+    /** @type {number} 中心 X */
+    const cx = viewWidth / 2
+    /** @type {number} 中心 Y */
+    const cy = viewHeight / 2
+
+    switch (this._maskShape) {
+      case 'circle':
+        // 圆形遮罩：从中心向外扩展
+        this._maskGraphics.circle(cx, cy, maxSize / 2)
+        break
+      case 'rect':
+        // 矩形遮罩：从中心向外扩展
+        this._maskGraphics.rect(
+          cx - maxSize / 2,
+          cy - maxSize / 2,
+          maxSize,
+          maxSize
+        )
+        break
+      case 'diamond':
+        // 菱形遮罩：从中心向外扩展
+        this._maskGraphics.moveTo(cx, cy - maxSize / 2)
+        this._maskGraphics.lineTo(cx + maxSize / 2, cy)
+        this._maskGraphics.lineTo(cx, cy + maxSize / 2)
+        this._maskGraphics.lineTo(cx - maxSize / 2, cy)
+        this._maskGraphics.closePath()
+        break
+      default:
+        // 未知形状降级到 circle
+        this._maskGraphics.circle(cx, cy, maxSize / 2)
+        break
+    }
+
+    // 填充白色（mask 只关心 alpha 通道，颜色不影响）
+    this._maskGraphics.fill(0xFFFFFF)
+  }
+
+  /**
+   * 清理遮罩资源
+   * 移除 mask 引用 + 从父容器移除 Graphics + 销毁 Graphics
+   * @param {import('pixi.js').Container|null} toStage - 目标场景 stage
+   * @private
+   */
+  _cleanupMask(toStage) {
+    // 移除 mask 引用（避免引用悬挂）
+    if (toStage) {
+      toStage.mask = null
+    }
+
+    // 从父容器移除 Graphics 并销毁
+    if (this._maskGraphics && !this._graphicsDestroyed) {
+      if (this._maskGraphics.parent) {
+        this._maskGraphics.parent.removeChild(this._maskGraphics)
+      }
+      try {
+        this._maskGraphics.destroy()
+      } catch (e) {
+        // 销毁异常忽略
+      }
+      this._maskGraphics = null
+      this._graphicsDestroyed = true
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 销毁
+  // --------------------------------------------------------------------------
+
+  /**
+   * 销毁遮罩转场（强制清理 Graphics 资源）
+   * 正常流程下 execute() 完成后会自动清理，此方法用于异常情况下强制清理
+   */
+  destroy() {
+    this._cleanupMask(null)
+  }
+}
+
+export { MaskTransition }

package/src/core/SceneManager/Scene.js

@@ -0,0 +1,221 @@
+// ============================================================================
+// Nimbus2D - 场景基类
+// ----------------------------------------------------------------------------
+// 所有游戏场景必须继承此基类，提供场景级事件能力和生命周期钩子。
+//
+// 设计决策：
+//   - 继承 EventEmitter，提供场景级事件能力
+//   - 构造函数创建 Container（从 pixi.js 导入）作为 stage
+//   - _state 由 SceneManager 设置（构造函数不设置，见决策 106）
+//   - _assetManager 由 SceneManager 注入（通过 _setAssetManager）
+//   - 内置资源引用管理（_retainAsset + _releaseAssets）
+//   - 5 个生命周期钩子：onCreate/onStart/onStop/onPause/onResume
+//   - 无 onDestroy 方法（资源引用由 destroy 自动释放）
+// ============================================================================
+
+import { Container } from 'pixi.js'
+import { EventEmitter } from '../../base/EventEmitter.js'
+import { SceneState } from './SceneState.js'
+import { SceneError } from '../../errors/SceneError.js'
+
+class Scene extends EventEmitter {
+  /**
+   * 构造函数
+   * @param {string} name - 场景名称
+   */
+  constructor(name) {
+    super()
+
+    /** @type {string} 场景名称 */
+    this._name = name
+
+    /** @type {import('pixi.js').Container} 场景舞台（构造函数中创建） */
+    this._stage = new Container()
+
+    /** @type {SceneState|null} 场景状态（由 SceneManager 设置，构造函数不设置） */
+    this._state = null
+
+    /** @type {boolean} 是否可见 */
+    this._isVisible = true
+
+    /** @type {number} 层级 */
+    this._zIndex = 0
+
+    /** @type {import('../AssetManager/AssetManager.js').AssetManager|null} 资源管理器（由 SceneManager 注入） */
+    this._assetManager = null
+
+    /** @type {Set<string>} 已引用的资源 ID 集合 */
+    this._retainedAssets = new Set()
+  }
+
+  // --------------------------------------------------------------------------
+  // 属性
+  // --------------------------------------------------------------------------
+
+  /** @type {string} 场景名称 */
+  get name() { return this._name }
+
+  /** @type {SceneState|null} 场景状态 */
+  get state() { return this._state }
+
+  /** @type {import('pixi.js').Container} 场景舞台 */
+  get stage() { return this._stage }
+
+  /** @type {boolean} 是否可见 */
+  get isVisible() { return this._isVisible }
+
+  /** @type {number} 层级 */
+  get zIndex() { return this._zIndex }
+
+  // --------------------------------------------------------------------------
+  // 生命周期钩子（子类重写）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 创建时调用（仅一次，首次 start 时调用）
+   * @returns {Promise<void>|void}
+   */
+  async onCreate() {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 启动时调用（每次 start）
+   * @returns {Promise<void>|void}
+   */
+  async onStart() {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 停止时调用（每次 stop）
+   * @returns {Promise<void>|void}
+   */
+  async onStop() {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 暂停时调用
+   * @returns {void}
+   */
+  onPause() {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 恢复时调用
+   * @returns {void}
+   */
+  onResume() {
+    // 基类空实现，子类按需重写
+  }
+
+  // --------------------------------------------------------------------------
+  // 更新方法（子类重写）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 每帧更新
+   * @param {number} delta - 帧间隔（秒）
+   */
+  update(delta) {
+    // 基类空实现，子类按需重写
+  }
+
+  // --------------------------------------------------------------------------
+  // 资源引用管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 引用资源（异步）
+   * @param {string} assetId - 资源 ID
+   * @returns {Promise<boolean>} - 是否引用成功
+   */
+  async _retainAsset(assetId) {
+    // 已引用过则直接返回
+    if (this._retainedAssets.has(assetId)) return true
+
+    // AssetManager 必须先注入
+    if (!this._assetManager) {
+      throw new SceneError(`Scene ${this._name} 未注入 AssetManager，请通过 SceneManager.register 注册场景`)
+    }
+
+    const data = await this._assetManager.retain(assetId, this._name)
+
+    // 使用 !== undefined && !== null 判断成功，避免 falsy 值误判
+    const ok = data !== undefined && data !== null
+    if (ok) {
+      this._retainedAssets.add(assetId)
+    }
+    return ok
+  }
+
+  /**
+   * 释放所有引用的资源（由 destroy 自动调用）
+   */
+  _releaseAssets() {
+    if (!this._assetManager) return
+    for (const assetId of this._retainedAssets) {
+      try {
+        this._assetManager.release(assetId, this._name)
+      } catch (e) {
+        // 忽略释放错误
+      }
+    }
+    this._retainedAssets.clear()
+  }
+
+  // --------------------------------------------------------------------------
+  // 内部方法（由 SceneManager 调用）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注入 AssetManager 引用（由 SceneManager.register 时调用）
+   * @param {import('../AssetManager/AssetManager.js').AssetManager} assetManager - 资源管理器实例
+   * @private
+   */
+  _setAssetManager(assetManager) {
+    this._assetManager = assetManager
+  }
+
+  /**
+   * 设置场景状态（由 SceneManager 调用）
+   * @param {SceneState} state - 新状态
+   * @private
+   */
+  _setState(state) {
+    this._state = state
+  }
+
+  // --------------------------------------------------------------------------
+  // 销毁
+  // --------------------------------------------------------------------------
+
+  /**
+   * 销毁场景（自动释放资源引用 + 销毁 stage）
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    // 释放所有资源引用
+    this._releaseAssets()
+
+    // 销毁场景舞台 Container
+    if (this._stage) {
+      this._stage.destroy({ children: true })
+      this._stage = null
+    }
+
+    this._state = SceneState.DESTROYED
+    this._assetManager = null
+    this._retainedAssets.clear()
+
+    // 先 emit destroyed 事件（super.destroy 后 emit 无效）
+    this.emit('destroyed', { name: this._name })
+
+    // 调用父类 destroy 设置 _destroyed = true 并清理监听器
+    super.destroy()
+  }
+}
+
+export { Scene }