@nimbus2d/core 0.0.1

package/src/core/EventBus/Interceptor.js

@@ -0,0 +1,26 @@
+// ============================================================================
+// Nimbus2D - EventBus 拦截器辅助类
+// ----------------------------------------------------------------------------
+// 封装拦截器信息和取消注册逻辑
+// ============================================================================
+
+/**
+ * 拦截器辅助类
+ * 封装拦截器函数、作用范围和取消注册方法
+ */
+class Interceptor {
+  /**
+   * 构造函数
+   * @param {Function} fn - 拦截器函数
+   * @param {string|null} [eventType=null] - 事件类型（null 表示全局拦截器）
+   */
+  constructor(fn, eventType = null) {
+    /** @type {Function} 拦截器函数 */
+    this.fn = fn
+
+    /** @type {string|null} 事件类型（null 表示全局拦截器） */
+    this.eventType = eventType
+  }
+}
+
+export { Interceptor }

package/src/core/EventBus/PerformanceStats.js

@@ -0,0 +1,105 @@
+// ============================================================================
+// Nimbus2D - EventBus 性能统计
+// ----------------------------------------------------------------------------
+// 记录事件总线的性能指标
+// ============================================================================
+
+/**
+ * 性能统计类
+ * 跟踪事件总线的触发次数、拦截次数、监听器数量等指标
+ */
+class PerformanceStats {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    /** @type {number} 总事件数（emit 调用次数） */
+    this.totalEvents = 0
+
+    /** @type {number} 已触发数（成功传播到监听器的事件数） */
+    this.emitted = 0
+
+    /** @type {number} 被拦截数（被拦截器阻止的事件数） */
+    this.blocked = 0
+
+    /** @type {number} 监听器总数 */
+    this.listenersCount = 0
+
+    /** @type {number} 拦截器总数 */
+    this.interceptorsCount = 0
+
+    /** @type {number} 累计触发耗时（ms） */
+    this._totalTime = 0
+  }
+
+  /**
+   * 平均触发耗时（ms）
+   * @type {number}
+   */
+  get averageTime() {
+    return this.emitted > 0 ? this._totalTime / this.emitted : 0
+  }
+
+  /**
+   * 记录一次触发
+   * @param {number} elapsedMs - 本次触发耗时（ms）
+   */
+  recordEmit(elapsedMs) {
+    this.totalEvents++
+    this.emitted++
+    this._totalTime += elapsedMs
+  }
+
+  /**
+   * 记录一次拦截
+   */
+  recordBlock() {
+    this.totalEvents++
+    this.blocked++
+  }
+
+  /**
+   * 更新监听器计数
+   * @param {number} count - 监听器数量
+   */
+  setListenersCount(count) {
+    this.listenersCount = count
+  }
+
+  /**
+   * 更新拦截器计数
+   * @param {number} count - 拦截器数量
+   */
+  setInterceptorsCount(count) {
+    this.interceptorsCount = count
+  }
+
+  /**
+   * 获取统计快照
+   * @returns {Object} 统计数据快照
+   */
+  getStats() {
+    return {
+      totalEvents: this.totalEvents,
+      emitted: this.emitted,
+      blocked: this.blocked,
+      listenersCount: this.listenersCount,
+      interceptorsCount: this.interceptorsCount,
+      averageTime: this.averageTime
+    }
+  }
+
+  /**
+   * 重置所有统计数据
+   */
+  reset() {
+    this.totalEvents = 0
+    this.emitted = 0
+    this.blocked = 0
+    this.listenersCount = 0
+    this.interceptorsCount = 0
+    this._totalTime = 0
+  }
+}
+
+export { PerformanceStats }

package/src/core/EventBus/index.js

@@ -0,0 +1,7 @@
+// ============================================================================
+// Nimbus2D - EventBus 模块统一导出
+// ============================================================================
+
+export { EventBus } from './EventBus.js'
+export { Interceptor } from './Interceptor.js'
+export { PerformanceStats } from './PerformanceStats.js'

package/src/core/Lifecycle/Lifecycle.js

@@ -0,0 +1,265 @@
+// ============================================================================
+// Nimbus2D - Lifecycle 生命周期管理
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 集中调度型：调用所有子系统的 initialize/update/destroy
+//   2. 状态机：CREATED → INITIALIZING → INITIALIZED → ACTIVE ⇄ PAUSED → DESTROYING → DESTROYED
+//   3. activate()/pause() 仅改变 Lifecycle 自身状态（不调用子系统的 activate/deactivate）
+//   4. update() 不检查子系统 isActive（直接调用所有子系统的 update）
+//   5. 销毁阶段不抛异常（记录到 Logger 后继续）
+//
+// 继承关系：
+//   EventEmitter → Lifecycle（调度者，不被其他模块调度）
+// ============================================================================
+
+import { EventEmitter } from '../../base/EventEmitter.js'
+import { LifecycleState } from './LifecycleState.js'
+import { LifecycleStateError } from '../../errors/LifecycleError.js'
+
+class Lifecycle extends EventEmitter {
+  /**
+   * 构造函数
+   * @param {import('../EventBus/EventBus.js').EventBus} eventBus - 全局事件总线
+   * @param {import('../Logger/Logger.js').Logger} logger - 日志系统实例（用于 _safeLog 防御性日志）
+   */
+  constructor(eventBus, logger) {
+    super()
+
+    /** @type {import('../EventBus/EventBus.js').EventBus} 全局事件总线 */
+    this._eventBus = eventBus
+
+    /** @type {import('../Logger/Logger.js').Logger} 日志系统实例 */
+    this._logger = logger
+
+    /** @type {LifecycleState} 当前状态 */
+    this._state = LifecycleState.CREATED
+
+    /** @type {import('../../base/Subsystem.js').Subsystem[]} 子系统列表（按注册顺序） */
+    this._subsystems = []
+  }
+
+  // --------------------------------------------------------------------------
+  // 子系统管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注册子系统
+   * @param {import('../../base/Subsystem.js').Subsystem} subsystem - 子系统实例
+   * @returns {Lifecycle} - this（链式）
+   */
+  registerSubsystem(subsystem) {
+    // 检查是否已注册（按名称去重）
+    const existing = this._subsystems.find((s) => s.name === subsystem.name)
+    if (existing) {
+      this._safeLog('warn', `子系统 ${subsystem.name} 已注册，跳过重复注册`)
+      return this
+    }
+
+    this._subsystems.push(subsystem)
+    this.emit('subsystem:registered', { name: subsystem.name, subsystem })
+    return this
+  }
+
+  /**
+   * 注销子系统（不销毁，仅从调度列表移除）
+   * @param {string} name - 子系统名称
+   * @returns {boolean} - 是否注销成功
+   */
+  unregisterSubsystem(name) {
+    const index = this._subsystems.findIndex((s) => s.name === name)
+    if (index === -1) return false
+
+    // 从列表移除
+    const [subsystem] = this._subsystems.splice(index, 1)
+    this.emit('subsystem:unregistered', { name: subsystem.name })
+    return true
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 初始化所有子系统（按注册顺序）
+   * @returns {Promise<void>}
+   * @throws {LifecycleStateError} 状态不合法时
+   */
+  async initialize() {
+    // 状态检查：必须为 CREATED
+    if (this._state !== LifecycleState.CREATED) {
+      throw new LifecycleStateError(this._state, [LifecycleState.CREATED])
+    }
+
+    // 转换到 INITIALIZING 状态
+    const oldState = this._state
+    this._state = LifecycleState.INITIALIZING
+    this.emit('state:change', { from: oldState, to: LifecycleState.INITIALIZING })
+
+    // 按注册顺序初始化所有子系统
+    for (const subsystem of this._subsystems) {
+      try {
+        await subsystem.initialize()
+        this.emit('subsystem:initialized', { name: subsystem.name, subsystem })
+      } catch (e) {
+        // 初始化阶段错误向上抛出
+        this.emit('subsystem:error', { name: subsystem.name, error: e, phase: 'initialize' })
+        this._safeLog('error', `子系统 ${subsystem.name} 初始化失败`, { error: e })
+        throw e
+      }
+    }
+
+    // 转换到 INITIALIZED 状态
+    const prevState = this._state
+    this._state = LifecycleState.INITIALIZED
+    this.emit('state:change', { from: prevState, to: LifecycleState.INITIALIZED })
+    this.emit('initialized')
+  }
+
+  /**
+   * 激活 Lifecycle（使 update 生效）
+   * 仅改变 Lifecycle 自身状态，不调用子系统的 activate/deactivate
+   * @returns {Lifecycle} - this
+   * @throws {LifecycleStateError} 状态不合法时
+   */
+  activate() {
+    // 状态检查：必须为 INITIALIZED 或 PAUSED
+    if (this._state !== LifecycleState.INITIALIZED && this._state !== LifecycleState.PAUSED) {
+      throw new LifecycleStateError(this._state, [LifecycleState.INITIALIZED, LifecycleState.PAUSED])
+    }
+
+    const oldState = this._state
+    this._state = LifecycleState.ACTIVE
+    this.emit('state:change', { from: oldState, to: LifecycleState.ACTIVE })
+    this.emit('activated')
+    return this
+  }
+
+  /**
+   * 暂停 Lifecycle（不调用 update）
+   * 仅改变 Lifecycle 自身状态，不调用子系统的 activate/deactivate
+   * @returns {Lifecycle} - this
+   * @throws {LifecycleStateError} 状态不合法时
+   */
+  pause() {
+    // 状态检查：必须为 ACTIVE
+    if (this._state !== LifecycleState.ACTIVE) {
+      throw new LifecycleStateError(this._state, [LifecycleState.ACTIVE])
+    }
+
+    const oldState = this._state
+    this._state = LifecycleState.PAUSED
+    this.emit('state:change', { from: oldState, to: LifecycleState.PAUSED })
+    this.emit('paused')
+    return this
+  }
+
+  /**
+   * 调用所有子系统的 update（按注册顺序）
+   * 仅在 ACTIVE 状态下执行，update 不检查子系统 isActive
+   * @param {number} delta - 帧间隔（秒）
+   */
+  update(delta) {
+    // 只有 ACTIVE 状态才调用 update
+    if (this._state !== LifecycleState.ACTIVE) return
+
+    for (const subsystem of this._subsystems) {
+      try {
+        subsystem.update(delta)
+      } catch (e) {
+        this.emit('subsystem:error', { name: subsystem.name, error: e, phase: 'update' })
+        this._safeLog('error', `子系统 ${subsystem.name} 更新失败`, { error: e })
+      }
+    }
+  }
+
+  /**
+   * 销毁所有子系统（反向顺序，不抛异常）
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this._state === LifecycleState.DESTROYED) return
+
+    const oldState = this._state
+    this._state = LifecycleState.DESTROYING
+    this.emit('state:change', { from: oldState, to: LifecycleState.DESTROYING })
+
+    // 反向销毁所有子系统（错误不中断流程）
+    const subsystems = [...this._subsystems].reverse()
+    for (const subsystem of subsystems) {
+      try {
+        await subsystem.destroy()
+      } catch (e) {
+        // 销毁阶段错误不抛出，记录到 Logger（若可用）
+        this.emit('subsystem:error', { name: subsystem.name, error: e, phase: 'destroy' })
+        this._safeLog('error', `子系统 ${subsystem.name} 销毁失败`, { error: e })
+      }
+    }
+
+    // 转换到 DESTROYED 状态
+    const prevState = this._state
+    this._state = LifecycleState.DESTROYED
+    this.emit('state:change', { from: prevState, to: LifecycleState.DESTROYED })
+    this.emit('destroyed')
+
+    // 清理引用
+    this._subsystems = []
+    this._eventBus = null
+    this._logger = null
+
+    // 调用父类 destroy 设置 _destroyed = true 并清理监听器
+    super.destroy()
+  }
+
+  // --------------------------------------------------------------------------
+  // 查询方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 当前状态
+   * @type {LifecycleState}
+   */
+  get state() {
+    return this._state
+  }
+
+  /**
+   * 所有子系统数组（返回副本）
+   * @type {import('../../base/Subsystem.js').Subsystem[]}
+   */
+  get subsystems() {
+    return [...this._subsystems]
+  }
+
+  /**
+   * 按名称获取子系统
+   * @param {string} name - 子系统名称
+   * @returns {import('../../base/Subsystem.js').Subsystem|null} 子系统实例，未找到返回 null
+   */
+  getSubsystem(name) {
+    return this._subsystems.find((s) => s.name === name) || null
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 防御性日志方法
+   * 处理 Logger 可能已销毁的情况
+   * @param {string} level - 日志级别（'debug'|'info'|'warn'|'error'）
+   * @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) {
+      // 完全忽略日志错误
+    }
+  }
+}
+
+export { Lifecycle }

package/src/core/Lifecycle/LifecycleState.js

@@ -0,0 +1,31 @@
+// ============================================================================
+// Nimbus2D - Lifecycle 状态枚举
+// ----------------------------------------------------------------------------
+// 定义 Lifecycle 生命周期管理器的所有合法状态。
+//
+// 状态转换流程：
+//   CREATED → INITIALIZING → INITIALIZED → ACTIVE ⇄ PAUSED → DESTROYING → DESTROYED
+// ============================================================================
+
+/**
+ * Lifecycle 状态枚举
+ * @enum {string}
+ */
+const LifecycleState = {
+  /** 已创建（初始状态） */
+  CREATED: 'CREATED',
+  /** 初始化中 */
+  INITIALIZING: 'INITIALIZING',
+  /** 已初始化（等待激活） */
+  INITIALIZED: 'INITIALIZED',
+  /** 已激活（update 生效） */
+  ACTIVE: 'ACTIVE',
+  /** 已暂停（update 不执行） */
+  PAUSED: 'PAUSED',
+  /** 销毁中 */
+  DESTROYING: 'DESTROYING',
+  /** 已销毁（终态） */
+  DESTROYED: 'DESTROYED'
+}
+
+export { LifecycleState }

package/src/core/Lifecycle/index.js

@@ -0,0 +1,6 @@
+// ============================================================================
+// Nimbus2D - Lifecycle 模块统一导出
+// ============================================================================
+
+export { Lifecycle } from './Lifecycle.js'
+export { LifecycleState } from './LifecycleState.js'

package/src/core/Logger/ConsoleHandler.js

@@ -0,0 +1,55 @@
+// ============================================================================
+// Nimbus2D - ConsoleHandler 控制台日志处理器
+// ----------------------------------------------------------------------------
+// 默认的日志处理器，输出到浏览器控制台
+// ============================================================================
+
+import { LogHandler } from './LogHandler.js'
+import { LogLevel, logLevelToString } from './LogLevel.js'
+
+/**
+ * 控制台日志处理器
+ * 继承 LogHandler，输出格式化的日志到浏览器控制台
+ */
+class ConsoleHandler extends LogHandler {
+  /**
+   * 构造函数
+   * @param {number} [level=LogLevel.DEBUG] - 最低处理级别
+   */
+  constructor(level = LogLevel.DEBUG) {
+    super(level)
+  }
+
+  /**
+   * 处理日志（继承自 LogHandler 的 handle 方法）
+   * @param {number} level - 日志级别
+   * @param {string} message - 消息
+   * @param {Object} [context={}] - 上下文
+   */
+  handle(level, message, context) {
+    if (level < this.level) return
+
+    const levelName = logLevelToString(level)
+    const time = new Date().toISOString()
+    const prefix = `[${time}] [${levelName}]`
+
+    switch (level) {
+      case LogLevel.DEBUG:
+        console.debug(prefix, message, context)
+        break
+      case LogLevel.INFO:
+        console.info(prefix, message, context)
+        break
+      case LogLevel.WARN:
+        console.warn(prefix, message, context)
+        break
+      case LogLevel.ERROR:
+        console.error(prefix, message, context)
+        break
+      default:
+        console.log(prefix, message, context)
+    }
+  }
+}
+
+export { ConsoleHandler }

package/src/core/Logger/LogHandler.js

@@ -0,0 +1,34 @@
+// ============================================================================
+// Nimbus2D - LogHandler 日志处理器基类
+// ----------------------------------------------------------------------------
+// 所有日志处理器的基类，子类重写 handle 方法
+// ============================================================================
+
+import { LogLevel } from './LogLevel.js'
+
+/**
+ * 日志处理器基类
+ * 子类必须重写 handle(level, message, context) 方法
+ */
+class LogHandler {
+  /**
+   * 构造函数
+   * @param {number} [level=LogLevel.DEBUG] - 最低处理级别
+   */
+  constructor(level = LogLevel.DEBUG) {
+    /** @type {number} 最低处理级别 */
+    this.level = level
+  }
+
+  /**
+   * 处理日志（子类重写）
+   * @param {number} level - 日志级别
+   * @param {string} message - 消息
+   * @param {Object} [context={}] - 上下文
+   */
+  handle(level, message, context) {
+    // 基类空实现，子类必须重写
+  }
+}
+
+export { LogHandler }

package/src/core/Logger/LogLevel.js

@@ -0,0 +1,38 @@
+// ============================================================================
+// Nimbus2D - 日志级别枚举
+// ----------------------------------------------------------------------------
+// DEBUG=0, INFO=1, WARN=2, ERROR=3, NONE=4
+// ============================================================================
+
+/**
+ * 日志级别枚举
+ * @enum {number}
+ */
+export const LogLevel = {
+  /** 调试级别（最详细） */
+  DEBUG: 0,
+  /** 信息级别 */
+  INFO: 1,
+  /** 警告级别 */
+  WARN: 2,
+  /** 错误级别 */
+  ERROR: 3,
+  /** 关闭日志 */
+  NONE: 4
+}
+
+/**
+ * 日志级别名称映射
+ * @param {number} level - 日志级别
+ * @returns {string} 级别名称
+ */
+export function logLevelToString(level) {
+  switch (level) {
+    case LogLevel.DEBUG: return 'DEBUG'
+    case LogLevel.INFO: return 'INFO'
+    case LogLevel.WARN: return 'WARN'
+    case LogLevel.ERROR: return 'ERROR'
+    case LogLevel.NONE: return 'NONE'
+    default: return 'UNKNOWN'
+  }
+}