@nimbus2d/core 0.0.1

package/src/core/SceneManager/SceneManager.js

@@ -0,0 +1,658 @@
+// ============================================================================
+// Nimbus2D - SceneManager 场景管理
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 多活动场景并行 + 独立 stage + 顺序叠加
+//   2. 场景栈 push/pop（与多场景同时支持）
+//   3. 完整生命周期 API：register/start/stop/pause/resume/setVisible/setZOrder
+//   4. 过渡效果核心内置 + 可扩展（FadeTransition、SlideTransition）
+//   5. Scene 基类继承 EventEmitter + 5 个生命周期方法
+//   6. 场景间通信仅通过 EventBus
+//   7. Scene 内置资源引用 + 自动释放
+//
+// 继承关系：
+//   EventEmitter → Subsystem → SceneManager（Lifecycle 内第三个初始化）
+// ============================================================================
+
+import { Subsystem } from '../../base/Subsystem.js'
+import { SceneState } from './SceneState.js'
+import { SceneError, SceneNotFoundError, SceneDuplicateError, SceneStateError } from '../../errors/SceneError.js'
+import { FadeTransition } from './FadeTransition.js'
+import { SlideTransition } from './SlideTransition.js'
+import { MaskTransition } from './MaskTransition.js'
+import { ZoomTransition } from './ZoomTransition.js'
+
+class SceneManager extends Subsystem {
+  /**
+   * 构造函数
+   * @param {import('../EventBus/EventBus.js').EventBus} eventBus - 全局事件总线
+   * @param {import('../ConfigSystem/ConfigSystem.js').ConfigSystem} config - 配置系统
+   * @param {import('../Logger/Logger.js').Logger} logger - 日志系统
+   * @param {import('../AssetManager/AssetManager.js').AssetManager} assetManager - 资源管理
+   * @param {object} pixi - PixiJS Application 实例
+   */
+  constructor(eventBus, config, logger, assetManager, pixi) {
+    super(eventBus, config, logger)
+
+    /** @type {import('../AssetManager/AssetManager.js').AssetManager} 资源管理器 */
+    this._assetManager = assetManager
+
+    /** @type {object} PixiJS Application 实例 */
+    this._pixi = pixi
+
+    /** @type {Map<string, import('./Scene.js').Scene>} 场景映射（name → scene） */
+    this._scenes = new Map()
+
+    /** @type {Set<string>} 运行中的场景名称集合 */
+    this._activeScenes = new Set()
+
+    /** @type {string[]} 场景栈 */
+    this._stack = []
+  }
+
+  // --------------------------------------------------------------------------
+  // 场景注册
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注册场景
+   * @param {import('./Scene.js').Scene} scene - 场景实例
+   * @returns {Promise<void>}
+   * @throws {SceneDuplicateError} 场景重复注册
+   */
+  async register(scene) {
+    if (this._scenes.has(scene.name)) {
+      throw new SceneDuplicateError(scene.name)
+    }
+
+    // 注入 AssetManager 引用（决策 106）
+    scene._setAssetManager(this._assetManager)
+
+    // 设置场景状态为 REGISTERED（决策 106）
+    scene._setState(SceneState.REGISTERED)
+
+    this._scenes.set(scene.name, scene)
+
+    this.emit('scene:registered', { name: scene.name, scene })
+  }
+
+  /**
+   * 注销场景（销毁实例）
+   * @param {string} name - 场景名称
+   * @returns {Promise<void>}
+   */
+  async unregister(name) {
+    const scene = this._getSceneOrThrow(name)
+
+    // 如果场景正在运行，先停止
+    if (scene.state === SceneState.RUNNING || scene.state === SceneState.PAUSED) {
+      await this.stop(name)
+    }
+
+    // 从栈中移除
+    this._stack = this._stack.filter((n) => n !== name)
+
+    // 从运行集合移除
+    this._activeScenes.delete(name)
+
+    // 从 pixi stage 移除
+    if (scene.stage && this._pixi && this._pixi.stage) {
+      this._pixi.stage.removeChild(scene.stage)
+    }
+
+    // 销毁场景
+    await scene.destroy()
+
+    // 从映射移除
+    this._scenes.delete(name)
+
+    this.emit('scene:unregistered', { name })
+  }
+
+  // --------------------------------------------------------------------------
+  // 场景生命周期
+  // --------------------------------------------------------------------------
+
+  /**
+   * 启动场景
+   * @param {string} name - 场景名称
+   * @returns {Promise<void>}
+   */
+  async start(name) {
+    const scene = this._getSceneOrThrow(name)
+
+    // 状态检查
+    if (scene.state !== SceneState.REGISTERED && scene.state !== SceneState.STOPPED) {
+      throw new SceneStateError(name, scene.state, `${SceneState.REGISTERED} 或 ${SceneState.STOPPED}`)
+    }
+
+    // 记录是否为首次启动（REGISTERED → STARTING），用于决定是否调用 onCreate
+    const isFirstStart = scene.state === SceneState.REGISTERED
+
+    // 设置为启动中
+    scene._setState(SceneState.STARTING)
+
+    try {
+      // 首次启动调用 onCreate（仅一次，REGISTERED → STARTING 时调用）
+      if (isFirstStart) {
+        await scene.onCreate()
+      }
+
+      // 调用 onStart（每次 start 都调用）
+      await scene.onStart()
+
+      // 设置为运行中
+      scene._setState(SceneState.RUNNING)
+
+      // 添加到运行集合
+      this._activeScenes.add(name)
+
+      // 添加到 pixi stage
+      if (scene.stage && this._pixi && this._pixi.stage) {
+        this._pixi.stage.addChild(scene.stage)
+      }
+
+      this.emit('scene:start', { name, scene })
+    } catch (e) {
+      // 启动失败回滚状态
+      scene._setState(SceneState.STOPPED)
+      this.emit('scene:error', { name, error: e })
+      throw e
+    }
+  }
+
+  /**
+   * 停止场景
+   * @param {string} name - 场景名称
+   * @returns {Promise<void>}
+   */
+  async stop(name) {
+    const scene = this._getSceneOrThrow(name)
+
+    // 状态检查
+    if (scene.state !== SceneState.RUNNING && scene.state !== SceneState.PAUSED) {
+      throw new SceneStateError(name, scene.state, `${SceneState.RUNNING} 或 ${SceneState.PAUSED}`)
+    }
+
+    try {
+      // 调用 onStop
+      await scene.onStop()
+
+      // 设置为已停止
+      scene._setState(SceneState.STOPPED)
+
+      // 从运行集合移除
+      this._activeScenes.delete(name)
+
+      // 从 pixi stage 移除
+      if (scene.stage && this._pixi && this._pixi.stage) {
+        this._pixi.stage.removeChild(scene.stage)
+      }
+
+      this.emit('scene:stop', { name, scene })
+    } catch (e) {
+      this.emit('scene:error', { name, error: e })
+      throw e
+    }
+  }
+
+  /**
+   * 暂停场景
+   * @param {string} name - 场景名称
+   */
+  pause(name) {
+    const scene = this._getSceneOrThrow(name)
+
+    if (scene.state !== SceneState.RUNNING) {
+      throw new SceneStateError(name, scene.state, SceneState.RUNNING)
+    }
+
+    scene._setState(SceneState.PAUSED)
+    scene.onPause()
+
+    this.emit('scene:pause', { name, scene })
+  }
+
+  /**
+   * 恢复场景
+   * @param {string} name - 场景名称
+   */
+  resume(name) {
+    const scene = this._getSceneOrThrow(name)
+
+    if (scene.state !== SceneState.PAUSED) {
+      throw new SceneStateError(name, scene.state, SceneState.PAUSED)
+    }
+
+    scene._setState(SceneState.RUNNING)
+    scene.onResume()
+
+    this.emit('scene:resume', { name, scene })
+  }
+
+  // --------------------------------------------------------------------------
+  // 场景栈
+  // --------------------------------------------------------------------------
+
+  /**
+   * 入栈（启动并置于栈顶）
+   * @param {string} name - 场景名称
+   * @param {import('./Transition.js').Transition} [transition] - 过渡效果
+   * @returns {Promise<void>}
+   */
+  async push(name, transition = null) {
+    // 如果场景未注册，先注册（需用户自行注册）
+    if (!this._scenes.has(name)) {
+      throw new SceneNotFoundError(name)
+    }
+
+    // 获取栈顶场景
+    const topName = this._stack.length > 0 ? this._stack[this._stack.length - 1] : null
+    const topScene = topName ? this._scenes.get(topName) : null
+
+    // 启动目标场景
+    await this.start(name)
+
+    // 入栈
+    this._stack.push(name)
+
+    // 执行过渡效果
+    if (transition && topScene) {
+      const toScene = this._scenes.get(name)
+      await this._doTransition(topScene, toScene, transition)
+    }
+
+    this.emit('scene:push', { name, stack: [...this._stack] })
+  }
+
+  /**
+   * 出栈（停止栈顶场景）
+   * @param {import('./Transition.js').Transition} [transition] - 过渡效果
+   * @returns {Promise<void>}
+   */
+  async pop(transition = null) {
+    if (this._stack.length === 0) return
+
+    // 弹出栈顶
+    const topName = this._stack.pop()
+    const topScene = this._scenes.get(topName)
+
+    // 获取新的栈顶场景
+    const newTopName = this._stack.length > 0 ? this._stack[this._stack.length - 1] : null
+    const newTopScene = newTopName ? this._scenes.get(newTopName) : null
+
+    // 执行过渡效果
+    if (transition && newTopScene) {
+      await this._doTransition(topScene, newTopScene, transition)
+    }
+
+    // 停止栈顶场景
+    await this.stop(topName)
+
+    this.emit('scene:pop', { name: topName, stack: [...this._stack] })
+  }
+
+  // --------------------------------------------------------------------------
+  // 视觉控制
+  // --------------------------------------------------------------------------
+
+  /**
+   * 设置场景可见性
+   * @param {string} name - 场景名称
+   * @param {boolean} visible - 是否可见
+   */
+  setVisible(name, visible) {
+    const scene = this._getSceneOrThrow(name)
+    scene._isVisible = visible
+    if (scene.stage) {
+      scene.stage.visible = visible
+    }
+  }
+
+  /**
+   * 设置场景层级
+   * @param {string} name - 场景名称
+   * @param {number} zIndex - 层级值
+   */
+  setZOrder(name, zIndex) {
+    const scene = this._getSceneOrThrow(name)
+    scene._zIndex = zIndex
+    if (scene.stage) {
+      scene.stage.zIndex = zIndex
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 过渡效果
+  // --------------------------------------------------------------------------
+
+  /**
+   * 场景过渡
+   * @param {string} from - 源场景名称
+   * @param {string} to - 目标场景名称
+   * @param {import('./Transition.js').Transition} transition - 过渡效果
+   * @returns {Promise<void>}
+   */
+  async transition(from, to, transition) {
+    const fromScene = this._getSceneOrThrow(from)
+    const toScene = this._getSceneOrThrow(to)
+
+    // 确保目标场景已启动
+    if (toScene.state !== SceneState.RUNNING) {
+      await this.start(to)
+    }
+
+    await this._doTransition(fromScene, toScene, transition)
+  }
+
+  /**
+   * 带转场动画的场景切换（四期新增 1.5/3.3）
+   * 与 transition() 共存，提供更便捷的转场 API：
+   *   1. 支持字符串效果名（'fade'/'slide'/'mask'/'zoom'）
+   *   2. 支持自定义 Transition 实例
+   *   3. 自动解析当前活动场景作为源场景
+   *   4. 自动启动目标场景、停止源场景
+   *   5. 完成后自动清理转场资源
+   *
+   * @param {string} sceneName - 目标场景名称
+   * @param {string|import('./Transition.js').Transition} [effect='fade'] - 转场效果名称或实例
+   * @param {Object} [options={}] - 转场选项
+   * @param {number} [options.duration=500] - 转场持续时间（毫秒）
+   * @param {string} [options.easing='easeInOut'] - 缓动函数（linear/easeIn/easeOut/easeInOut）
+   * @param {Function} [options.onTransitionStart] - 转场开始回调 (currentScene, targetScene) => void
+   * @param {Function} [options.onTransitionEnd] - 转场结束回调 (currentScene, targetScene) => void
+   * @returns {Promise<void>}
+   * @throws {SceneNotFoundError} 目标场景未注册
+   */
+  async transitionTo(sceneName, effect = 'fade', options = {}) {
+    // 1. 获取目标场景（不存在则抛错）
+    const targetScene = this._getSceneOrThrow(sceneName)
+
+    // 2. 解析转场效果（字符串名 → Transition 实例）
+    const transition = this._resolveTransition(effect, options)
+
+    // 3. 获取当前活动场景作为源场景
+    const currentScene = this._getCurrentActiveScene()
+
+    // 4. 广播转场开始事件 + 触发开始回调
+    this.emit('scene:transition:start', {
+      from: currentScene ? currentScene.name : null,
+      to: sceneName
+    })
+    if (typeof options.onTransitionStart === 'function') {
+      try {
+        options.onTransitionStart(currentScene, targetScene)
+      } catch (e) {
+        // 用户回调异常不中断转场流程
+      }
+    }
+
+    try {
+      // 5. 启动目标场景（如果未启动）
+      if (targetScene.state !== SceneState.RUNNING) {
+        await this.start(sceneName)
+      }
+
+      // 6. 执行转场动画（直接调用 execute，避免 _doTransition 重复发射事件）
+      try {
+        await transition.execute(currentScene, targetScene)
+      } catch (e) {
+        // 转场动画异常不中断流程，记录到 scene:error 事件
+        this.emit('scene:error', { name: sceneName, error: e })
+      }
+
+      // 7. 停止源场景（如果与目标不同）
+      if (currentScene && currentScene !== targetScene) {
+        await this.stop(currentScene.name)
+      }
+    } finally {
+      // 8. 清理转场资源（如 MaskTransition 的 Graphics）
+      if (transition && typeof transition.destroy === 'function') {
+        try {
+          transition.destroy()
+        } catch (e) {
+          // 销毁异常忽略
+        }
+      }
+    }
+
+    // 9. 广播转场结束事件 + 触发结束回调
+    this.emit('scene:transition:end', {
+      from: currentScene ? currentScene.name : null,
+      to: sceneName
+    })
+    if (typeof options.onTransitionEnd === 'function') {
+      try {
+        options.onTransitionEnd(currentScene, targetScene)
+      } catch (e) {
+        // 用户回调异常不中断后续流程
+      }
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 查询方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取场景实例
+   * @param {string} name - 场景名称
+   * @returns {import('./Scene.js').Scene|null}
+   */
+  get(name) {
+    return this._scenes.get(name) || null
+  }
+
+  /**
+   * 是否注册
+   * @param {string} name - 场景名称
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._scenes.has(name)
+  }
+
+  /**
+   * 是否运行中
+   * @param {string} name - 场景名称
+   * @returns {boolean}
+   */
+  isActive(name) {
+    return this._activeScenes.has(name)
+  }
+
+  /**
+   * 列出所有场景名称
+   * @returns {string[]}
+   */
+  list() {
+    return [...this._scenes.keys()]
+  }
+
+  /**
+   * 列出运行中场景名称
+   * @returns {string[]}
+   */
+  listActive() {
+    return [...this._activeScenes]
+  }
+
+  /**
+   * 获取场景栈
+   * @returns {string[]}
+   */
+  getStack() {
+    return [...this._stack]
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期（继承自 Subsystem）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 初始化
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    await super.initialize()
+  }
+
+  /**
+   * 每帧更新（仅更新运行中且未暂停的场景）
+   * @param {number} delta - 帧间隔（秒）
+   */
+  update(delta) {
+    for (const name of this._activeScenes) {
+      const scene = this._scenes.get(name)
+      if (scene && scene.state === SceneState.RUNNING) {
+        try {
+          scene.update(delta)
+        } catch (e) {
+          this.emit('scene:error', { name, error: e })
+        }
+      }
+    }
+  }
+
+  /**
+   * 销毁所有场景
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this._isDestroyed) return
+
+    // 反向停止所有运行中的场景
+    for (const name of [...this._activeScenes]) {
+      try {
+        const scene = this._scenes.get(name)
+        if (scene) {
+          await scene.onStop()
+          scene._setState(SceneState.STOPPED)
+          if (scene.stage && this._pixi && this._pixi.stage) {
+            this._pixi.stage.removeChild(scene.stage)
+          }
+        }
+      } catch (e) {
+        // 销毁阶段错误不中断
+      }
+    }
+
+    // 销毁所有场景
+    for (const [name, scene] of this._scenes) {
+      try {
+        await scene.destroy()
+        this.emit('scene:destroyed', { name })
+      } catch (e) {
+        // 忽略销毁错误
+      }
+    }
+
+    this._scenes.clear()
+    this._activeScenes.clear()
+    this._stack = []
+    this._assetManager = null
+    this._pixi = null
+
+    await super.destroy()
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取场景实例，不存在则抛错
+   * @param {string} name - 场景名称
+   * @returns {import('./Scene.js').Scene}
+   * @throws {SceneNotFoundError}
+   * @private
+   */
+  _getSceneOrThrow(name) {
+    const scene = this._scenes.get(name)
+    if (!scene) {
+      throw new SceneNotFoundError(name)
+    }
+    return scene
+  }
+
+  /**
+   * 执行过渡效果
+   * @param {import('./Scene.js').Scene} fromScene - 源场景
+   * @param {import('./Scene.js').Scene} toScene - 目标场景
+   * @param {import('./Transition.js').Transition} transition - 过渡效果
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _doTransition(fromScene, toScene, transition) {
+    if (!transition) return
+
+    this.emit('scene:transition:start', {
+      from: fromScene ? fromScene.name : null,
+      to: toScene ? toScene.name : null
+    })
+
+    try {
+      await transition.execute(fromScene, toScene)
+    } catch (e) {
+      // 过渡错误不中断流程
+    }
+
+    this.emit('scene:transition:end', {
+      from: fromScene ? fromScene.name : null,
+      to: toScene ? toScene.name : null
+    })
+  }
+
+  /**
+   * 解析转场效果（四期新增 1.5/3.3）
+   * 支持两种输入：
+   *   1. 字符串效果名：'fade'/'slide'/'mask'/'zoom'，自动创建对应 Transition 实例
+   *   2. Transition 实例：直接返回（用户自定义转场）
+   * 未知的效果名降级到 FadeTransition
+   *
+   * @param {string|import('./Transition.js').Transition} effect - 转场效果名称或实例
+   * @param {Object} options - 转场选项（传给 Transition 构造函数）
+   * @returns {import('./Transition.js').Transition} Transition 实例
+   * @private
+   */
+  _resolveTransition(effect, options) {
+    // 字符串效果名：根据映射创建实例
+    if (typeof effect === 'string') {
+      switch (effect) {
+        case 'fade':
+          return new FadeTransition(options)
+        case 'slide':
+          return new SlideTransition(options)
+        case 'mask':
+          return new MaskTransition(options)
+        case 'zoom':
+          return new ZoomTransition(options)
+        default:
+          // 未知效果名降级到 FadeTransition（最通用）
+          return new FadeTransition(options)
+      }
+    }
+    // 非字符串：假设是 Transition 实例，直接返回
+    return effect
+  }
+
+  /**
+   * 获取当前活动场景（四期新增 1.5/3.3）
+   * 遍历 _activeScenes，返回第一个 RUNNING 状态的场景
+   * 用于 transitionTo() 自动解析源场景
+   *
+   * @returns {import('./Scene.js').Scene|null} 当前活动场景，无则返回 null
+   * @private
+   */
+  _getCurrentActiveScene() {
+    for (const name of this._activeScenes) {
+      const scene = this._scenes.get(name)
+      if (scene && scene.state === SceneState.RUNNING) {
+        return scene
+      }
+    }
+    return null
+  }
+}
+
+export { SceneManager }

package/src/core/SceneManager/SceneState.js

@@ -0,0 +1,29 @@
+// ============================================================================
+// Nimbus2D - 场景状态枚举
+// ----------------------------------------------------------------------------
+// 定义场景的所有合法状态。
+//
+// 状态转换流程：
+//   无 → REGISTERED → STARTING → RUNNING ⇄ PAUSED → STOPPED → DESTROYED
+// ============================================================================
+
+/**
+ * 场景状态枚举
+ * @enum {string}
+ */
+const SceneState = {
+  /** 已注册（SceneManager.register 后） */
+  REGISTERED: 'REGISTERED',
+  /** 启动中 */
+  STARTING: 'STARTING',
+  /** 运行中 */
+  RUNNING: 'RUNNING',
+  /** 已暂停 */
+  PAUSED: 'PAUSED',
+  /** 已停止（可重新 start） */
+  STOPPED: 'STOPPED',
+  /** 已销毁（不可恢复） */
+  DESTROYED: 'DESTROYED'
+}
+
+export { SceneState }