@nimbus2d/core 0.0.1

package/src/errors/SceneError.js

@@ -0,0 +1,124 @@
+// ============================================================================
+// Nimbus2D - 场景系统错误类
+// ----------------------------------------------------------------------------
+// 包含 SceneError、SceneNotFoundError、SceneDuplicateError、
+// SceneStateError、TransitionError
+// 注意：使用 sceneName getter（不重写 Error.name）
+// ============================================================================
+
+import { NimbusError } from './NimbusError.js'
+
+/**
+ * 场景系统错误基类
+ * @extends NimbusError
+ */
+class SceneError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='SCENE_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'SCENE_ERROR', cause = null) {
+    super(message, code, 'SceneManager', cause)
+  }
+}
+
+/**
+ * 场景未找到错误
+ * @extends SceneError
+ */
+class SceneNotFoundError extends SceneError {
+  /**
+   * 构造函数
+   * @param {string} sceneName - 场景名称
+   */
+  constructor(sceneName) {
+    super(`场景未找到：${sceneName}`, 'SCENE_NOT_FOUND')
+    /** @type {string} 场景名称 */
+    this._sceneName = sceneName
+  }
+
+  /** @type {string} 场景名称 */
+  get sceneName() {
+    return this._sceneName
+  }
+}
+
+/**
+ * 场景重复注册错误
+ * @extends SceneError
+ */
+class SceneDuplicateError extends SceneError {
+  /**
+   * 构造函数
+   * @param {string} sceneName - 场景名称
+   */
+  constructor(sceneName) {
+    super(`场景重复注册：${sceneName}`, 'SCENE_DUPLICATE')
+    /** @type {string} 场景名称 */
+    this._sceneName = sceneName
+  }
+
+  /** @type {string} 场景名称 */
+  get sceneName() {
+    return this._sceneName
+  }
+}
+
+/**
+ * 场景状态错误
+ * @extends SceneError
+ */
+class SceneStateError extends SceneError {
+  /**
+   * 构造函数
+   * @param {string} sceneName - 场景名称
+   * @param {string} currentState - 当前状态
+   * @param {string} expectedState - 期望状态
+   */
+  constructor(sceneName, currentState, expectedState) {
+    super(
+      `场景 ${sceneName} 状态错误：当前 ${currentState}，期望 ${expectedState}`,
+      'SCENE_STATE'
+    )
+    /** @type {string} 场景名称 */
+    this._sceneName = sceneName
+    /** @type {string} 当前状态 */
+    this._currentState = currentState
+    /** @type {string} 期望状态 */
+    this._expectedState = expectedState
+  }
+
+  /** @type {string} 场景名称 */
+  get sceneName() {
+    return this._sceneName
+  }
+
+  /** @type {string} 当前状态 */
+  get currentState() {
+    return this._currentState
+  }
+
+  /** @type {string} 期望状态 */
+  get expectedState() {
+    return this._expectedState
+  }
+}
+
+/**
+ * 过渡效果错误
+ * @extends SceneError
+ */
+class TransitionError extends SceneError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, cause = null) {
+    super(message, 'TRANSITION_ERROR', cause)
+  }
+}
+
+export { SceneError, SceneNotFoundError, SceneDuplicateError, SceneStateError, TransitionError }

package/src/errors/SubsystemError.js

@@ -0,0 +1,68 @@
+// ============================================================================
+// Nimbus2D - 子系统错误类
+// ----------------------------------------------------------------------------
+// 包含 SubsystemError 和 SubsystemStateError
+// Subsystem.initialize() 状态检查时抛出 SubsystemStateError（非 LifecycleError）
+// ============================================================================
+
+import { NimbusError } from './NimbusError.js'
+
+/**
+ * 子系统错误基类
+ * 所有 SubsystemError 子类构造函数设置 module='Subsystem'
+ * @extends NimbusError
+ */
+class SubsystemError extends NimbusError {
+  /**
+   * 构造函数
+   * @param {string} message - 错误消息
+   * @param {string} [code='SUBSYSTEM_ERROR'] - 错误码
+   * @param {Error|null} [cause=null] - 原始错误
+   */
+  constructor(message, code = 'SUBSYSTEM_ERROR', cause = null) {
+    super(message, code, 'Subsystem', cause)
+  }
+}
+
+/**
+ * 子系统状态错误
+ * 子系统 initialize() 时状态检查不通过抛出此错误
+ * @extends SubsystemError
+ */
+class SubsystemStateError extends SubsystemError {
+  /**
+   * 构造函数
+   * @param {string} subsystemName - 子系统名称
+   * @param {string} currentState - 当前状态
+   * @param {string[]} expectedStates - 期望状态列表
+   */
+  constructor(subsystemName, currentState, expectedStates) {
+    super(
+      `子系统 ${subsystemName} 状态错误：当前 ${currentState}，期望 ${expectedStates.join(' 或 ')}`,
+      'SUBSYSTEM_STATE'
+    )
+    /** @type {string} 子系统名称 */
+    this._subsystemName = subsystemName
+    /** @type {string} 当前状态 */
+    this._currentState = currentState
+    /** @type {string[]} 期望状态列表 */
+    this._expectedStates = expectedStates
+  }
+
+  /** @type {string} 子系统名称 */
+  get subsystemName() {
+    return this._subsystemName
+  }
+
+  /** @type {string} 当前状态 */
+  get currentState() {
+    return this._currentState
+  }
+
+  /** @type {string[]} 期望状态列表 */
+  get expectedStates() {
+    return this._expectedStates
+  }
+}
+
+export { SubsystemError, SubsystemStateError }

package/src/errors/index.js

@@ -0,0 +1,53 @@
+// ============================================================================
+// Nimbus2D - 错误类统一导出
+// ----------------------------------------------------------------------------
+// 导出所有框架错误类，按模块分组
+// ============================================================================
+
+// 基础错误类
+export { NimbusError } from './NimbusError.js'
+
+// 子系统错误
+export { SubsystemError, SubsystemStateError } from './SubsystemError.js'
+
+// 配置系统错误
+export { ConfigError, ConfigPathError } from './ConfigError.js'
+
+// 资源系统错误
+export {
+  ResourceError,
+  ResourceNotFoundError,
+  ResourceDuplicateError,
+  ResourceStateError,
+  ResourceLoadError,
+  AdapterError,
+  ResourceDestroyedError
+} from './ResourceError.js'
+
+// 插件系统错误
+export {
+  PluginError,
+  PluginNotFoundError,
+  PluginDuplicateError,
+  PluginDependencyError,
+  PluginStateError
+} from './PluginError.js'
+
+// 场景系统错误
+export {
+  SceneError,
+  SceneNotFoundError,
+  SceneDuplicateError,
+  SceneStateError,
+  TransitionError
+} from './SceneError.js'
+
+// 生命周期错误
+export { LifecycleError, LifecycleStateError } from './LifecycleError.js'
+
+// 对象池错误
+export {
+  PoolError,
+  PoolStateError,
+  PoolExhaustedError
+} from '../core/PoolManager/PoolTypes.js'

package/src/index.js

@@ -0,0 +1,86 @@
+// ============================================================================
+// Nimbus2D 游戏框架 - 统一入口
+// ----------------------------------------------------------------------------
+// 项目定位：
+//   Nimbus2D 是基于 PixiJS v8 的微内核 + 插件化 2D 游戏开发框架。
+//   本文件是框架的统一导出入口。
+//
+// 设计哲学（详见《总体架构文档.md》）：
+//   1. 微内核 + 插件化：核心精简稳定，非核心能力以插件形式提供
+//   2. 数据驱动：对象严禁使用中文 key，所有数据应存在数据库中
+//   3. 模块化分离：按职责划分模块，单文件控制在 400 行内（特殊不超过 700 行）
+//   4. 接口稳定：核心 API 一旦确定，不轻易变更
+// ============================================================================
+
+// === 基类 ===
+export { EventEmitter } from './base/EventEmitter.js'
+export { Subsystem } from './base/Subsystem.js'
+
+// === 核心模块 ===
+export { Application, AppState, DefaultConfig } from './core/Application/index.js'
+export { PluginSystem, Plugin, PluginEntry, PluginState } from './core/PluginSystem/index.js'
+export { Lifecycle, LifecycleState } from './core/Lifecycle/index.js'
+export { EventBus, Interceptor, PerformanceStats } from './core/EventBus/index.js'
+export { SceneManager, Scene, SceneState, Transition, FadeTransition, SlideTransition, MaskTransition, ZoomTransition } from './core/SceneManager/index.js'
+export {
+  AssetManager, ResourceType, ResourceState, LoadStrategy, ResourceEventType,
+  ResourceEntry, ResourceCache, RefCounter, ResourceEventBus,
+  IResourceAdapter, PixiAdapter, IResourceHandler, IResourcePlugin
+} from './core/AssetManager/index.js'
+export {
+  ConfigSystem, ConfigLayer, ConfigLayerType, ConfigPath,
+  ConfigWatcher, ConfigMerger, ConfigTypes
+} from './core/ConfigSystem/index.js'
+export { Logger, LogLevel, LogHandler, ConsoleHandler } from './core/Logger/index.js'
+export {
+  PoolManager, ObjectPool, PoolState,
+  PoolDefaultConfig
+} from './core/PoolManager/index.js'
+
+// === 四期新增：GPU 渲染核心 ===
+export {
+  SpriteGPULayer,
+  SpriteGPULayerEventType,
+  SpriteGPULayerError
+} from './core/SpriteGPULayer/index.js'
+
+// === 四期新增：高级视口相机 ===
+export {
+  Camera,
+  CameraEventType,
+  CameraError
+} from './core/Camera/index.js'
+
+// === 四期新增：Timeline 动画引擎 ===
+export {
+  Timeline,
+  Track,
+  Clip,
+  Easing,
+  BUILTIN_EASINGS,
+  TimelineEventType,
+  TimelineState,
+  TimelineError,
+  TimelineDefaultConfig
+} from './core/Timeline/index.js'
+
+// === 错误类 ===
+export {
+  NimbusError,
+  SubsystemError, SubsystemStateError,
+  ConfigError, ConfigPathError,
+  ResourceError, ResourceNotFoundError, ResourceDuplicateError,
+  ResourceStateError, ResourceLoadError, AdapterError, ResourceDestroyedError,
+  PluginError, PluginNotFoundError, PluginDuplicateError,
+  PluginDependencyError, PluginStateError,
+  SceneError, SceneNotFoundError, SceneDuplicateError,
+  SceneStateError, TransitionError,
+  LifecycleError, LifecycleStateError,
+  PoolError, PoolStateError, PoolExhaustedError
+} from './errors/index.js'
+
+// 注：CameraError 和 TimelineError 已在各自模块的导出区块中导出
+// （与 Camera/Timeline 模块独立性设计一致，错误类由模块自身维护）
+
+// === 工具类 ===
+export { MemoryChecker } from './utils/MemoryChecker.js'

package/src/types/index.js

@@ -0,0 +1,141 @@
+// ============================================================================
+// Nimbus2D - 类型定义（JSDoc typedef）
+// ----------------------------------------------------------------------------
+// 框架的公共类型定义文件，使用 JSDoc 语法定义。
+// 纯 JavaScript 项目不使用 TypeScript，通过 JSDoc 提供类型提示。
+//
+// 注意：此文件仅用于 IDE 类型提示，实际运行时使用各模块的枚举定义。
+// 枚举值必须与各模块的实际定义保持完全一致。
+// ============================================================================
+
+/**
+ * 应用状态枚举（与 Application/AppState.js 保持一致）
+ * @enum {string}
+ */
+export const AppState = {
+  CREATED: 'CREATED',
+  STARTING: 'STARTING',
+  RUNNING: 'RUNNING',
+  STOPPING: 'STOPPING',
+  DESTROYED: 'DESTROYED'
+}
+
+/**
+ * 插件状态枚举（与 PluginSystem/PluginState.js 保持一致）
+ * @enum {string}
+ */
+export const PluginState = {
+  REGISTERED: 'REGISTERED',
+  INSTALLING: 'INSTALLING',
+  INSTALLED: 'INSTALLED',
+  UNINSTALLING: 'UNINSTALLING',
+  UNREGISTERED: 'UNREGISTERED',
+  ERROR: 'ERROR'
+}
+
+/**
+ * 生命周期状态枚举（与 Lifecycle/LifecycleState.js 保持一致）
+ * @enum {string}
+ */
+export const LifecycleState = {
+  CREATED: 'CREATED',
+  INITIALIZING: 'INITIALIZING',
+  INITIALIZED: 'INITIALIZED',
+  ACTIVE: 'ACTIVE',
+  PAUSED: 'PAUSED',
+  DESTROYING: 'DESTROYING',
+  DESTROYED: 'DESTROYED'
+}
+
+/**
+ * 场景状态枚举（与 SceneManager/SceneState.js 保持一致）
+ * @enum {string}
+ */
+export const SceneState = {
+  REGISTERED: 'REGISTERED',
+  STARTING: 'STARTING',
+  RUNNING: 'RUNNING',
+  PAUSED: 'PAUSED',
+  STOPPED: 'STOPPED',
+  DESTROYED: 'DESTROYED'
+}
+
+/**
+ * 资源类型枚举（与 AssetManager/AssetTypes.js 保持一致）
+ * @enum {string}
+ */
+export const ResourceType = {
+  IMAGE: 'IMAGE',
+  SPRITESHEET: 'SPRITESHEET',
+  ATLAS: 'ATLAS',
+  AUDIO: 'AUDIO',
+  FONT: 'FONT',
+  DATA: 'DATA',
+  BINARY: 'BINARY',
+  SHADER: 'SHADER'
+}
+
+/**
+ * 资源状态枚举（与 AssetManager/AssetTypes.js 保持一致）
+ * @enum {string}
+ */
+export const ResourceState = {
+  REGISTERED: 'REGISTERED',
+  LOADING: 'LOADING',
+  LOADED: 'LOADED',
+  ERROR: 'ERROR',
+  UNLOADED: 'UNLOADED'
+}
+
+/**
+ * 加载策略枚举（与 AssetManager/AssetTypes.js 保持一致）
+ * @enum {string}
+ */
+export const LoadStrategy = {
+  LAZY: 'LAZY',
+  EAGER: 'EAGER',
+  GROUP: 'GROUP'
+}
+
+/**
+ * 日志级别枚举（与 Logger/LogLevel.js 保持一致）
+ * @enum {number}
+ */
+export const LogLevel = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  NONE: 4
+}
+
+/**
+ * 配置层类型枚举（与 ConfigSystem/ConfigLayerType.js 保持一致）
+ * @enum {string}
+ */
+export const ConfigLayerType = {
+  DEFAULT: 'default',
+  MODULE: 'module',
+  USER: 'user',
+  RUNTIME: 'runtime'
+}
+
+/**
+ * 应用默认配置
+ * @type {Object}
+ */
+export const DEFAULT_CONFIG = {
+  pixi: {
+    width: 800,
+    height: 600,
+    backgroundColor: 0x000000,
+    antialias: true,
+    alpha: false,
+    resolution: 0
+  },
+  modules: {
+    logger: {
+      level: 1
+    }
+  }
+}