@nimbus2d/core 0.0.1

package/src/core/Logger/Logger.js

@@ -0,0 +1,234 @@
+// ============================================================================
+// Nimbus2D - Logger 日志系统
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 四级日志：debug/info/warn/error
+//   2. 级别控制：DEBUG=0/INFO=1/WARN=2/ERROR=3/NONE=4
+//   3. 对象型 handler：{ level, handle(level, message, context) }
+//   4. 内置 ConsoleHandler（默认，明确实现 handle 方法）
+//   5. 双通道广播（this.emit('log') + this._eventBus.emit('log')）
+//
+// 继承关系：
+//   EventEmitter → Subsystem → Logger（Lifecycle 内第一个初始化）
+// ============================================================================
+
+import { Subsystem } from '../../base/Subsystem.js'
+import { LogLevel } from './LogLevel.js'
+import { ConsoleHandler } from './ConsoleHandler.js'
+
+class Logger extends Subsystem {
+  /**
+   * 构造函数
+   * 注意：Logger 不传 logger 参数给 super()，Logger 自身就是 logger
+   * 内部调用 super(eventBus, config, null)，然后 this._logger = this
+   * @param {import('../EventBus/EventBus.js').EventBus} eventBus - 全局事件总线
+   * @param {import('../ConfigSystem/ConfigSystem.js').ConfigSystem} config - 配置系统
+   */
+  constructor(eventBus, config) {
+    super(eventBus, config, null)
+
+    // Logger 自身就是 logger，设置 _logger = this
+    this._logger = this
+
+    /** @type {number} 当前日志级别 */
+    this._level = LogLevel.INFO
+
+    /** @type {LogHandler[]} 处理器列表 */
+    this._handlers = []
+
+    /** @type {Function|null} 配置监听取消函数 */
+    this._unwatchLevel = null
+  }
+
+  // --------------------------------------------------------------------------
+  // 日志方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * DEBUG 级别日志
+   * @param {string} message - 消息
+   * @param {Object} [context={}] - 上下文
+   */
+  debug(message, context = {}) {
+    this.log(LogLevel.DEBUG, message, context)
+  }
+
+  /**
+   * INFO 级别日志
+   * @param {string} message - 消息
+   * @param {Object} [context={}] - 上下文
+   */
+  info(message, context = {}) {
+    this.log(LogLevel.INFO, message, context)
+  }
+
+  /**
+   * WARN 级别日志
+   * @param {string} message - 消息
+   * @param {Object} [context={}] - 上下文
+   */
+  warn(message, context = {}) {
+    this.log(LogLevel.WARN, message, context)
+  }
+
+  /**
+   * ERROR 级别日志
+   * @param {string} message - 消息
+   * @param {Object} [context={}] - 上下文
+   */
+  error(message, context = {}) {
+    this.log(LogLevel.ERROR, message, context)
+  }
+
+  /**
+   * 通用日志方法
+   * @param {number} level - 日志级别
+   * @param {string} message - 消息
+   * @param {Object} [context={}] - 上下文
+   */
+  log(level, message, context = {}) {
+    if (!this.isEnabledFor(level)) return
+
+    // 1. 调用所有 handler
+    for (const handler of this._handlers) {
+      try {
+        handler.handle(level, message, context)
+      } catch (e) {
+        // handler 错误不中断其他 handler
+      }
+    }
+
+    // 2. 双通道广播日志事件
+    // 通道 A：Logger 自身 emit（局部监听）
+    this.emit('log', { level, message, context })
+    // 通道 B：EventBus 广播（全局监听）
+    if (this._eventBus) {
+      try {
+        this._eventBus.emit('log', { level, message, context, logger: this.name })
+      } catch (e) {
+        // EventBus 错误不影响日志流程
+      }
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 级别控制
+  // --------------------------------------------------------------------------
+
+  /**
+   * 设置日志级别
+   * @param {number} level - 日志级别（LogLevel 枚举值）
+   */
+  setLevel(level) {
+    const oldLevel = this._level
+    this._level = level
+    this.emit('level:change', { oldLevel, newLevel: level })
+  }
+
+  /**
+   * 获取当前日志级别
+   * @returns {number}
+   */
+  getLevel() {
+    return this._level
+  }
+
+  /**
+   * 检查指定级别是否启用
+   * @param {number} level - 日志级别
+   * @returns {boolean}
+   */
+  isEnabledFor(level) {
+    return level >= this._level
+  }
+
+  // --------------------------------------------------------------------------
+  // Handler 管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 添加 handler
+   * @param {LogHandler} handler - 处理器实例
+   */
+  addHandler(handler) {
+    if (this._handlers.includes(handler)) return
+    this._handlers.push(handler)
+    this.emit('handler:added', { handler })
+  }
+
+  /**
+   * 移除 handler
+   * @param {LogHandler} handler - 处理器实例
+   */
+  removeHandler(handler) {
+    const idx = this._handlers.indexOf(handler)
+    if (idx !== -1) {
+      this._handlers.splice(idx, 1)
+      this.emit('handler:removed', { handler })
+    }
+  }
+
+  /**
+   * 获取所有 handler
+   * @returns {LogHandler[]}
+   */
+  getHandlers() {
+    return [...this._handlers]
+  }
+
+  /**
+   * 清空所有 handler
+   */
+  clearHandlers() {
+    this._handlers = []
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期（继承自 Subsystem）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 初始化：自动注册 ConsoleHandler，监听 ConfigSystem
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    await super.initialize()
+
+    // 自动注册 ConsoleHandler
+    this.addHandler(new ConsoleHandler())
+
+    // 监听 ConfigSystem 变化
+    if (this._config) {
+      this._unwatchLevel = this._config.watch('modules.logger.level', (newValue) => {
+        if (typeof newValue === 'number') {
+          this.setLevel(newValue)
+        }
+      })
+
+      // 初始化级别
+      const configLevel = this._config.get('modules.logger.level')
+      if (typeof configLevel === 'number') {
+        this.setLevel(configLevel)
+      }
+    }
+  }
+
+  /**
+   * 销毁：清理 handler 和配置监听
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    // 取消配置监听
+    if (this._unwatchLevel) {
+      this._unwatchLevel()
+      this._unwatchLevel = null
+    }
+
+    // 清理 handler
+    this._handlers = []
+
+    await super.destroy()
+  }
+}
+
+export { Logger }

package/src/core/Logger/index.js

@@ -0,0 +1,8 @@
+// ============================================================================
+// Nimbus2D - Logger 模块统一导出
+// ============================================================================
+
+export { Logger } from './Logger.js'
+export { LogLevel } from './LogLevel.js'
+export { LogHandler } from './LogHandler.js'
+export { ConsoleHandler } from './ConsoleHandler.js'

package/src/core/PluginSystem/Plugin.js

@@ -0,0 +1,156 @@
+// ============================================================================
+// Nimbus2D - 插件基类
+// ----------------------------------------------------------------------------
+// 所有插件必须继承此基类，提供安装/卸载/更新生命周期。
+//
+// 设计决策：
+//   - 独立设计（不继承任何类）
+//   - name getter 必须由子类实现
+//   - install/uninstall 可返回 Promise（支持异步安装）
+//   - update 可选重写
+//   - 静态 isPlugin 检查方法
+// ============================================================================
+
+class Plugin {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    // 基类无状态
+  }
+
+  // --------------------------------------------------------------------------
+  // 元信息（子类必须实现 name，其他可选）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 插件名称（必须重写，不实现抛错）
+   * @type {string}
+   */
+  get name() {
+    throw new Error('Plugin.name 必须由子类实现')
+  }
+
+  /**
+   * 插件版本，默认 '1.0.0'
+   * @type {string}
+   */
+  get version() {
+    return '1.0.0'
+  }
+
+  /**
+   * 依赖插件名数组，默认 []
+   * @type {string[]}
+   */
+  get dependencies() {
+    return []
+  }
+
+  /**
+   * 插件描述，默认 ''
+   * @type {string}
+   */
+  get description() {
+    return ''
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期方法（子类重写）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 安装插件
+   * @param {object} app - Application 实例
+   * @param {Object} [options={}] - 插件配置
+   * @returns {void|Promise<void>}
+   */
+  install(app, options = {}) {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 卸载插件
+   * @param {object} app - Application 实例
+   * @returns {void|Promise<void>}
+   */
+  uninstall(app) {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 每帧更新（可选重写）
+   * @param {number} delta - 帧间隔（秒）
+   * @param {object} app - Application 实例
+   */
+  update(delta, app) {
+    // 基类空实现，子类按需重写
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期钩子（三期新增，子类可重写，默认空实现）
+  // 钩子执行顺序：beforeInstall → install → afterInstall
+  //                beforeUninstall → uninstall → afterUninstall
+  // --------------------------------------------------------------------------
+
+  /**
+   * 安装前钩子（在 install() 调用前执行）
+   * 用于安装前的校验、资源预加载等准备工作
+   * @param {Object} [options={}] - 插件配置
+   * @returns {void|Promise<void>}
+   */
+  onBeforeInstall(options = {}) {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 安装后钩子（在 install() 调用后执行）
+   * 用于安装后的初始化、事件注册等后续操作
+   * @param {Object} [options={}] - 插件配置
+   * @returns {void|Promise<void>}
+   */
+  onAfterInstall(options = {}) {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 卸载前钩子（在 uninstall() 调用前执行）
+   * 用于卸载前的资源保存、通知发送等清理准备
+   * @param {Object} [context={}] - 钩子上下文
+   * @param {string} [context.name] - 插件名称
+   * @param {Plugin} [context.plugin] - 插件实例
+   * @param {object} [context.app] - Application 实例（供需要访问应用的清理逻辑使用）
+   * @returns {void|Promise<void>}
+   */
+  onBeforeUninstall(context = {}) {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 卸载后钩子（在 uninstall() 调用后执行）
+   * 用于卸载后的最终清理、日志记录等收尾操作
+   * @param {Object} [context={}] - 钩子上下文
+   * @param {string} [context.name] - 插件名称
+   * @param {Plugin} [context.plugin] - 插件实例
+   * @param {object} [context.app] - Application 实例（供需要访问应用的收尾逻辑使用）
+   * @returns {void|Promise<void>}
+   */
+  onAfterUninstall(context = {}) {
+    // 基类空实现，子类按需重写
+  }
+
+  // --------------------------------------------------------------------------
+  // 静态方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 检查对象是否为 Plugin 实例
+   * @param {any} obj - 待检查对象
+   * @returns {boolean}
+   */
+  static isPlugin(obj) {
+    return obj instanceof Plugin
+  }
+}
+
+export { Plugin }

package/src/core/PluginSystem/PluginEntry.js

@@ -0,0 +1,102 @@
+// ============================================================================
+// Nimbus2D - 插件条目类
+// ----------------------------------------------------------------------------
+// 封装插件注册条目的状态与元数据，公开辅助类。
+//
+// 设计决策：
+//   - 公开导出，用户可访问
+//   - setState 和 markInstalled 仅供 PluginSystem 内部调用
+//   - 所有字段通过只读 getter 暴露
+// ============================================================================
+
+import { PluginState } from './PluginState.js'
+
+class PluginEntry {
+  /**
+   * 构造函数
+   * @param {import('./Plugin.js').Plugin} plugin - 插件实例
+   * @param {Object} [options={}] - 插件配置
+   */
+  constructor(plugin, options = {}) {
+    /** @type {import('./Plugin.js').Plugin} 插件实例 */
+    this._plugin = plugin
+
+    /** @type {string} 插件名称 */
+    this._name = plugin.name
+
+    /** @type {PluginState} 插件状态 */
+    this._state = PluginState.REGISTERED
+
+    /** @type {Object} 插件配置 */
+    this._options = options
+
+    /** @type {string[]} 依赖列表 */
+    this._dependencies = plugin.dependencies || []
+
+    /** @type {number|null} 安装时间戳 */
+    this._installTime = null
+  }
+
+  // --------------------------------------------------------------------------
+  // 只读 Getter
+  // --------------------------------------------------------------------------
+
+  /** @type {import('./Plugin.js').Plugin} 插件实例 */
+  get plugin() { return this._plugin }
+
+  /** @type {string} 插件名称 */
+  get name() { return this._name }
+
+  /** @type {PluginState} 插件状态 */
+  get state() { return this._state }
+
+  /** @type {Object} 插件配置 */
+  get options() { return this._options }
+
+  /** @type {string[]} 依赖列表 */
+  get dependencies() { return this._dependencies }
+
+  /** @type {number|null} 安装时间戳 */
+  get installTime() { return this._installTime }
+
+  // --------------------------------------------------------------------------
+  // 状态变更方法（仅 PluginSystem 内部调用）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 设置插件状态
+   * @param {PluginState} newState - 新状态
+   */
+  setState(newState) {
+    this._state = newState
+  }
+
+  /**
+   * 标记为已安装（同时记录 installTime）
+   */
+  markInstalled() {
+    this._state = PluginState.INSTALLED
+    this._installTime = Date.now()
+  }
+
+  /**
+   * 重置安装时间戳（卸载时调用，通过公共方法避免外部直接访问私有属性）
+   */
+  resetInstallTime() {
+    this._installTime = null
+  }
+
+  // --------------------------------------------------------------------------
+  // 工具方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 返回字符串表示
+   * @returns {string}
+   */
+  toString() {
+    return `PluginEntry(name=${this._name}, state=${this._state})`
+  }
+}
+
+export { PluginEntry }

package/src/core/PluginSystem/PluginState.js

@@ -0,0 +1,30 @@
+// ============================================================================
+// Nimbus2D - 插件状态枚举
+// ----------------------------------------------------------------------------
+// 定义插件的所有合法状态。
+//
+// 状态转换流程：
+//   无 → REGISTERED → INSTALLING → INSTALLED → UNINSTALLING → UNREGISTERED
+//   任何状态都可能因异常进入 ERROR 状态
+// ============================================================================
+
+/**
+ * 插件状态枚举
+ * @enum {string}
+ */
+const PluginState = {
+  /** 已注册（仅注册未安装） */
+  REGISTERED: 'REGISTERED',
+  /** 安装中 */
+  INSTALLING: 'INSTALLING',
+  /** 已安装 */
+  INSTALLED: 'INSTALLED',
+  /** 卸载中 */
+  UNINSTALLING: 'UNINSTALLING',
+  /** 已注销 */
+  UNREGISTERED: 'UNREGISTERED',
+  /** 错误状态 */
+  ERROR: 'ERROR'
+}
+
+export { PluginState }