@nimbus2d/core 0.0.1

package/src/core/Application/Application.js

@@ -0,0 +1,480 @@
+// ============================================================================
+// Nimbus2D - Application 启动器
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 直接包含 PixiJS Application（v8 异步初始化）
+//   2. 分层配置 + 合理默认值
+//   3. async start() + async stop()
+//   4. 提供 use(plugin, options) 注册插件（委托 PluginSystem.register，链式返回 Application）
+//   5. 提供 onError(callback) 全局错误处理（封装 EventBus.on('error')）
+//
+// 继承关系：
+//   EventEmitter → Application（启动器，包含所有核心模块，不被 Lifecycle 调度）
+// ============================================================================
+
+// 导入 unsafe-eval polyfill（PixiJS v8 官方推荐）
+// 在 CSP 限制环境（如 Electron）中，PixiJS 的 WebGL 着色器编译需要 eval()
+// 此 polyfill 使用预编译着色器替代运行时编译，无需在 CSP 中放开 unsafe-eval
+// 必须在 import { Application } from 'pixi.js' 之前导入
+import 'pixi.js/unsafe-eval'
+import { Application as PixiApplication } from 'pixi.js'
+import { EventEmitter } from '../../base/EventEmitter.js'
+import { AppState } from './AppState.js'
+import { DefaultConfig } from './DefaultConfig.js'
+import { ConfigSystem } from '../ConfigSystem/ConfigSystem.js'
+import { ConfigLayerType } from '../ConfigSystem/ConfigLayerType.js'
+import { EventBus } from '../EventBus/EventBus.js'
+import { Logger } from '../Logger/Logger.js'
+import { Lifecycle } from '../Lifecycle/Lifecycle.js'
+import { AssetManager } from '../AssetManager/AssetManager.js'
+import { SceneManager } from '../SceneManager/SceneManager.js'
+import { PoolManager } from '../PoolManager/PoolManager.js'
+import { PluginSystem } from '../PluginSystem/PluginSystem.js'
+import { MemoryChecker } from '../../utils/MemoryChecker.js'
+
+class Application extends EventEmitter {
+  /**
+   * 构造函数
+   * 仅保存用户配置，不创建任何子系统实例
+   * @param {Object} [config={}] - 用户配置（合并到 USER 配置层）
+   * @param {import('../SceneManager/Scene.js').Scene} [initialScene=null] - 初始场景
+   */
+  constructor(config = {}, initialScene = null) {
+    super()
+
+    /** @type {AppState} 应用当前状态 */
+    this._state = AppState.CREATED
+
+    /** @type {import('../SceneManager/Scene.js').Scene|null} 初始场景 */
+    this._initialScene = initialScene
+
+    /** @type {Object} 用户初始配置 */
+    this._initialConfig = config
+
+    // 仅保存配置，所有引用 = null，实例在 start() 中创建
+    /** @type {import('pixi.js').Application|null} PixiJS 应用实例 */
+    this._pixi = null
+
+    /** @type {ConfigSystem|null} 配置系统 */
+    this._config = null
+
+    /** @type {EventBus|null} 事件总线 */
+    this._eventBus = null
+
+    /** @type {Lifecycle|null} 生命周期管理 */
+    this._lifecycle = null
+
+    /** @type {Logger|null} 日志系统 */
+    this._logger = null
+
+    /** @type {AssetManager|null} 资源管理 */
+    this._assetManager = null
+
+    /** @type {SceneManager|null} 场景管理 */
+    this._sceneManager = null
+
+    /** @type {import('../PoolManager/PoolManager.js').PoolManager|null} 对象池管理 */
+    this._poolManager = null
+
+    /** @type {import('../../utils/MemoryChecker.js').MemoryChecker|null} 内存泄漏检测 */
+    this._memoryChecker = null
+
+    /** @type {PluginSystem|null} 插件管理 */
+    this._pluginSystem = null
+
+    // === 画布尺寸变化检测（四期新增 1.5：app:resize 事件机制）===
+    // 用于检测 PixiJS resizeTo 触发的画布尺寸变化，并广播 app:resize 事件
+    // 让 Camera 等组件能感知画布尺寸变化并同步更新视口尺寸
+    /** @type {number} 上一帧的画布宽度（像素，pixi.screen.width） */
+    this._lastScreenWidth = 0
+    /** @type {number} 上一帧的画布高度（像素，pixi.screen.height） */
+    this._lastScreenHeight = 0
+  }
+
+  // --------------------------------------------------------------------------
+  // 状态相关
+  // --------------------------------------------------------------------------
+
+  /** @type {AppState} 应用当前状态 */
+  get state() { return this._state }
+
+  // --------------------------------------------------------------------------
+  // 核心模块访问器
+  // --------------------------------------------------------------------------
+
+  /** @type {import('pixi.js').Application|null} PixiJS Application 实例 */
+  get pixi() { return this._pixi }
+
+  /** @type {import('pixi.js').Container|null} PixiJS 根舞台（pixi.stage 别名） */
+  get stage() { return this._pixi ? this._pixi.stage : null }
+
+  /** @type {import('pixi.js').Renderer|null} PixiJS 渲染器（pixi.renderer 别名） */
+  get renderer() { return this._pixi ? this._pixi.renderer : null }
+
+  /** @type {ConfigSystem|null} 配置系统实例 */
+  get config() { return this._config }
+
+  /** @type {EventBus|null} EventBus 实例 */
+  get eventBus() { return this._eventBus }
+
+  /** @type {Lifecycle|null} Lifecycle 实例 */
+  get lifecycle() { return this._lifecycle }
+
+  /** @type {Logger|null} Logger 实例 */
+  get logger() { return this._logger }
+
+  /** @type {AssetManager|null} AssetManager 实例 */
+  get assetManager() { return this._assetManager }
+
+  /** @type {SceneManager|null} SceneManager 实例 */
+  get sceneManager() { return this._sceneManager }
+
+  /** @type {import('../PoolManager/PoolManager.js').PoolManager|null} PoolManager 实例 */
+  get poolManager() { return this._poolManager }
+
+  /** @type {import('../../utils/MemoryChecker.js').MemoryChecker|null} MemoryChecker 实例 */
+  get memoryChecker() { return this._memoryChecker }
+
+  /** @type {PluginSystem|null} PluginSystem 实例 */
+  get pluginSystem() { return this._pluginSystem }
+
+  // --------------------------------------------------------------------------
+  // 生命周期方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 异步启动应用
+   * 按依赖顺序创建和初始化所有核心模块
+   * @returns {Promise<Application>} - 启动完成后返回 this（链式调用）
+   * @throws {Error} 启动失败时抛出
+   */
+  async start() {
+    if (this._state !== AppState.CREATED) {
+      throw new Error(`Application 已启动或已销毁，当前状态：${this._state}`)
+    }
+    this._state = AppState.STARTING
+
+    // 0. WebGPU 检测与渲染器偏好配置（四期新增 1.2）
+    //    在 PixiJS init 之前决定 preference，确保 PixiJS 使用正确的后端
+    const rendererConfig = this._initialConfig.renderer || {}
+    const preferWebGPU = rendererConfig.preferWebGPU === true
+    const webgpuFallback = rendererConfig.webgpu?.fallback !== false // 默认 true
+    const webgpuDetected = this._detectWebGPU()
+
+    /** @type {'webgl'|'webgpu'} PixiJS 渲染器偏好 */
+    let preference = 'webgl' // 默认 WebGL，保证最大兼容性
+    if (preferWebGPU) {
+      if (webgpuDetected) {
+        preference = 'webgpu'
+      } else if (!webgpuFallback) {
+        // 不支持 WebGPU 且未启用回退 → 抛错阻止启动
+        throw new Error('WebGPU 不被当前浏览器支持，且 renderer.webgpu.fallback=false 已禁用回退')
+      }
+      // fallback=true 时，preference 保持 'webgl'，由 PixiJS 使用 WebGL
+    }
+
+    // 1. 创建并初始化 PixiJS Application（v8 两步异步初始化：new + await init）
+    //    最早创建，后续模块构造需要 pixi 引用
+    //    preference 合并策略：
+    //      - preferWebGPU=true：由 renderer 配置决定 preference，覆盖用户 pixi.preference
+    //        （renderer.preferWebGPU 优先级最高，确保 WebGPU 检测逻辑生效）
+    //      - preferWebGPU=false：不覆盖用户 pixi.preference，尊重用户显式配置
+    //        （用户可通过 pixi.preference 直接控制后端，向后兼容）
+    this._pixi = new PixiApplication()
+    const pixiConfig = { ...this._initialConfig.pixi }
+    if (preferWebGPU) {
+      pixiConfig.preference = preference
+    }
+    await this._pixi.init(pixiConfig)
+
+    // 2. 创建所有核心模块实例（按依赖顺序，构造阶段不初始化）
+    // 注意：Logger 必须在 Lifecycle 之前创建，因为 Lifecycle 构造函数需要 logger 引用
+    this._config = new ConfigSystem()
+    this._eventBus = new EventBus()
+    this._logger = new Logger(this._eventBus, this._config)
+    this._lifecycle = new Lifecycle(this._eventBus, this._logger)
+    this._assetManager = new AssetManager(this._eventBus, this._config, this._logger, this._pixi)
+    this._sceneManager = new SceneManager(this._eventBus, this._config, this._logger, this._assetManager, this._pixi)
+    this._poolManager = new PoolManager(this._eventBus, this._config, this._logger)
+    this._pluginSystem = new PluginSystem(this._eventBus, this._config, this._logger, this)
+
+    // MemoryChecker 不注册到 Lifecycle（是工具类，不是子系统）
+    // 在 Lifecycle 初始化后创建，以便自动挂钩已初始化的 PoolManager/AssetManager
+
+    // 3. 初始化基础设施模块（ConfigSystem 必须先初始化，创建 4 层配置，才能加载配置）
+    await this._config.initialize()
+    await this._eventBus.initialize()
+
+    // 4. 加载默认配置 + 用户配置（初始化后才能写入配置层）
+    // DefaultConfig 写入 DEFAULT 层（代码内置默认值，freezable=true）
+    this._config.loadJSON(DefaultConfig, ConfigLayerType.DEFAULT)
+    // 用户配置写入 USER 层（构造参数传入，可覆盖 DEFAULT）
+    this._config.loadJSON(this._initialConfig, ConfigLayerType.USER)
+
+    // 5. 注册子系统到 Lifecycle（注册顺序决定初始化顺序）
+    //    PoolManager 在 PluginSystem 之前初始化，确保插件安装时池管理器已就绪
+    this._lifecycle.registerSubsystem(this._logger)
+    this._lifecycle.registerSubsystem(this._assetManager)
+    this._lifecycle.registerSubsystem(this._sceneManager)
+    this._lifecycle.registerSubsystem(this._poolManager)
+    this._lifecycle.registerSubsystem(this._pluginSystem)
+
+    // 6. 初始化 Lifecycle（内部按顺序初始化所有子系统）
+    await this._lifecycle.initialize()
+
+    // 7. 激活 Lifecycle（关键步骤：使 update() 生效）
+    this._lifecycle.activate()
+
+    // 8. 创建 MemoryChecker（在 Lifecycle 初始化后，以便挂钩已初始化的子系统）
+    //    MemoryChecker 是工具类，不注册到 Lifecycle，由 Application 直接管理
+    this._memoryChecker = new MemoryChecker(this._eventBus, this._config, this._logger)
+
+    // 开发模式自动挂钩 PoolManager/AssetManager
+    if (this._config.get('core.developmentMode') !== false) {
+      this._memoryChecker.hookPoolManager(this._poolManager)
+      this._memoryChecker.hookAssetManager(this._assetManager)
+      this._logger.info('Application.start', '开发模式：MemoryChecker 已自动挂钩 PoolManager/AssetManager')
+    }
+
+    // 9. 启动初始场景（如有）
+    if (this._initialScene) {
+      await this._sceneManager.register(this._initialScene)
+      await this._sceneManager.start(this._initialScene.name)
+    }
+
+    // 10. 添加 Lifecycle.update 到 PixiJS ticker
+    //     同时检测画布尺寸变化（PixiJS resizeTo 触发后，pixi.screen.width/height 会变化）
+    //     每帧轮询检测，性能开销可忽略（仅两次数值比较）
+    this._lastScreenWidth = this._pixi.screen.width
+    this._lastScreenHeight = this._pixi.screen.height
+    this._pixi.ticker.add((ticker) => {
+      const deltaSec = ticker.deltaMS / 1000
+      this._lifecycle.update(deltaSec)
+      // 检测画布尺寸变化并广播 app:resize 事件
+      this._checkResize()
+    })
+
+    // 11. 广播渲染器后端事件（四期新增 1.2）
+    //     在所有模块初始化完成后广播，确保订阅者能正常接收
+    this._eventBus.emit('renderer:backend', {
+      /** 实际使用的后端（基于 PixiJS renderer 实例检测） */
+      backend: this._detectRendererBackend(),
+      /** 用户配置的偏好 */
+      preference,
+      /** 是否优先 WebGPU（用户配置） */
+      preferWebGPU,
+      /** 浏览器是否支持 WebGPU（环境检测） */
+      webgpuDetected
+    })
+
+    // 12. 完成启动
+    this._state = AppState.RUNNING
+    this.emit('ready', this)
+    return this
+  }
+
+  /**
+   * 异步停止应用（销毁所有资源）
+   * 销毁阶段错误不抛出，仅记录到 Logger
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    if (this._state === AppState.DESTROYED) return
+    this._state = AppState.STOPPING
+
+    try {
+      // 1. 停止 PixiJS ticker
+      if (this._pixi) this._pixi.ticker.stop()
+
+      // 2-9. 反向销毁所有模块（错误不中断流程）
+      //    销毁顺序：MemoryChecker → PluginSystem → PoolManager → SceneManager → AssetManager → Logger
+      //    MemoryChecker 最先销毁（它只是工具类，仅持有引用，不管理资源）
+      await this._safeDestroy(this._memoryChecker)
+      await this._safeDestroy(this._pluginSystem)
+      await this._safeDestroy(this._poolManager)
+      await this._safeDestroy(this._sceneManager)
+      await this._safeDestroy(this._assetManager)
+      await this._safeDestroy(this._logger)
+      await this._safeDestroy(this._lifecycle)
+      await this._safeDestroy(this._eventBus)
+      await this._safeDestroy(this._config)
+
+      // 9. 销毁 PixiJS Application（v8 签名：destroy(rendererOptions, stageOptions)）
+      if (this._pixi) {
+        try {
+          this._pixi.destroy(
+            { removeView: true, releaseGlobalResources: true },
+            { children: true, texture: true, textureSource: true }
+          )
+        } catch (e) { /* 忽略 */ }
+      }
+    } finally {
+      this._state = AppState.DESTROYED
+      this.emit('destroyed')
+      this.removeAllListeners()
+    }
+  }
+
+  /**
+   * 注册插件（链式调用）
+   * 委托给 pluginSystem.register(plugin, options)，链式返回 Application 实例
+   * @param {import('../PluginSystem/Plugin.js').Plugin} plugin - 插件实例
+   * @param {Object} [options={}] - 插件配置
+   * @returns {Promise<Application>} - 返回 Promise 支持异步等待安装完成
+   */
+  async use(plugin, options = {}) {
+    if (this._pluginSystem) {
+      await this._pluginSystem.register(plugin, options)
+    }
+    return this
+  }
+
+  /**
+   * 注册全局错误回调
+   * 内部封装 EventBus.on('error')，自动解构 payload
+   * @param {Function} callback - 错误回调 (error: Error, source?: string) => void
+   * @returns {Function} - 取消注册函数
+   */
+  onError(callback) {
+    if (!this._eventBus) return () => {}
+    return this._eventBus.on('error', (payload) => {
+      callback(payload.error, payload.source)
+    })
+  }
+
+  /**
+   * 静态工厂方法
+   * @param {Object} [config={}] - 配置
+   * @param {import('../SceneManager/Scene.js').Scene} [initialScene=null] - 初始场景
+   * @returns {Promise<Application>} - 启动后的 Application 实例
+   */
+  static async create(config = {}, initialScene = null) {
+    const app = new Application(config, initialScene)
+    await app.start()
+    return app
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 安全销毁模块（销毁阶段错误不中断流程）
+   * @param {object} module - 模块实例
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _safeDestroy(module) {
+    if (!module) return
+    try {
+      if (typeof module.destroy === 'function') {
+        await module.destroy()
+      }
+    } catch (e) {
+      // 销毁阶段错误不抛出，尝试记录到 Logger（若可用）
+      try {
+        if (this._logger && this._logger.isDestroyed !== true) {
+          this._logger.error('Application.stop', e)
+        }
+      } catch (logErr) { /* 忽略 */ }
+    }
+  }
+
+  /**
+   * 检测浏览器是否支持 WebGPU（四期新增 1.2）
+   * 通过 navigator.gpu 是否存在判断 WebGPU 支持
+   *
+   * @returns {boolean} true 表示支持 WebGPU
+   * @private
+   */
+  _detectWebGPU() {
+    // navigator.gpu 是 WebGPU API 的入口点
+    // 在不支持 WebGPU 的浏览器（如 Safari < 16.4、Firefox 未启用）中为 undefined
+    // 注意：navigator.gpu 存在不代表一定能正常工作，但作为快速检测足够
+    return typeof navigator !== 'undefined' && !!navigator.gpu
+  }
+
+  /**
+   * 检测 PixiJS 实际使用的渲染器后端（四期新增 1.2）
+   * 通过 PixiJS renderer 实例的 type 字段判断
+   *
+   * @returns {'webgl'|'webgpu'|'unknown'} 实际使用的后端
+   * @private
+   */
+  _detectRendererBackend() {
+    if (!this._pixi || !this._pixi.renderer) return 'unknown'
+    // PixiJS v8 中 WebGLRenderer.type === 'webgl'，WebGPURenderer.type === 'webgpu'
+    // 通过实例的 type 字段判断（PixiJS v8 推荐 API）
+    const rendererType = this._pixi.renderer.type
+    if (rendererType === 'webgpu') return 'webgpu'
+    if (rendererType === 'webgl') return 'webgl'
+    return 'unknown'
+  }
+
+  /**
+   * 检测画布尺寸变化并广播 app:resize 事件（四期新增 1.5）
+   *
+   * 工作原理：
+   *   - PixiJS 的 ResizePlugin 在 window resize 时自动调用 renderer.resize()
+   *   - renderer.resize() 会更新 pixi.screen.width/height
+   *   - 本方法每帧轮询 pixi.screen 的尺寸，对比上一帧的值
+   *   - 若尺寸变化，通过 EventBus 广播 'app:resize' 事件
+   *
+   * 事件负载（payload）：
+   *   - width: number        新画布宽度（像素）
+   *   - height: number       新画布高度（像素）
+   *   - prevWidth: number    上一帧画布宽度（像素）
+   *   - prevHeight: number   上一帧画布高度（像素）
+   *
+   * 监听示例：
+   *   app.eventBus.on('app:resize', ({ width, height }) => {
+   *     camera.setSize(width, height)
+   *   })
+   *
+   * 性能考虑：
+   *   - 每帧仅执行两次数值比较，开销可忽略
+   *   - 仅在尺寸变化时才触发事件分发
+   *
+   * @private
+   */
+  _checkResize() {
+    // 防御性检查：pixi 或 eventBus 可能已销毁
+    // 注意：EventBus 内部 emit() 已有 destroyed 检查，此处仅检查引用是否存在
+    if (!this._pixi || !this._eventBus) return
+
+    const screen = this._pixi.screen
+    // 快速比较：尺寸未变化时直接返回（每帧命中）
+    if (screen.width === this._lastScreenWidth && screen.height === this._lastScreenHeight) {
+      return
+    }
+
+    // 尺寸变化：缓存旧值，更新当前值
+    const prevWidth = this._lastScreenWidth
+    const prevHeight = this._lastScreenHeight
+    this._lastScreenWidth = screen.width
+    this._lastScreenHeight = screen.height
+
+    // 广播 app:resize 事件，让 Camera 等订阅者同步更新视口尺寸
+    this._eventBus.emit('app:resize', {
+      /** 新画布宽度（像素） */
+      width: screen.width,
+      /** 新画布高度（像素） */
+      height: screen.height,
+      /** 上一帧画布宽度（像素，便于订阅者计算变化量） */
+      prevWidth,
+      /** 上一帧画布高度（像素，便于订阅者计算变化量） */
+      prevHeight
+    })
+
+    // 同时通过 EventEmitter 触发本地 'resize' 事件（不依赖 EventBus 的监听者）
+    // 允许通过 app.on('resize', cb) 直接订阅
+    this.emit('resize', {
+      width: screen.width,
+      height: screen.height,
+      prevWidth,
+      prevHeight
+    })
+  }
+}
+
+export { Application }

package/src/core/Application/DefaultConfig.js

@@ -0,0 +1,63 @@
+// ============================================================================
+// Nimbus2D - 默认配置
+// ----------------------------------------------------------------------------
+// Application 的默认配置，写入 ConfigSystem 的 DEFAULT 层（freezable=true）。
+// ============================================================================
+
+/**
+ * 默认配置对象
+ * @type {Object}
+ */
+const DefaultConfig = {
+  /** PixiJS 相关配置 */
+  pixi: {
+    /** 画布宽度 */
+    width: 800,
+    /** 画布高度 */
+    height: 600,
+    /** 背景颜色（十六进制） */
+    backgroundColor: 0x000000,
+    /** 是否抗锯齿 */
+    antialias: true,
+    /** 是否启用 alpha 通道 */
+    alpha: false,
+    /** 分辨率（0 表示自动检测） */
+    resolution: 0
+  },
+
+  /** 渲染器配置（四期新增 1.2：WebGPU 适配器） */
+  renderer: {
+    /**
+     * 是否优先使用 WebGPU 后端
+     * - true: 优先尝试 WebGPU，不支持时根据 webgpu.fallback 决定回退策略
+     * - false: 直接使用 WebGL（默认值，保证最大兼容性）
+     */
+    preferWebGPU: false,
+    /** WebGPU 相关子配置 */
+    webgpu: {
+      /**
+       * 不支持 WebGPU 时是否自动回退到 WebGL
+       * - true: 自动回退（默认值，保证启动成功）
+       * - false: 抛出错误，阻止启动（适用于必须使用 WebGPU 的场景）
+       */
+      fallback: true
+    }
+  },
+
+  /** 核心配置 */
+  core: {
+    /** 是否启用开发模式（开发模式增强参数校验、状态守卫、内存检测） */
+    developmentMode: true
+  },
+
+  /** 模块配置 */
+  modules: {
+    /** 日志系统配置 */
+    logger: {
+      /** 日志级别：0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=NONE */
+      level: 1
+    }
+  }
+}
+
+export { DefaultConfig }

package/src/core/Application/index.js

@@ -0,0 +1,7 @@
+// ============================================================================
+// Nimbus2D - Application 模块统一导出
+// ============================================================================
+
+export { Application } from './Application.js'
+export { AppState } from './AppState.js'
+export { DefaultConfig } from './DefaultConfig.js'