@nimbus2d/core 0.0.1

package/src/core/AssetManager/core/ResourceEntry.js

@@ -0,0 +1,191 @@
+// ============================================================================
+// Nimbus2D - 资源条目
+// ----------------------------------------------------------------------------
+// 封装单个资源的元信息、状态和数据。
+//
+// 设计决策：
+//   - 资源 ID 作为唯一标识
+//   - 状态机：REGISTERED → LOADING → LOADED → UNLOADED / ERROR
+//   - 支持分组、标签、加载策略等元信息
+// ============================================================================
+
+import { ResourceState, LoadStrategy } from '../AssetTypes.js'
+
+class ResourceEntry {
+  /**
+   * 构造函数
+   * @param {string} id - 资源唯一标识
+   * @param {Object} options - 资源注册选项
+   * @param {string} options.type - 资源类型（ResourceType 枚举值）
+   * @param {string} options.src - 资源路径
+   * @param {string} [options.strategy=LoadStrategy.LAZY] - 加载策略
+   * @param {string} [options.group] - 分组名称
+   * @param {string[]} [options.tags=[]] - 标签列表
+   * @param {Object} [options.adapterOptions={}] - 适配器自定义选项
+   */
+  constructor(id, options) {
+    /** @type {string} 资源唯一标识 */
+    this._id = id
+
+    /** @type {string} 资源类型 */
+    this._type = options.type
+
+    /** @type {string} 资源路径 */
+    this._src = options.src
+
+    /** @type {string|null} 资源别名（用于 PixiJS Assets 缓存键） */
+    this._alias = options.alias || null
+
+    /** @type {LoadStrategy} 加载策略 */
+    this._strategy = options.strategy || LoadStrategy.LAZY
+
+    /** @type {string} 分组名称 */
+    this._group = options.group || ''
+
+    /** @type {string[]} 标签列表 */
+    this._tags = options.tags || []
+
+    /** @type {Object} 适配器自定义选项 */
+    this._adapterOptions = options.adapterOptions
+      ? options.adapterOptions
+      : (options.pixiData ? { pixiData: options.pixiData } : {})
+
+    /** @type {ResourceState} 当前状态 */
+    this._state = ResourceState.REGISTERED
+
+    /** @type {*} 资源数据（加载后填充） */
+    this._data = null
+
+    /** @type {Error|null} 加载错误（加载失败时填充） */
+    this._error = null
+
+    /** @type {number} 引用计数 */
+    this._refCount = 0
+  }
+
+  // --------------------------------------------------------------------------
+  // Getter
+  // --------------------------------------------------------------------------
+
+  /** @type {string} 资源 ID */
+  get id() { return this._id }
+
+  /** @type {string} 资源类型 */
+  get type() { return this._type }
+
+  /** @type {string} 资源路径 */
+  get src() { return this._src }
+
+  /** @type {string|null} 资源别名 */
+  get alias() { return this._alias }
+
+  /** @type {LoadStrategy} 加载策略 */
+  get strategy() { return this._strategy }
+
+  /** @type {string} 分组名称 */
+  get group() { return this._group }
+
+  /** @type {string[]} 标签列表 */
+  get tags() { return this._tags }
+
+  /** @type {Object} 适配器自定义选项 */
+  get adapterOptions() { return this._adapterOptions }
+
+  /** @type {ResourceState} 当前状态 */
+  get state() { return this._state }
+
+  /** @type {*} 资源数据 */
+  get data() { return this._data }
+
+  /** @type {Error|null} 加载错误 */
+  get error() { return this._error }
+
+  /** @type {number} 引用计数 */
+  get refCount() { return this._refCount }
+
+  /** @type {boolean} 是否已加载 */
+  get isLoaded() { return this._state === ResourceState.LOADED }
+
+  // --------------------------------------------------------------------------
+  // 状态变更
+  // --------------------------------------------------------------------------
+
+  /**
+   * 标记为加载中
+   */
+  setLoading() {
+    this._state = ResourceState.LOADING
+    this._error = null
+  }
+
+  /**
+   * 标记为已加载
+   * @param {*} data - 资源数据
+   */
+  setLoaded(data) {
+    this._state = ResourceState.LOADED
+    this._data = data
+    this._error = null
+  }
+
+  /**
+   * 标记为加载失败
+   * @param {Error} error - 错误
+   */
+  setError(error) {
+    this._state = ResourceState.ERROR
+    this._error = error
+  }
+
+  /**
+   * 标记为已卸载
+   */
+  setUnloaded() {
+    this._state = ResourceState.UNLOADED
+    this._data = null
+    this._error = null
+  }
+
+  /**
+   * 设置分组名称（仅当未设置分组时由 ResourceCache.createGroup 调用）
+   * @param {string} group - 分组名称
+   */
+  setGroup(group) {
+    if (!this._group) {
+      this._group = group
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 引用计数
+  // --------------------------------------------------------------------------
+
+  /**
+   * 增加引用计数
+   * @returns {number} 新的引用计数
+   */
+  addRef() {
+    this._refCount++
+    return this._refCount
+  }
+
+  /**
+   * 减少引用计数（最小为 0）
+   * @returns {number} 新的引用计数
+   */
+  releaseRef() {
+    if (this._refCount > 0) {
+      this._refCount--
+    }
+    return this._refCount
+  }
+
+  /**
+   * 重置引用计数为 0
+   */
+  resetRef() {
+    this._refCount = 0
+  }
+}
+
+export { ResourceEntry }

package/src/core/AssetManager/core/ResourceEventBus.js

@@ -0,0 +1,127 @@
+// ============================================================================
+// Nimbus2D - 资源内部事件总线
+// ----------------------------------------------------------------------------
+// 资源管理模块的内部事件通信通道，与核心 EventBus 解耦。
+//
+// 设计决策：
+//   - 轻量级实现，仅用于资源模块内部通信
+//   - 不依赖核心 EventBus（避免循环依赖）
+//   - 支持基本事件能力（on/off/emit/removeAllListeners）
+// ============================================================================
+
+class ResourceEventBus {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    /** @type {Map<string, Array<{fn: Function, once: boolean}>>} 事件监听器映射 */
+    this._listeners = new Map()
+  }
+
+  /**
+   * 注册事件监听器
+   * @param {string} event - 事件名称
+   * @param {Function} listener - 监听回调
+   * @returns {Function} 取消注册函数
+   */
+  on(event, listener) {
+    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._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) {
+    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)
+    if (list.length === 0) {
+      this._listeners.delete(event)
+    }
+    return true
+  }
+
+  /**
+   * 触发事件
+   * @param {string} event - 事件名称
+   * @param {...*} args - 传递给监听器的参数
+   * @returns {boolean} true 表示有监听器被调用
+   */
+  emit(event, ...args) {
+    const list = this._listeners.get(event)
+    if (!list || list.length === 0) return false
+
+    const snapshot = list.slice()
+    const toRemove = []
+
+    for (const entry of snapshot) {
+      try {
+        entry.fn(...args)
+      } catch (e) {
+        // 错误不中断其他监听器
+      }
+      if (entry.once) {
+        toRemove.push(entry)
+      }
+    }
+
+    for (const entry of toRemove) {
+      const index = list.indexOf(entry)
+      if (index !== -1) {
+        list.splice(index, 1)
+      }
+    }
+
+    if (list.length === 0) {
+      this._listeners.delete(event)
+    }
+
+    return true
+  }
+
+  /**
+   * 移除指定事件的所有监听器（不传参则移除所有）
+   * @param {string} [event] - 事件名称
+   */
+  removeAllListeners(event) {
+    if (event) {
+      this._listeners.delete(event)
+    } else {
+      this._listeners.clear()
+    }
+  }
+
+  /**
+   * 销毁
+   */
+  destroy() {
+    this._listeners.clear()
+  }
+}
+
+export { ResourceEventBus }

package/src/core/AssetManager/handlers/IResourceHandler.js

@@ -0,0 +1,45 @@
+// ============================================================================
+// Nimbus2D - 资源处理器接口
+// ----------------------------------------------------------------------------
+// 定义资源处理器的契约，处理器在资源加载/卸载完成时执行回调。
+//
+// 设计决策：
+//   - 独立设计（不继承任何类）
+//   - 两个回调：onLoadComplete、onLoadError、onUnload
+//   - 用于资源加载后的后处理（如缓存预热、数据校验等）
+// ============================================================================
+
+/**
+ * 资源处理器接口（基类）
+ * 资源处理器在资源加载完成、加载失败、卸载完成时接收通知，
+ * 可用于缓存预热、数据校验、统计记录等场景。
+ */
+class IResourceHandler {
+  /**
+   * 资源加载完成回调
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   * @param {*} data - 资源数据
+   */
+  onLoadComplete(entry, data) {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 资源加载失败回调
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   * @param {Error} error - 错误
+   */
+  onLoadError(entry, error) {
+    // 基类空实现，子类按需重写
+  }
+
+  /**
+   * 资源卸载完成回调
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   */
+  onUnload(entry) {
+    // 基类空实现，子类按需重写
+  }
+}
+
+export { IResourceHandler }

package/src/core/AssetManager/index.js

@@ -0,0 +1,26 @@
+// ============================================================================
+// Nimbus2D - AssetManager 模块统一导出
+// ============================================================================
+
+export { AssetManager } from './AssetManager.js'
+export {
+  ResourceType,
+  ResourceState,
+  LoadStrategy,
+  ResourceEventType,
+  ResourceError,
+  ResourceNotFoundError,
+  ResourceDuplicateError,
+  ResourceStateError,
+  ResourceLoadError,
+  AdapterError,
+  ResourceDestroyedError
+} from './AssetTypes.js'
+export { ResourceEntry } from './core/ResourceEntry.js'
+export { ResourceCache } from './core/ResourceCache.js'
+export { RefCounter } from './core/RefCounter.js'
+export { ResourceEventBus } from './core/ResourceEventBus.js'
+export { IResourceAdapter } from './adapters/IResourceAdapter.js'
+export { PixiAdapter } from './adapters/PixiAdapter.js'
+export { IResourceHandler } from './handlers/IResourceHandler.js'
+export { IResourcePlugin } from './plugins/IResourcePlugin.js'

package/src/core/AssetManager/plugins/IResourcePlugin.js

@@ -0,0 +1,56 @@
+// ============================================================================
+// Nimbus2D - 资源插件接口
+// ----------------------------------------------------------------------------
+// 定义资源插件的契约，插件通过钩子机制扩展资源管理行为。
+//
+// 设计决策：
+//   - 独立设计（不继承任何类）
+//   - 四个钩子：beforeLoad、afterLoad、beforeUnload、afterUnload
+//   - 钩子可返回 Promise，支持异步处理
+// ============================================================================
+
+/**
+ * 资源插件接口（基类）
+ * 资源插件通过 before/after 钩子在资源加载和卸载前后执行自定义逻辑，
+ * 可用于数据校验、格式转换、缓存预热、性能监控等。
+ */
+class IResourcePlugin {
+  /**
+   * 资源加载前钩子
+   * 可修改 entry（如添加适配器选项），返回修改后的 entry
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   * @returns {import('../core/ResourceEntry.js').ResourceEntry|Promise<import('../core/ResourceEntry.js').ResourceEntry>}
+   */
+  beforeLoad(entry) {
+    return entry
+  }
+
+  /**
+   * 资源加载后钩子
+   * 可修改 data（如数据转换），返回修改后的 data
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   * @param {*} data - 资源数据
+   * @returns {*|Promise<*>}
+   */
+  afterLoad(entry, data) {
+    return data
+  }
+
+  /**
+   * 资源卸载前钩子
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   */
+  beforeUnload(entry) {
+    // 基类空实现
+  }
+
+  /**
+   * 资源卸载后钩子
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   */
+  afterUnload(entry) {
+    // 基类空实现
+  }
+}
+
+export { IResourcePlugin }