@nimbus2d/core 0.0.1

package/src/core/PluginSystem/PluginSystem.js

@@ -0,0 +1,530 @@
+// ============================================================================
+// Nimbus2D - PluginSystem 插件管理
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 强制继承 Plugin 类
+//   2. install/uninstall 两阶段生命周期
+//   3. 静态依赖声明 + 拓扑排序安装
+//   4. 完整插件状态机：REGISTERED → INSTALLING → INSTALLED → UNINSTALLING → UNREGISTERED / ERROR
+//   5. 错误隔离（单个插件失败不影响其他插件）
+//   6. 生命周期钩子（三期新增）：beforeInstall/afterInstall/beforeUninstall/afterUninstall
+//      双模式：插件定义钩子方法 + 事件广播 + onHook 外部订阅
+//
+// 继承关系：
+//   EventEmitter → Subsystem → PluginSystem（Lifecycle 内第四个/最后初始化）
+// ============================================================================
+
+import { Subsystem } from '../../base/Subsystem.js'
+import { Plugin } from './Plugin.js'
+import { PluginEntry } from './PluginEntry.js'
+import { PluginState } from './PluginState.js'
+import {
+  PluginNotFoundError,
+  PluginDuplicateError,
+  PluginDependencyError,
+  PluginStateError,
+  PluginError
+} from '../../errors/PluginError.js'
+
+class PluginSystem extends Subsystem {
+  /**
+   * 构造函数
+   * @param {import('../EventBus/EventBus.js').EventBus} eventBus - 全局事件总线
+   * @param {import('../ConfigSystem/ConfigSystem.js').ConfigSystem} config - 配置系统
+   * @param {import('../Logger/Logger.js').Logger} logger - 日志系统
+   * @param {object} app - Application 实例（传给 plugin.install）
+   */
+  constructor(eventBus, config, logger, app) {
+    super(eventBus, config, logger)
+
+    /** @type {object} Application 实例 */
+    this._app = app
+
+    /** @type {Map<string, PluginEntry>} 插件映射（name → entry） */
+    this._entries = new Map()
+
+    /**
+     * 钩子监听器映射（三期新增）
+     * hookName → Set<Function>，支持外部订阅插件生命周期钩子
+     * @type {Map<string, Set<Function>>}
+     */
+    this._hookListeners = null
+  }
+
+  // --------------------------------------------------------------------------
+  // 插件管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注册插件
+   * 如果 PluginSystem 已初始化，则自动安装并等待安装完成
+   * @param {Plugin} plugin - 插件实例
+   * @param {Object} [options={}] - 插件配置
+   * @returns {Promise<PluginSystem>} - 返回 Promise 支持异步等待安装完成
+   * @throws {PluginDuplicateError} 插件重复注册
+   */
+  async register(plugin, options = {}) {
+    // 检查是否为 Plugin 实例
+    if (!Plugin.isPlugin(plugin)) {
+      throw new Error('插件必须继承 Plugin 类')
+    }
+
+    const name = plugin.name
+
+    // 检查重复
+    if (this._entries.has(name)) {
+      throw new PluginDuplicateError(name)
+    }
+
+    // 创建条目并存储
+    const entry = new PluginEntry(plugin, options)
+    this._entries.set(name, entry)
+
+    this.emit('plugin:registered', { name, plugin })
+
+    // 如果 PluginSystem 已初始化（应用已启动），等待安装完成
+    if (this._isInitialized) {
+      await this.install(name)
+    }
+
+    return this
+  }
+
+  /**
+   * 注销插件（已安装则先卸载）
+   * @param {string} name - 插件名称
+   * @returns {Promise<void>}
+   */
+  async unregister(name) {
+    const entry = this._getEntryOrThrow(name)
+
+    // 已安装则先卸载
+    if (entry.state === PluginState.INSTALLED) {
+      await this.uninstall(name)
+    }
+
+    // 设置为已注销
+    entry.setState(PluginState.UNREGISTERED)
+
+    // 从映射移除
+    this._entries.delete(name)
+
+    this.emit('plugin:unregistered', { name })
+  }
+
+  /**
+   * 安装单个插件
+   * 执行流程：beforeInstall 钩子 → 安装逻辑 → afterInstall 钩子
+   * @param {string} name - 插件名称
+   * @returns {Promise<void>}
+   */
+  async install(name) {
+    const entry = this._getEntryOrThrow(name)
+
+    // 状态检查
+    if (entry.state !== PluginState.REGISTERED) {
+      throw new PluginStateError(name, entry.state, PluginState.REGISTERED)
+    }
+
+    // 检查依赖是否已安装
+    for (const dep of entry.dependencies) {
+      const depEntry = this._entries.get(dep)
+      if (!depEntry || depEntry.state !== PluginState.INSTALLED) {
+        throw new PluginDependencyError(name, `依赖插件 ${dep} 未安装`)
+      }
+    }
+
+    // 1. 执行 beforeInstall 钩子（在状态变更前）
+    await this._executeHook('beforeInstall', {
+      name: entry.name,
+      plugin: entry.plugin,
+      options: entry.options
+    })
+
+    // 2. 设置为安装中
+    entry.setState(PluginState.INSTALLING)
+    this.emit('plugin:installing', { name: entry.name, plugin: entry.plugin })
+
+    try {
+      // 调用插件的 install 方法
+      await entry.plugin.install(this._app, entry.options)
+
+      // 标记为已安装
+      entry.markInstalled()
+
+      this.emit('plugin:installed', { name: entry.name, plugin: entry.plugin })
+    } catch (e) {
+      // 安装失败设为 ERROR 状态
+      entry.setState(PluginState.ERROR)
+      this.emit('plugin:error', { name: entry.name, error: e })
+      throw e
+    }
+
+    // 3. 执行 afterInstall 钩子（安装成功后）
+    await this._executeHook('afterInstall', {
+      name: entry.name,
+      plugin: entry.plugin,
+      options: entry.options
+    })
+  }
+
+  /**
+   * 卸载单个插件
+   * 执行流程：beforeUninstall 钩子 → 卸载逻辑 → afterUninstall 钩子
+   * @param {string} name - 插件名称
+   * @returns {Promise<void>}
+   */
+  async uninstall(name) {
+    const entry = this._getEntryOrThrow(name)
+
+    // 状态检查
+    if (entry.state !== PluginState.INSTALLED) {
+      throw new PluginStateError(name, entry.state, PluginState.INSTALLED)
+    }
+
+    // 1. 执行 beforeUninstall 钩子（在状态变更前）
+    //    传递完整 context（包含 app），供钩子方法访问应用实例
+    await this._executeHook('beforeUninstall', {
+      name: entry.name,
+      plugin: entry.plugin,
+      app: this._app
+    })
+
+    // 2. 设置为卸载中
+    entry.setState(PluginState.UNINSTALLING)
+    this.emit('plugin:uninstalling', { name: entry.name, plugin: entry.plugin })
+
+    try {
+      // 调用插件的 uninstall 方法
+      await entry.plugin.uninstall(this._app)
+
+      // 设置为已注册（可重新安装），通过公共方法重置安装时间戳
+      entry.setState(PluginState.REGISTERED)
+      entry.resetInstallTime()
+
+      this.emit('plugin:uninstalled', { name: entry.name, plugin: entry.plugin })
+    } catch (e) {
+      // 卸载失败设为 ERROR 状态
+      entry.setState(PluginState.ERROR)
+      this.emit('plugin:error', { name: entry.name, error: e })
+      throw e
+    }
+
+    // 3. 执行 afterUninstall 钩子（卸载成功后）
+    //    传递完整 context（包含 app），供钩子方法访问应用实例
+    await this._executeHook('afterUninstall', {
+      name: entry.name,
+      plugin: entry.plugin,
+      app: this._app
+    })
+  }
+
+  // --------------------------------------------------------------------------
+  // 查询方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取插件实例
+   * @param {string} name - 插件名称
+   * @returns {Plugin|null}
+   */
+  get(name) {
+    const entry = this._entries.get(name)
+    return entry ? entry.plugin : null
+  }
+
+  /**
+   * 是否已注册
+   * @param {string} name - 插件名称
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._entries.has(name)
+  }
+
+  /**
+   * 是否已安装
+   * @param {string} name - 插件名称
+   * @returns {boolean}
+   */
+  isInstalled(name) {
+    const entry = this._entries.get(name)
+    return entry ? entry.state === PluginState.INSTALLED : false
+  }
+
+  /**
+   * 列出所有插件名称
+   * @returns {string[]}
+   */
+  list() {
+    return [...this._entries.keys()]
+  }
+
+  /**
+   * 列出已安装插件名称
+   * @returns {string[]}
+   */
+  listInstalled() {
+    const result = []
+    for (const [name, entry] of this._entries) {
+      if (entry.state === PluginState.INSTALLED) {
+        result.push(name)
+      }
+    }
+    return result
+  }
+
+  // --------------------------------------------------------------------------
+  // 钩子（三期新增）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 订阅插件生命周期钩子
+   * 钩子执行时，onHook 订阅者会在插件定义的钩子方法和事件广播之后被调用
+   *
+   * @param {string} hookName - 钩子名称
+   *        可选值：'beforeInstall'/'afterInstall'/'beforeUninstall'/'afterUninstall'
+   * @param {Function} callback - 回调函数 ({ name, plugin, options? }) => void
+   * @returns {Function} - 取消订阅函数
+   * @throws {PluginError} 无效的钩子名称或 callback 不是函数
+   */
+  onHook(hookName, callback) {
+    // 已销毁检查
+    if (this.isDestroyed) return () => {}
+
+    // 未初始化检查（_hookListeners 在 initialize() 中创建）
+    if (!this._hookListeners) {
+      console.warn('[PluginSystem] onHook() 在初始化前调用，已忽略')
+      return () => {}
+    }
+
+    // 参数校验
+    const validHooks = ['beforeInstall', 'afterInstall', 'beforeUninstall', 'afterUninstall']
+    if (!validHooks.includes(hookName)) {
+      throw new PluginError(`无效的钩子名称: '${hookName}'，可选值: ${validHooks.join(', ')}`)
+    }
+    if (typeof callback !== 'function') {
+      throw new PluginError('callback 必须是函数')
+    }
+
+    if (!this._hookListeners.has(hookName)) {
+      this._hookListeners.set(hookName, new Set())
+    }
+    this._hookListeners.get(hookName).add(callback)
+
+    // 返回取消订阅函数
+    return () => {
+      const listeners = this._hookListeners.get(hookName)
+      if (listeners) {
+        listeners.delete(callback)
+      }
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期（继承自 Subsystem）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 初始化：拓扑排序后按顺序安装所有 REGISTERED 插件
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    await super.initialize()
+
+    // 初始化钩子监听器映射
+    this._hookListeners = new Map()
+
+    // 拓扑排序
+    const sorted = this._topologicalSort()
+
+    // 按排序顺序安装所有 REGISTERED 插件
+    for (const name of sorted) {
+      const entry = this._entries.get(name)
+      if (entry && entry.state === PluginState.REGISTERED) {
+        try {
+          await this.install(name)
+        } catch (e) {
+          // 单个插件安装失败不影响其他插件
+          this._safeLog('error', `插件 ${name} 安装失败`, { error: e })
+        }
+      }
+    }
+  }
+
+  /**
+   * 调用所有已安装插件的 update
+   * @param {number} delta - 帧间隔（秒）
+   */
+  update(delta) {
+    for (const [name, entry] of this._entries) {
+      if (entry.state === PluginState.INSTALLED) {
+        try {
+          entry.plugin.update(delta, this._app)
+        } catch (e) {
+          this.emit('plugin:error', { name, error: e })
+        }
+      }
+    }
+  }
+
+  /**
+   * 反向卸载所有已安装插件，清理钩子监听器
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this._isDestroyed) return
+
+    // 反向卸载所有已安装插件
+    const installedNames = this.listInstalled().reverse()
+    for (const name of installedNames) {
+      try {
+        await this.uninstall(name)
+      } catch (e) {
+        // 销毁阶段错误不中断
+        this._safeLog('error', `插件 ${name} 卸载失败`, { error: e })
+      }
+    }
+
+    // 清理钩子监听器
+    if (this._hookListeners) {
+      for (const listeners of this._hookListeners.values()) {
+        listeners.clear()
+      }
+      this._hookListeners.clear()
+    }
+    this._hookListeners = null
+
+    this._entries.clear()
+    this._app = null
+
+    await super.destroy()
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 拓扑排序
+   * @returns {string[]} 安装顺序
+   * @throws {PluginDependencyError} 检测到循环依赖
+   * @private
+   */
+  _topologicalSort() {
+    const sorted = []
+    const visited = new Set()
+    const visiting = new Set()
+
+    const visit = (name) => {
+      if (visited.has(name)) return
+      if (visiting.has(name)) {
+        throw new PluginDependencyError(name, `检测到循环依赖：${name}`)
+      }
+      visiting.add(name)
+
+      const entry = this._entries.get(name)
+      if (!entry) {
+        throw new PluginNotFoundError(name)
+      }
+
+      // 先安装依赖
+      const deps = entry.dependencies || []
+      for (const dep of deps) {
+        visit(dep)
+      }
+
+      visiting.delete(name)
+      visited.add(name)
+      sorted.push(name)
+    }
+
+    for (const name of this._entries.keys()) {
+      visit(name)
+    }
+
+    return sorted
+  }
+
+  /**
+   * 获取插件条目，不存在则抛错
+   * @param {string} name - 插件名称
+   * @returns {PluginEntry}
+   * @throws {PluginNotFoundError}
+   * @private
+   */
+  _getEntryOrThrow(name) {
+    const entry = this._entries.get(name)
+    if (!entry) {
+      throw new PluginNotFoundError(name)
+    }
+    return entry
+  }
+
+  /**
+   * 防御性日志方法
+   * @param {string} level - 日志级别
+   * @param {string} message - 日志消息
+   * @param {Object} [context={}] - 上下文
+   * @private
+   */
+  _safeLog(level, message, context = {}) {
+    try {
+      if (this._logger && !this._logger.isDestroyed) {
+        this._logger[level](message, context)
+      }
+    } catch (e) {
+      // 完全忽略日志错误
+    }
+  }
+
+  /**
+   * 执行钩子（内部方法，三期新增）
+   * 执行流程：
+   *   1. 调用插件定义的钩子方法（如 plugin.onBeforeInstall）
+   *   2. 通过 EventBus 广播事件（如 plugin:beforeInstall）
+   *   3. 调用 onHook 订阅者回调
+   *
+   * @param {string} hookName - 钩子名称（如 'beforeInstall'）
+   * @param {Object} context - 钩子上下文 { name, plugin, options? }
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _executeHook(hookName, context) {
+    // 1. 调用插件定义的钩子方法
+    //    将 hookName 转为方法名：'beforeInstall' → 'onBeforeInstall'
+    const methodName = 'on' + hookName.charAt(0).toUpperCase() + hookName.slice(1)
+    if (typeof context.plugin[methodName] === 'function') {
+      try {
+        // 安装钩子（beforeInstall/afterInstall）传递 options 参数（向后兼容）
+        // 卸载钩子（beforeUninstall/afterUninstall）传递完整 context（含 app/name/plugin）
+        const isInstallHook = hookName === 'beforeInstall' || hookName === 'afterInstall'
+        const arg = isInstallHook ? context.options : context
+        await context.plugin[methodName](arg)
+      } catch (e) {
+        // 钩子异常仅记录日志，不中断安装/卸载流程
+        this._safeLog('error', `插件 '${context.name}' 的 ${methodName} 钩子执行失败`, { error: e })
+      }
+    }
+
+    // 2. 通过 EventBus 广播事件
+    this._eventBus.emit(`plugin:${hookName}`, context)
+
+    // 3. 调用 onHook 订阅者
+    if (this._hookListeners) {
+      const listeners = this._hookListeners.get(hookName)
+      if (listeners) {
+        for (const callback of listeners) {
+          try {
+            callback(context)
+          } catch (e) {
+            // 订阅者异常仅记录日志，不中断其他订阅者
+            this._safeLog('error', `钩子 '${hookName}' 的订阅者执行失败`, { error: e })
+          }
+        }
+      }
+    }
+  }
+}
+
+export { PluginSystem }

package/src/core/PluginSystem/index.js

@@ -0,0 +1,8 @@
+// ============================================================================
+// Nimbus2D - PluginSystem 模块统一导出
+// ============================================================================
+
+export { PluginSystem } from './PluginSystem.js'
+export { Plugin } from './Plugin.js'
+export { PluginEntry } from './PluginEntry.js'
+export { PluginState } from './PluginState.js'

package/src/core/PoolManager/DefaultConfig.js

@@ -0,0 +1,19 @@
+// ============================================================================
+// Nimbus2D - 对象池默认配置
+// ----------------------------------------------------------------------------
+// PoolManager 的默认配置，写入 ConfigSystem 的 DEFAULT 层。
+// 各池的具体配置由插件通过 ConfigSystem.loadModule() 注册到 MODULE 层。
+// ============================================================================
+
+/**
+ * 对象池默认配置
+ * @type {Object}
+ */
+const PoolDefaultConfig = {
+  /** 对象池管理器配置 */
+  poolManager: {
+    // 默认无配置，各池的配置由插件自己的 loadModule 注册
+  }
+}
+
+export { PoolDefaultConfig }