@nimbus2d/core 0.0.1

package/src/core/AssetManager/AssetManager.js

@@ -0,0 +1,711 @@
+// ============================================================================
+// Nimbus2D - AssetManager 资源管理
+// ----------------------------------------------------------------------------
+// 职责：
+//   1. 门面 + 适配器（IResourceAdapter → PixiAdapter）+ 处理器 + 插件钩子
+//   2. 引用计数 + 缓存（分组+标签）+ 独立 EventBus
+//   3. 8 种资源类型：IMAGE/SPRITESHEET/ATLAS/AUDIO/FONT/DATA/BINARY/SHADER
+//   4. PixiAdapter 核心内置自动注册（支持 6 种类型）
+//   5. 3 种加载策略：LAZY/EAGER/GROUP
+//   6. 双通道事件广播（内部 EventBus + 核心 EventBus）
+//
+// 继承关系：
+//   EventEmitter → Subsystem → AssetManager（Lifecycle 内第二个初始化）
+// ============================================================================
+
+import { Subsystem } from '../../base/Subsystem.js'
+import { ResourceCache } from './core/ResourceCache.js'
+import { RefCounter } from './core/RefCounter.js'
+import { ResourceEventBus } from './core/ResourceEventBus.js'
+import { ResourceEntry } from './core/ResourceEntry.js'
+import { PixiAdapter } from './adapters/PixiAdapter.js'
+import {
+  ResourceType,
+  ResourceState,
+  LoadStrategy,
+  ResourceEventType,
+  ResourceNotFoundError,
+  ResourceDuplicateError,
+  ResourceStateError,
+  ResourceLoadError,
+  AdapterError,
+  ResourceDestroyedError
+} from './AssetTypes.js'
+
+class AssetManager extends Subsystem {
+  /**
+   * 构造函数
+   * @param {import('../EventBus/EventBus.js').EventBus} eventBus - 全局事件总线
+   * @param {import('../ConfigSystem/ConfigSystem.js').ConfigSystem} config - 配置系统实例
+   * @param {import('../Logger/Logger.js').Logger} logger - 日志系统实例
+   * @param {object} pixi - PixiJS Application 实例（用于 PixiAdapter 自动注册）
+   */
+  constructor(eventBus, config, logger, pixi) {
+    super(eventBus, config, logger)
+
+    /** @type {object} PixiJS Application 实例 */
+    this._pixi = pixi
+
+    /** @type {ResourceCache} 资源缓存 */
+    this._cache = new ResourceCache()
+
+    /** @type {RefCounter} 引用计数器 */
+    this._refCounter = new RefCounter()
+
+    /** @type {ResourceEventBus} 内部事件总线 */
+    this._internalBus = new ResourceEventBus()
+
+    /** @type {Map<string, import('./adapters/IResourceAdapter.js').IResourceAdapter>} 适配器映射（type → adapter） */
+    this._adapters = new Map()
+
+    /** @type {import('./handlers/IResourceHandler.js').IResourceHandler[]} 处理器列表 */
+    this._handlers = []
+
+    /** @type {import('./plugins/IResourcePlugin.js').IResourcePlugin[]} 插件列表 */
+    this._plugins = []
+
+    /** @type {Set<string>} 加载中的资源 ID（防止重复加载） */
+    this._loadingIds = new Set()
+  }
+
+  // --------------------------------------------------------------------------
+  // 适配器管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注册适配器
+   * @param {string} type - 资源类型（ResourceType 枚举值）
+   * @param {import('./adapters/IResourceAdapter.js').IResourceAdapter} adapter - 适配器实例
+   */
+  registerAdapter(type, adapter) {
+    if (this._isDestroyed) throw new ResourceDestroyedError()
+    this._adapters.set(type, adapter)
+  }
+
+  /**
+   * 注销适配器
+   * @param {string} type - 资源类型
+   * @returns {boolean} 是否注销成功
+   */
+  unregisterAdapter(type) {
+    return this._adapters.delete(type)
+  }
+
+  // --------------------------------------------------------------------------
+  // 处理器管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 添加处理器
+   * @param {import('./handlers/IResourceHandler.js').IResourceHandler} handler - 处理器实例
+   */
+  addHandler(handler) {
+    if (!this._handlers.includes(handler)) {
+      this._handlers.push(handler)
+    }
+  }
+
+  /**
+   * 移除处理器
+   * @param {import('./handlers/IResourceHandler.js').IResourceHandler} handler - 处理器实例
+   */
+  removeHandler(handler) {
+    const index = this._handlers.indexOf(handler)
+    if (index !== -1) {
+      this._handlers.splice(index, 1)
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 资源插件管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 添加资源插件
+   * @param {import('./plugins/IResourcePlugin.js').IResourcePlugin} plugin - 资源插件实例
+   */
+  addPlugin(plugin) {
+    if (!this._plugins.includes(plugin)) {
+      this._plugins.push(plugin)
+    }
+  }
+
+  /**
+   * 移除资源插件
+   * @param {import('./plugins/IResourcePlugin.js').IResourcePlugin} plugin - 资源插件实例
+   */
+  removePlugin(plugin) {
+    const index = this._plugins.indexOf(plugin)
+    if (index !== -1) {
+      this._plugins.splice(index, 1)
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 资源注册
+  // --------------------------------------------------------------------------
+
+  /**
+   * 注册资源
+   * @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={}] - 适配器选项
+   */
+  register(id, options) {
+    if (this._isDestroyed) throw new ResourceDestroyedError()
+
+    // 检查重复
+    if (this._cache.has(id)) {
+      throw new ResourceDuplicateError(id)
+    }
+
+    // 创建资源条目
+    const entry = new ResourceEntry(id, options)
+    this._cache.add(entry)
+
+    // 广播事件
+    this._emitEvent(ResourceEventType.REGISTERED, { id, entry })
+
+    // EAGER 策略：注册后立即加载
+    if (entry.strategy === LoadStrategy.EAGER) {
+      // 异步加载不等待，错误通过事件通知
+      this.load(id).catch(() => {})
+    }
+  }
+
+  /**
+   * 注销资源
+   * @param {string} id - 资源 ID
+   */
+  unregister(id) {
+    if (this._isDestroyed) throw new ResourceDestroyedError()
+
+    const entry = this._cache.get(id)
+    if (!entry) return
+
+    // 已加载的资源需先卸载
+    if (entry.isLoaded) {
+      this._doUnload(entry)
+    }
+
+    // 移除引用计数记录
+    this._refCounter.removeResource(id)
+
+    // 从缓存移除
+    this._cache.delete(id)
+
+    // 广播事件
+    this._emitEvent(ResourceEventType.UNREGISTERED, { id })
+  }
+
+  // --------------------------------------------------------------------------
+  // 资源加载
+  // --------------------------------------------------------------------------
+
+  /**
+   * 加载单个资源
+   * @param {string} id - 资源 ID
+   * @returns {Promise<*>} - 资源数据
+   */
+  async load(id) {
+    if (this._isDestroyed) throw new ResourceDestroyedError()
+
+    const entry = this._getEntryOrThrow(id)
+
+    // 已加载直接返回
+    if (entry.isLoaded) return entry.data
+
+    // 正在加载中，等待完成
+    if (entry.state === ResourceState.LOADING) {
+      return this._waitForLoad(id)
+    }
+
+    // 获取适配器
+    const adapter = this._getAdapterOrThrow(entry.type)
+
+    // 标记加载中
+    entry.setLoading()
+    this._loadingIds.add(id)
+    this._emitEvent(ResourceEventType.LOAD_START, { id })
+
+    try {
+      // 执行 beforeLoad 插件钩子
+      let modifiedEntry = entry
+      for (const plugin of this._plugins) {
+        modifiedEntry = await plugin.beforeLoad(modifiedEntry)
+      }
+
+      // 通过适配器加载
+      const data = await adapter.load(modifiedEntry)
+
+      // 执行 afterLoad 插件钩子
+      let modifiedData = data
+      for (const plugin of this._plugins) {
+        modifiedData = await plugin.afterLoad(modifiedEntry, modifiedData)
+      }
+
+      // 标记已加载
+      entry.setLoaded(modifiedData)
+
+      // 通知处理器
+      for (const handler of this._handlers) {
+        try {
+          handler.onLoadComplete(entry, modifiedData)
+        } catch (e) {
+          // 处理器错误不影响加载流程
+        }
+      }
+
+      // 广播事件
+      this._emitEvent(ResourceEventType.LOAD_COMPLETE, { id, data: modifiedData })
+
+      return modifiedData
+    } catch (e) {
+      // 标记加载失败
+      const error = e instanceof Error ? e : new Error(String(e))
+      entry.setError(error)
+
+      // 通知处理器
+      for (const handler of this._handlers) {
+        try {
+          handler.onLoadError(entry, error)
+        } catch (handlerErr) {
+          // 处理器错误不影响错误流程
+        }
+      }
+
+      // 广播事件
+      this._emitEvent(ResourceEventType.LOAD_ERROR, { id, error })
+      this._emitEvent(ResourceEventType.ERROR, { id, error })
+
+      throw new ResourceLoadError(id, error)
+    } finally {
+      this._loadingIds.delete(id)
+    }
+  }
+
+  /**
+   * 加载多个资源
+   * @param {string[]} ids - 资源 ID 列表
+   * @returns {Promise<Map<string, *>>} - 资源数据映射（id → data）
+   */
+  async loadAll(ids) {
+    const results = new Map()
+    const promises = ids.map(async (id) => {
+      const data = await this.load(id)
+      results.set(id, data)
+    })
+    await Promise.all(promises)
+    return results
+  }
+
+  /**
+   * 加载分组
+   * @param {string} groupName - 分组名称
+   * @returns {Promise<Map<string, *>>} - 资源数据映射
+   */
+  async loadGroup(groupName) {
+    const ids = this._cache.getGroupIds(groupName)
+    return this.loadAll(ids)
+  }
+
+  // --------------------------------------------------------------------------
+  // 资源卸载
+  // --------------------------------------------------------------------------
+
+  /**
+   * 卸载单个资源
+   * @param {string} id - 资源 ID
+   * @returns {Promise<void>}
+   */
+  async unload(id) {
+    if (this._isDestroyed) throw new ResourceDestroyedError()
+
+    const entry = this._cache.get(id)
+    if (!entry) return
+
+    // 引用计数 > 0 时不卸载
+    if (this._refCounter.getCount(id) > 0) {
+      this._safeLog('warn', `资源 ${id} 引用计数 > 0，跳过卸载`)
+      return
+    }
+
+    await this._doUnload(entry)
+  }
+
+  /**
+   * 卸载分组
+   * @param {string} groupName - 分组名称
+   * @returns {Promise<void>}
+   */
+  async unloadGroup(groupName) {
+    const entries = this._cache.getGroupEntries(groupName)
+    for (const entry of entries) {
+      if (this._refCounter.getCount(entry.id) === 0) {
+        await this._doUnload(entry)
+      }
+    }
+  }
+
+  /**
+   * 清空所有资源
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    const entries = this._cache.getAllEntries()
+    for (const entry of entries) {
+      try {
+        if (entry.isLoaded) {
+          await this._doUnload(entry)
+        }
+      } catch (e) {
+        // 清空阶段错误不中断
+      }
+    }
+    this._cache.clear()
+    this._refCounter.clear()
+  }
+
+  // --------------------------------------------------------------------------
+  // 引用计数
+  // --------------------------------------------------------------------------
+
+  /**
+   * 引用资源（异步，LAZY 策略时触发加载）
+   * @param {string} id - 资源 ID
+   * @param {string} holder - 持有者标识（如场景名）
+   * @returns {Promise<*>} - 资源数据
+   */
+  async retain(id, holder) {
+    if (this._isDestroyed) throw new ResourceDestroyedError()
+
+    this._getEntryOrThrow(id)
+
+    // 增加引用计数
+    this._refCounter.retain(id, holder)
+
+    // 广播事件
+    this._emitEvent(ResourceEventType.RETAIN, { id, holder })
+
+    // 如果未加载，触发加载
+    const entry = this._cache.get(id)
+    if (entry && !entry.isLoaded && entry.state !== ResourceState.LOADING) {
+      return this.load(id)
+    }
+
+    return entry ? entry.data : null
+  }
+
+  /**
+   * 释放引用
+   * @param {string} id - 资源 ID
+   * @param {string} holder - 持有者标识
+   */
+  release(id, holder) {
+    if (this._isDestroyed) return
+
+    const newCount = this._refCounter.release(id, holder)
+
+    // 广播事件
+    this._emitEvent(ResourceEventType.RELEASE, { id, holder })
+
+    // 引用计数为 0 时，可根据配置决定是否自动卸载
+    // 目前不自动卸载，由用户手动调用 unload 或 unloadGroup
+  }
+
+  /**
+   * 释放 holder 的所有引用
+   * @param {string} holder - 持有者标识
+   */
+  releaseAllByHolder(holder) {
+    this._refCounter.releaseAllByHolder(holder)
+  }
+
+  // --------------------------------------------------------------------------
+  // 分组管理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 创建分组
+   * @param {string} name - 分组名称
+   * @param {string[]} [ids=[]] - 初始资源 ID 列表
+   */
+  createGroup(name, ids = []) {
+    this._cache.createGroup(name, ids)
+  }
+
+  /**
+   * 添加到分组
+   * @param {string} name - 分组名称
+   * @param {string} id - 资源 ID
+   */
+  addToGroup(name, id) {
+    this._cache.addToGroup(name, id)
+  }
+
+  /**
+   * 从分组移除
+   * @param {string} name - 分组名称
+   * @param {string} id - 资源 ID
+   */
+  removeFromGroup(name, id) {
+    this._cache.removeFromGroup(name, id)
+  }
+
+  // --------------------------------------------------------------------------
+  // 查询方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取资源数据
+   * @param {string} id - 资源 ID
+   * @returns {*|null} 资源数据，未加载返回 null
+   */
+  get(id) {
+    const entry = this._cache.get(id)
+    return entry && entry.isLoaded ? entry.data : null
+  }
+
+  /**
+   * 是否已注册
+   * @param {string} id - 资源 ID
+   * @returns {boolean}
+   */
+  has(id) {
+    return this._cache.has(id)
+  }
+
+  /**
+   * 获取资源状态
+   * @param {string} id - 资源 ID
+   * @returns {string|null} ResourceState 枚举值，未找到返回 null
+   */
+  getState(id) {
+    const entry = this._cache.get(id)
+    return entry ? entry.state : null
+  }
+
+  /**
+   * 获取资源条目
+   * @param {string} id - 资源 ID
+   * @returns {ResourceEntry|null}
+   */
+  getEntry(id) {
+    return this._cache.get(id)
+  }
+
+  /**
+   * 获取统计信息
+   * @returns {Object}
+   */
+  getStats() {
+    return this._cache.getStats()
+  }
+
+  // --------------------------------------------------------------------------
+  // 生命周期（继承自 Subsystem）
+  // --------------------------------------------------------------------------
+
+  /**
+   * 初始化：自动注册 PixiAdapter
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    await super.initialize()
+
+    // 自动注册 PixiAdapter（核心内置）
+    if (this._pixi) {
+      const pixiAdapter = new PixiAdapter(this._pixi)
+      // 为 PixiAdapter 支持的 6 种类型各注册一次（通过公共 getter 访问）
+      for (const type of pixiAdapter.supportedTypes) {
+        this._adapters.set(type, pixiAdapter)
+      }
+    }
+  }
+
+  /**
+   * 销毁：清理所有资源
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this._isDestroyed) return
+
+    // 清理所有资源（错误不中断）
+    try {
+      await this.clear()
+    } catch (e) {
+      // 忽略清理错误
+    }
+
+    // 清理适配器
+    this._adapters.clear()
+
+    // 清理处理器和插件
+    this._handlers = []
+    this._plugins = []
+
+    // 销毁内部事件总线
+    this._internalBus.destroy()
+    this._internalBus = null
+
+    // 清理缓存和引用计数
+    this._cache.clear()
+    this._refCounter.clear()
+
+    this._pixi = null
+    this._loadingIds.clear()
+
+    await super.destroy()
+  }
+
+  // --------------------------------------------------------------------------
+  // 私有方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取资源条目，不存在则抛错
+   * @param {string} id - 资源 ID
+   * @returns {ResourceEntry}
+   * @throws {ResourceNotFoundError}
+   * @private
+   */
+  _getEntryOrThrow(id) {
+    const entry = this._cache.get(id)
+    if (!entry) {
+      throw new ResourceNotFoundError(id)
+    }
+    return entry
+  }
+
+  /**
+   * 获取适配器，不存在则抛错
+   * @param {string} type - 资源类型
+   * @returns {import('./adapters/IResourceAdapter.js').IResourceAdapter}
+   * @throws {AdapterError}
+   * @private
+   */
+  _getAdapterOrThrow(type) {
+    const adapter = this._adapters.get(type)
+    if (!adapter) {
+      throw new AdapterError(`未找到资源类型 ${type} 的适配器`)
+    }
+    return adapter
+  }
+
+  /**
+   * 执行卸载逻辑
+   * @param {ResourceEntry} entry - 资源条目
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _doUnload(entry) {
+    if (!entry.isLoaded) return
+
+    const adapter = this._adapters.get(entry.type)
+
+    try {
+      // 执行 beforeUnload 插件钩子
+      for (const plugin of this._plugins) {
+        plugin.beforeUnload(entry)
+      }
+
+      // 通过适配器卸载
+      if (adapter) {
+        await adapter.unload(entry)
+      }
+
+      // 执行 afterUnload 插件钩子
+      for (const plugin of this._plugins) {
+        plugin.afterUnload(entry)
+      }
+
+      // 标记已卸载
+      entry.setUnloaded()
+
+      // 通知处理器
+      for (const handler of this._handlers) {
+        try {
+          handler.onUnload(entry)
+        } catch (e) {
+          // 处理器错误不影响卸载流程
+        }
+      }
+
+      // 广播事件
+      this._emitEvent(ResourceEventType.UNLOAD, { id: entry.id })
+    } catch (e) {
+      // 卸载错误记录但不中断
+      this._safeLog('error', `资源 ${entry.id} 卸载失败`, { error: e })
+    }
+  }
+
+  /**
+   * 等待资源加载完成
+   * @param {string} id - 资源 ID
+   * @returns {Promise<*>} - 资源数据
+   * @private
+   */
+  _waitForLoad(id) {
+    return new Promise((resolve, reject) => {
+      // 监听加载完成或失败
+      const offComplete = this._internalBus.on(ResourceEventType.LOAD_COMPLETE, (payload) => {
+        if (payload.id === id) {
+          offComplete()
+          offError()
+          resolve(payload.data)
+        }
+      })
+
+      const offError = this._internalBus.on(ResourceEventType.LOAD_ERROR, (payload) => {
+        if (payload.id === id) {
+          offComplete()
+          offError()
+          reject(new ResourceLoadError(id, payload.error))
+        }
+      })
+    })
+  }
+
+  /**
+   * 双通道事件广播
+   * @param {string} eventType - 事件类型
+   * @param {Object} payload - 事件数据
+   * @private
+   */
+  _emitEvent(eventType, payload) {
+    // 内部通道
+    this._internalBus.emit(eventType, payload)
+    // 核心通道（带 asset: 前缀）
+    if (this._eventBus) {
+      try {
+        this._eventBus.emit(`asset:${eventType}`, payload)
+      } catch (e) {
+        // EventBus 错误不影响资源管理流程
+      }
+    }
+  }
+
+  /**
+   * 防御性日志方法
+   * @param {string} level - 日志级别
+   * @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 { AssetManager }