@nimbus2d/core 0.0.1

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nimbus2d/core",
+  "version": "0.0.1",
+  "description": "Nimbus2D 核心框架 - 基于 PixiJS v8 的微内核 + 插件化 2D 游戏开发框架",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch"
+  },
+  "peerDependencies": {
+    "pixi.js": "^8.0.0"
+  },
+  "keywords": [
+    "nimbus2d",
+    "game-framework",
+    "pixijs",
+    "2d",
+    "plugin",
+    "microkernel"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nimbus2d/nimbus-2d.git",
+    "directory": "packages/@nimbus2d/core"
+  }
+}

package/src/base/EventEmitter.js

@@ -0,0 +1,187 @@
+// ============================================================================
+// Nimbus2D - 事件发射器基类
+// ----------------------------------------------------------------------------
+// 职责：
+//   提供基础事件能力（on/off/once/emit/removeAllListeners），
+//   是所有事件相关类的基类。
+//
+// 设计决策：
+//   - 轻量级实现，不依赖第三方库
+//   - on/once 返回取消注册函数（Function）
+//   - off 返回 boolean（是否注销成功）
+//   - emit 返回 boolean（true 表示有监听器被调用）
+//   - 监听器按注册顺序调用
+//   - once 监听器触发后自动移除
+//   - emit 时如果监听器抛错，捕获并 console.error，不影响其他监听器
+// ============================================================================
+
+class EventEmitter {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    /** @type {Map<string, Array<{fn: Function, once: boolean}>>} 事件监听器映射表 */
+    this._listeners = new Map()
+
+    /** @type {boolean} 是否已销毁 */
+    this._destroyed = false
+  }
+
+  /**
+   * 注册事件监听器
+   * @param {string} event - 事件名称
+   * @param {Function} listener - 监听回调
+   * @returns {Function} 取消注册函数
+   */
+  on(event, listener) {
+    if (this._destroyed) return () => {}
+    if (typeof listener !== 'function') {
+      console.warn(`[EventEmitter] on() 监听器必须是函数: ${event}`)
+      return () => {}
+    }
+
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, [])
+    }
+    this._listeners.get(event).push({ fn: listener, once: false })
+
+    // 返回取消注册函数
+    return () => this.off(event, listener)
+  }
+
+  /**
+   * 注册一次性事件监听器（触发一次后自动移除）
+   * @param {string} event - 事件名称
+   * @param {Function} listener - 监听回调
+   * @returns {Function} 取消注册函数
+   */
+  once(event, listener) {
+    if (this._destroyed) return () => {}
+    if (typeof listener !== 'function') {
+      console.warn(`[EventEmitter] once() 监听器必须是函数: ${event}`)
+      return () => {}
+    }
+
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, [])
+    }
+    this._listeners.get(event).push({ fn: listener, once: true })
+
+    // 返回取消注册函数
+    return () => this.off(event, listener)
+  }
+
+  /**
+   * 移除事件监听器
+   * @param {string} event - 事件名称
+   * @param {Function} listener - 要移除的监听回调
+   * @returns {boolean} 是否注销成功
+   */
+  off(event, listener) {
+    if (this._destroyed) return false
+
+    const list = this._listeners.get(event)
+    if (!list) return false
+
+    // 移除匹配的监听器（只移除第一个匹配的）
+    const index = list.findIndex((entry) => entry.fn === listener)
+    if (index === -1) return false
+
+    list.splice(index, 1)
+
+    // 如果该事件已无监听器，清理 Map 条目
+    if (list.length === 0) {
+      this._listeners.delete(event)
+    }
+
+    return true
+  }
+
+  /**
+   * 触发事件
+   * @param {string} event - 事件名称
+   * @param {...*} args - 传递给监听器的参数
+   * @returns {boolean} true 表示有监听器被调用
+   */
+  emit(event, ...args) {
+    if (this._destroyed) return false
+
+    const list = this._listeners.get(event)
+    if (!list || list.length === 0) return false
+
+    // 复制监听器列表，避免迭代中修改列表
+    const listeners = list.slice()
+
+    // 收集需要移除的 once 监听器
+    const toRemove = []
+
+    for (const entry of listeners) {
+      try {
+        entry.fn(...args)
+      } catch (err) {
+        console.error(`[EventEmitter] 事件 "${event}" 监听器执行出错:`, err)
+      }
+
+      if (entry.once) {
+        toRemove.push(entry)
+      }
+    }
+
+    // 移除已触发的 once 监听器
+    for (const entry of toRemove) {
+      const index = list.indexOf(entry)
+      if (index !== -1) {
+        list.splice(index, 1)
+      }
+    }
+
+    // 如果该事件已无监听器，清理 Map 条目
+    if (list.length === 0) {
+      this._listeners.delete(event)
+    }
+
+    return true
+  }
+
+  /**
+   * 移除指定事件的所有监听器（不传参则移除所有事件的所有监听器）
+   * @param {string} [event] - 事件名称，不传则移除所有
+   */
+  removeAllListeners(event) {
+    if (this._destroyed) return
+
+    if (event) {
+      this._listeners.delete(event)
+    } else {
+      this._listeners.clear()
+    }
+  }
+
+  /**
+   * 获取指定事件的监听器数量
+   * @param {string} event - 事件名称
+   * @returns {number} 监听器数量
+   */
+  listenerCount(event) {
+    const list = this._listeners.get(event)
+    return list ? list.length : 0
+  }
+
+  /**
+   * 获取所有已注册的事件名称
+   * @returns {string[]} 事件名称数组
+   */
+  eventNames() {
+    return Array.from(this._listeners.keys())
+  }
+
+  /**
+   * 销毁，清理所有监听器
+   */
+  destroy() {
+    this._destroyed = true
+    this._listeners.clear()
+  }
+}
+
+export { EventEmitter }

package/src/base/Subsystem.js

@@ -0,0 +1,183 @@
+// ============================================================================
+// Nimbus2D - 子系统基类
+// ----------------------------------------------------------------------------
+// 职责：
+//   提供完整的生命周期骨架（initialize/update/activate/deactivate/destroy），
+//   便于 Lifecycle 集中调度。
+//
+// 设计决策：
+//   - 继承 EventEmitter，提供事件能力
+//   - 构造函数使用位置参数：constructor(eventBus, config, logger=null)
+//   - initialize() 仅设置 _isInitialized（不设置 _isActive）
+//   - _isActive 默认 false，需显式调用 activate() 才置为 true
+//   - Logger 参数可选（解决 Logger 鸡生蛋问题）
+//   - initialize() 状态检查抛 SubsystemStateError
+//   - destroy() 为 async 方法（子类异步销毁）
+//   - 子类通过重写生命周期方法扩展行为
+// ============================================================================
+
+import { EventEmitter } from './EventEmitter.js'
+import { SubsystemStateError } from '../errors/SubsystemError.js'
+
+class Subsystem extends EventEmitter {
+  /**
+   * 构造函数
+   * @param {import('../core/EventBus/EventBus.js').EventBus} eventBus - 全局事件总线
+   * @param {import('../core/ConfigSystem/ConfigSystem.js').ConfigSystem} config - 配置系统
+   * @param {import('../core/Logger/Logger.js').Logger|null} [logger=null] - 日志系统（可选，Logger 自身传 null）
+   */
+  constructor(eventBus, config, logger = null) {
+    super()
+
+    /** @type {import('../core/EventBus/EventBus.js').EventBus} 全局事件总线 */
+    this._eventBus = eventBus
+
+    /** @type {import('../core/ConfigSystem/ConfigSystem.js').ConfigSystem} 配置系统 */
+    this._config = config
+
+    /** @type {import('../core/Logger/Logger.js').Logger|null} 日志系统（可能为 null） */
+    this._logger = logger
+
+    /** @type {boolean} 是否已初始化 */
+    this._isInitialized = false
+
+    /** @type {boolean} 是否已激活 */
+    this._isActive = false
+
+    /** @type {boolean} 是否已销毁 */
+    this._isDestroyed = false
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 初始化子系统
+   * 默认行为：
+   *   1. 检查状态（必须未初始化且未销毁，否则抛 SubsystemStateError）
+   *   2. 标记 _isInitialized = true（注意：不设置 _isActive = true）
+   *   3. emit 'initialized' 事件
+   * 子类重写时应先调用 super.initialize()
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (this._isInitialized) {
+      throw new SubsystemStateError(this.name, 'INITIALIZED', ['CREATED'])
+    }
+    if (this._isDestroyed) {
+      throw new SubsystemStateError(this.name, 'DESTROYED', ['CREATED'])
+    }
+    this._isInitialized = true
+    this.emit('initialized', { name: this.name })
+  }
+
+  /**
+   * 每帧更新
+   * 子类重写此方法执行每帧逻辑
+   * @param {number} delta - 距上一帧的时间增量（秒）
+   * @returns {void}
+   */
+  update(delta) {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 激活子系统
+   * 默认行为：
+   *   1. 检查 _isInitialized（必须为 true）
+   *   2. 检查 _isDestroyed（不能已销毁）
+   *   3. 标记 _isActive = true
+   *   4. emit 'activated' 事件
+   * @returns {void}
+   */
+  activate() {
+    if (this._isDestroyed) return
+    if (!this._isInitialized) {
+      console.warn(`[Subsystem] ${this.name} 未初始化，不能激活`)
+      return
+    }
+    this._isActive = true
+    this.emit('activated', { name: this.name })
+  }
+
+  /**
+   * 停用子系统
+   * 默认行为：
+   *   1. 标记 _isActive = false
+   *   2. emit 'deactivated' 事件
+   * @returns {void}
+   */
+  deactivate() {
+    if (this._isDestroyed) return
+    this._isActive = false
+    this.emit('deactivated', { name: this.name })
+  }
+
+  /**
+   * 销毁子系统
+   * 默认行为：
+   *   1. 标记 _isDestroyed = true, _isActive = false, _isInitialized = false
+   *   2. 调用 removeAllListeners()
+   *   3. 释放引用
+   *   4. emit 'destroyed' 事件
+   * 子类重写时应调用 super.destroy()
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this._isDestroyed) return
+
+    this._isActive = false
+    this._isInitialized = false
+    this._isDestroyed = true
+
+    // 先 emit destroyed 事件（removeAllListeners 后 emit 无效）
+    this.emit('destroyed', { name: this.name })
+
+    // 清理事件监听器
+    this.removeAllListeners()
+
+    // 释放引用
+    this._eventBus = null
+    this._config = null
+    this._logger = null
+  }
+
+  // --------------------------------------------------------------------------
+  // Getter
+  // --------------------------------------------------------------------------
+
+  /**
+   * 子系统名称（子类可重写）
+   * @type {string}
+   */
+  get name() {
+    return this.constructor.name
+  }
+
+  /**
+   * 是否已初始化
+   * @type {boolean}
+   */
+  get isInitialized() {
+    return this._isInitialized
+  }
+
+  /**
+   * 是否已激活
+   * @type {boolean}
+   */
+  get isActive() {
+    return this._isActive
+  }
+
+  /**
+   * 是否已销毁
+   * @type {boolean}
+   */
+  get isDestroyed() {
+    return this._isDestroyed
+  }
+}
+
+export { Subsystem }

package/src/base/index.js

@@ -0,0 +1,6 @@
+// ============================================================================
+// Nimbus2D - 基类统一导出
+// ============================================================================
+
+export { EventEmitter } from './EventEmitter.js'
+export { Subsystem } from './Subsystem.js'

package/src/core/Application/AppState.js

@@ -0,0 +1,27 @@
+// ============================================================================
+// Nimbus2D - 应用状态枚举
+// ----------------------------------------------------------------------------
+// 定义 Application 启动器的所有合法状态。
+//
+// 状态转换流程：
+//   CREATED → STARTING → RUNNING → STOPPING → DESTROYED
+// ============================================================================
+
+/**
+ * 应用状态枚举
+ * @enum {string}
+ */
+const AppState = {
+  /** 已创建（初始状态） */
+  CREATED: 'CREATED',
+  /** 启动中 */
+  STARTING: 'STARTING',
+  /** 运行中 */
+  RUNNING: 'RUNNING',
+  /** 停止中 */
+  STOPPING: 'STOPPING',
+  /** 已销毁（终态） */
+  DESTROYED: 'DESTROYED'
+}
+
+export { AppState }