@nimbus2d/core 0.0.1

package/src/core/AssetManager/AssetTypes.js

@@ -0,0 +1,108 @@
+// ============================================================================
+// Nimbus2D - 资源类型定义
+// ----------------------------------------------------------------------------
+// 定义资源管理模块的所有枚举类型和错误类重导出。
+//
+// 包含：
+//   - ResourceType：资源类型枚举（8种）
+//   - ResourceState：资源状态枚举
+//   - LoadStrategy：加载策略枚举
+//   - ResourceEventType：事件类型枚举
+//   - 错误类重导出（从 errors/ResourceError.js）
+// ============================================================================
+
+/**
+ * 资源类型枚举
+ * @enum {string}
+ */
+const ResourceType = {
+  /** 图片（PNG/JPG/WebP/GIF） */
+  IMAGE: 'IMAGE',
+  /** 精灵图集（含帧动画数据） */
+  SPRITESHEET: 'SPRITESHEET',
+  /** 纹理图集（含区域划分数据） */
+  ATLAS: 'ATLAS',
+  /** 音频（第一期 PixiAdapter 不支持，需自定义适配器） */
+  AUDIO: 'AUDIO',
+  /** 字体 */
+  FONT: 'FONT',
+  /** 数据（JSON/XML/CSV） */
+  DATA: 'DATA',
+  /** 二进制 */
+  BINARY: 'BINARY',
+  /** 着色器（第一期 PixiAdapter 不支持，需自定义适配器） */
+  SHADER: 'SHADER'
+}
+
+/**
+ * 资源状态枚举
+ * @enum {string}
+ */
+const ResourceState = {
+  /** 已注册（未加载） */
+  REGISTERED: 'REGISTERED',
+  /** 加载中 */
+  LOADING: 'LOADING',
+  /** 已加载（可用） */
+  LOADED: 'LOADED',
+  /** 加载失败 */
+  ERROR: 'ERROR',
+  /** 已卸载 */
+  UNLOADED: 'UNLOADED'
+}
+
+/**
+ * 加载策略枚举
+ * @enum {string}
+ */
+const LoadStrategy = {
+  /** 懒加载：retain 时触发加载（默认） */
+  LAZY: 'LAZY',
+  /** 急加载：register 后立即加载 */
+  EAGER: 'EAGER',
+  /** 分组加载：需手动调用 loadGroup */
+  GROUP: 'GROUP'
+}
+
+/**
+ * 资源事件类型枚举
+ * @enum {string}
+ */
+const ResourceEventType = {
+  /** 资源已注册 */
+  REGISTERED: 'registered',
+  /** 资源已注销 */
+  UNREGISTERED: 'unregistered',
+  /** 加载开始 */
+  LOAD_START: 'load:start',
+  /** 加载完成 */
+  LOAD_COMPLETE: 'load:complete',
+  /** 加载失败 */
+  LOAD_ERROR: 'load:error',
+  /** 资源已卸载 */
+  UNLOAD: 'unload',
+  /** 资源被引用 */
+  RETAIN: 'retain',
+  /** 资源被释放 */
+  RELEASE: 'release',
+  /** 资源错误 */
+  ERROR: 'error'
+}
+
+// 重导出错误类（统一从 errors 模块导入）
+export {
+  ResourceError,
+  ResourceNotFoundError,
+  ResourceDuplicateError,
+  ResourceStateError,
+  ResourceLoadError,
+  AdapterError,
+  ResourceDestroyedError
+} from '../../errors/ResourceError.js'
+
+export {
+  ResourceType,
+  ResourceState,
+  LoadStrategy,
+  ResourceEventType
+}

package/src/core/AssetManager/adapters/IResourceAdapter.js

@@ -0,0 +1,50 @@
+// ============================================================================
+// Nimbus2D - 资源适配器接口
+// ----------------------------------------------------------------------------
+// 定义资源适配器的契约，所有适配器必须实现此接口。
+//
+// 设计决策：
+//   - 独立设计（不继承任何类）
+//   - 三个方法：load、unload、supports
+//   - load 返回 Promise<any>，unload 返回 Promise<void>
+// ============================================================================
+
+/**
+ * 资源适配器接口（基类）
+ * 所有资源适配器必须继承此类并实现其方法。
+ *
+ * 子类需要实现：
+ *   - load(entry): 加载资源
+ *   - unload(entry): 卸载资源
+ *   - supports(type): 检查是否支持指定类型
+ */
+class IResourceAdapter {
+  /**
+   * 加载资源
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   * @returns {Promise<any>} - 资源数据
+   */
+  async load(entry) {
+    throw new Error('IResourceAdapter.load() 必须由子类实现')
+  }
+
+  /**
+   * 卸载资源
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   * @returns {Promise<void>}
+   */
+  async unload(entry) {
+    throw new Error('IResourceAdapter.unload() 必须由子类实现')
+  }
+
+  /**
+   * 检查适配器是否支持指定资源类型
+   * @param {string} type - ResourceType 枚举值
+   * @returns {boolean}
+   */
+  supports(type) {
+    throw new Error('IResourceAdapter.supports() 必须由子类实现')
+  }
+}
+
+export { IResourceAdapter }

package/src/core/AssetManager/adapters/PixiAdapter.js

@@ -0,0 +1,90 @@
+// ============================================================================
+// Nimbus2D - PixiJS 资源适配器
+// ----------------------------------------------------------------------------
+// 桥接 PixiJS v8 Assets，支持 6 种资源类型。
+// 核心内置自动注册，无需用户手动添加。
+//
+// 支持的资源类型：
+//   IMAGE / SPRITESHEET / ATLAS / FONT / DATA / BINARY
+//
+// 不支持的类型（需用户自定义适配器）：
+//   AUDIO / SHADER
+// ============================================================================
+
+import { Assets } from 'pixi.js'
+import { IResourceAdapter } from './IResourceAdapter.js'
+import { ResourceType } from '../AssetTypes.js'
+
+class PixiAdapter extends IResourceAdapter {
+  /**
+   * 构造函数
+   * @param {object} pixi - PixiJS Application 实例
+   */
+  constructor(pixi) {
+    super()
+
+    /** @type {object} PixiJS Application 实例 */
+    this._pixi = pixi
+
+    /** @type {string[]} 支持的资源类型列表 */
+    this._supportedTypes = [
+      ResourceType.IMAGE,
+      ResourceType.SPRITESHEET,
+      ResourceType.ATLAS,
+      ResourceType.FONT,
+      ResourceType.DATA,
+      ResourceType.BINARY
+    ]
+  }
+
+  /**
+   * 加载资源（桥接 PixiJS v8 Assets.load）
+   * v8 签名：Assets.load(url) 或 Assets.load({ src, data, alias })
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   * @returns {Promise<any>} - 资源数据
+   */
+  async load(entry) {
+    // PixiJS v8 Assets.load 支持字符串或 LoadAsset 对象
+    const loadOptions = entry.adapterOptions || {}
+
+    // 构建加载参数
+    const loadAsset = { src: entry.src }
+    if (loadOptions.pixiData) {
+      loadAsset.data = loadOptions.pixiData
+    }
+    if (entry.alias) {
+      loadAsset.alias = entry.alias
+    }
+
+    return await Assets.load(loadAsset)
+  }
+
+  /**
+   * 卸载资源（桥接 PixiJS v8 Assets.unload）
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   * @returns {Promise<void>}
+   */
+  async unload(entry) {
+    // PixiJS v8 Assets.unload 按资源标识卸载
+    await Assets.unload(entry.src)
+  }
+
+  /**
+   * 检查是否支持指定资源类型
+   * @param {string} type - ResourceType 枚举值
+   * @returns {boolean}
+   */
+  supports(type) {
+    return this._supportedTypes.includes(type)
+  }
+
+  /**
+   * 支持的资源类型列表（只读）
+   * @type {string[]}
+   */
+  get supportedTypes() {
+    return this._supportedTypes
+  }
+}
+
+export { PixiAdapter }

package/src/core/AssetManager/core/RefCounter.js

@@ -0,0 +1,167 @@
+// ============================================================================
+// Nimbus2D - 引用计数器
+// ----------------------------------------------------------------------------
+// 管理资源的引用计数，支持按持有者（holder）追踪引用关系。
+//
+// 设计决策：
+//   - 主存储：Map<resourceId, number> 全局引用计数
+//   - 持有者映射：Map<holder, Map<resourceId, number>> 按持有者追踪
+//   - 支持按持有者批量释放
+// ============================================================================
+
+class RefCounter {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    /** @type {Map<string, number>} 全局引用计数（resourceId → count） */
+    this._counts = new Map()
+
+    /** @type {Map<string, Map<string, number>>} 持有者映射（holder → (resourceId → count)） */
+    this._holders = new Map()
+  }
+
+  // --------------------------------------------------------------------------
+  // 引用操作
+  // --------------------------------------------------------------------------
+
+  /**
+   * 增加引用计数
+   * @param {string} resourceId - 资源 ID
+   * @param {string} holder - 持有者标识
+   * @returns {number} 新的全局引用计数
+   */
+  retain(resourceId, holder) {
+    // 增加全局计数
+    const count = (this._counts.get(resourceId) || 0) + 1
+    this._counts.set(resourceId, count)
+
+    // 增加持有者计数
+    if (!this._holders.has(holder)) {
+      this._holders.set(holder, new Map())
+    }
+    const holderMap = this._holders.get(holder)
+    holderMap.set(resourceId, (holderMap.get(resourceId) || 0) + 1)
+
+    return count
+  }
+
+  /**
+   * 减少引用计数
+   * @param {string} resourceId - 资源 ID
+   * @param {string} holder - 持有者标识
+   * @returns {number} 新的全局引用计数（最小为 0）
+   */
+  release(resourceId, holder) {
+    let count = this._counts.get(resourceId) || 0
+
+    // 减少持有者计数
+    const holderMap = this._holders.get(holder)
+    if (holderMap && holderMap.has(resourceId)) {
+      const holderCount = holderMap.get(resourceId) - 1
+      if (holderCount <= 0) {
+        holderMap.delete(resourceId)
+        if (holderMap.size === 0) {
+          this._holders.delete(holder)
+        }
+      } else {
+        holderMap.set(resourceId, holderCount)
+      }
+
+      // 减少全局计数
+      count = Math.max(0, count - 1)
+      this._counts.set(resourceId, count)
+    }
+
+    return count
+  }
+
+  /**
+   * 释放持有者的所有引用
+   * @param {string} holder - 持有者标识
+   * @returns {string[]} 引用计数降为 0 的资源 ID 列表（可安全卸载）
+   */
+  releaseAllByHolder(holder) {
+    const holderMap = this._holders.get(holder)
+    if (!holderMap) return []
+
+    /** @type {string[]} 引用计数降为 0 的资源列表 */
+    const zeroRefIds = []
+
+    for (const [resourceId, holderCount] of holderMap) {
+      // 按持有者的引用数减少全局计数（持有者可能对同一资源多次 retain）
+      const count = Math.max(0, (this._counts.get(resourceId) || 0) - holderCount)
+      this._counts.set(resourceId, count)
+
+      if (count === 0) {
+        zeroRefIds.push(resourceId)
+      }
+    }
+
+    // 清空持有者映射
+    this._holders.delete(holder)
+
+    return zeroRefIds
+  }
+
+  // --------------------------------------------------------------------------
+  // 查询方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取资源的全局引用计数
+   * @param {string} resourceId - 资源 ID
+   * @returns {number}
+   */
+  getCount(resourceId) {
+    return this._counts.get(resourceId) || 0
+  }
+
+  /**
+   * 获取持有者对指定资源的引用计数
+   * @param {string} resourceId - 资源 ID
+   * @param {string} holder - 持有者标识
+   * @returns {number}
+   */
+  getHolderCount(resourceId, holder) {
+    const holderMap = this._holders.get(holder)
+    if (!holderMap) return 0
+    return holderMap.get(resourceId) || 0
+  }
+
+  /**
+   * 获取持有者引用的所有资源 ID
+   * @param {string} holder - 持有者标识
+   * @returns {string[]}
+   */
+  getHolderResources(holder) {
+    const holderMap = this._holders.get(holder)
+    return holderMap ? [...holderMap.keys()] : []
+  }
+
+  // --------------------------------------------------------------------------
+  // 清理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 清空所有引用计数
+   */
+  clear() {
+    this._counts.clear()
+    this._holders.clear()
+  }
+
+  /**
+   * 移除资源记录（资源被卸载时调用）
+   * @param {string} resourceId - 资源 ID
+   */
+  removeResource(resourceId) {
+    this._counts.delete(resourceId)
+    // 从所有持有者映射中移除
+    for (const holderMap of this._holders.values()) {
+      holderMap.delete(resourceId)
+    }
+  }
+}
+
+export { RefCounter }

package/src/core/AssetManager/core/ResourceCache.js

@@ -0,0 +1,281 @@
+// ============================================================================
+// Nimbus2D - 资源缓存
+// ----------------------------------------------------------------------------
+// 管理资源条目的存储、分组和标签索引。
+//
+// 设计决策：
+//   - 主存储使用 Map<string, ResourceEntry>
+//   - 分组索引使用 Map<string, Set<string>>
+//   - 标签索引使用 Map<string, Set<string>>
+//   - 支持按分组/标签批量查询
+// ============================================================================
+
+import { ResourceState } from '../AssetTypes.js'
+
+class ResourceCache {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    /** @type {Map<string, import('../core/ResourceEntry.js').ResourceEntry>} 主存储（id → entry） */
+    this._entries = new Map()
+
+    /** @type {Map<string, Set<string>>} 分组索引（groupName → id集合） */
+    this._groups = new Map()
+
+    /** @type {Map<string, Set<string>>} 标签索引（tagName → id集合） */
+    this._tags = new Map()
+  }
+
+  // --------------------------------------------------------------------------
+  // 条目操作
+  // --------------------------------------------------------------------------
+
+  /**
+   * 添加资源条目
+   * @param {import('../core/ResourceEntry.js').ResourceEntry} entry - 资源条目
+   */
+  add(entry) {
+    this._entries.set(entry.id, entry)
+
+    // 索引分组
+    if (entry.group) {
+      if (!this._groups.has(entry.group)) {
+        this._groups.set(entry.group, new Set())
+      }
+      this._groups.get(entry.group).add(entry.id)
+    }
+
+    // 索引标签
+    for (const tag of entry.tags) {
+      if (!this._tags.has(tag)) {
+        this._tags.set(tag, new Set())
+      }
+      this._tags.get(tag).add(entry.id)
+    }
+  }
+
+  /**
+   * 获取资源条目
+   * @param {string} id - 资源 ID
+   * @returns {import('../core/ResourceEntry.js').ResourceEntry|null}
+   */
+  get(id) {
+    return this._entries.get(id) || null
+  }
+
+  /**
+   * 是否存在资源
+   * @param {string} id - 资源 ID
+   * @returns {boolean}
+   */
+  has(id) {
+    return this._entries.has(id)
+  }
+
+  /**
+   * 删除资源条目
+   * @param {string} id - 资源 ID
+   * @returns {boolean} 是否删除成功
+   */
+  delete(id) {
+    const entry = this._entries.get(id)
+    if (!entry) return false
+
+    // 从分组索引中移除
+    if (entry.group && this._groups.has(entry.group)) {
+      this._groups.get(entry.group).delete(id)
+      // 空分组自动清理
+      if (this._groups.get(entry.group).size === 0) {
+        this._groups.delete(entry.group)
+      }
+    }
+
+    // 从标签索引中移除
+    for (const tag of entry.tags) {
+      if (this._tags.has(tag)) {
+        this._tags.get(tag).delete(id)
+        // 空标签自动清理
+        if (this._tags.get(tag).size === 0) {
+          this._tags.delete(tag)
+        }
+      }
+    }
+
+    return this._entries.delete(id)
+  }
+
+  // --------------------------------------------------------------------------
+  // 分组操作
+  // --------------------------------------------------------------------------
+
+  /**
+   * 创建分组
+   * @param {string} name - 分组名称
+   * @param {string[]} [ids=[]] - 初始资源 ID 列表
+   */
+  createGroup(name, ids = []) {
+    if (!this._groups.has(name)) {
+      this._groups.set(name, new Set())
+    }
+    for (const id of ids) {
+      this._groups.get(name).add(id)
+      // 同步更新条目的 group 字段（通过公共方法，避免直接访问私有属性）
+      const entry = this._entries.get(id)
+      if (entry && !entry.group) {
+        entry.setGroup(name)
+      }
+    }
+  }
+
+  /**
+   * 添加资源到分组
+   * @param {string} name - 分组名称
+   * @param {string} id - 资源 ID
+   */
+  addToGroup(name, id) {
+    if (!this._groups.has(name)) {
+      this._groups.set(name, new Set())
+    }
+    this._groups.get(name).add(id)
+  }
+
+  /**
+   * 从分组移除资源
+   * @param {string} name - 分组名称
+   * @param {string} id - 资源 ID
+   */
+  removeFromGroup(name, id) {
+    if (this._groups.has(name)) {
+      this._groups.get(name).delete(id)
+      if (this._groups.get(name).size === 0) {
+        this._groups.delete(name)
+      }
+    }
+  }
+
+  /**
+   * 获取分组内所有资源 ID
+   * @param {string} name - 分组名称
+   * @returns {string[]}
+   */
+  getGroupIds(name) {
+    const group = this._groups.get(name)
+    return group ? [...group] : []
+  }
+
+  /**
+   * 获取分组内所有资源条目
+   * @param {string} name - 分组名称
+   * @returns {import('../core/ResourceEntry.js').ResourceEntry[]}
+   */
+  getGroupEntries(name) {
+    const ids = this.getGroupIds(name)
+    return ids.map((id) => this._entries.get(id)).filter(Boolean)
+  }
+
+  /**
+   * 是否存在分组
+   * @param {string} name - 分组名称
+   * @returns {boolean}
+   */
+  hasGroup(name) {
+    return this._groups.has(name)
+  }
+
+  // --------------------------------------------------------------------------
+  // 标签操作
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取标签下所有资源 ID
+   * @param {string} tag - 标签名
+   * @returns {string[]}
+   */
+  getTagIds(tag) {
+    const tagSet = this._tags.get(tag)
+    return tagSet ? [...tagSet] : []
+  }
+
+  // --------------------------------------------------------------------------
+  // 查询方法
+  // --------------------------------------------------------------------------
+
+  /**
+   * 获取所有资源 ID
+   * @returns {string[]}
+   */
+  getAllIds() {
+    return [...this._entries.keys()]
+  }
+
+  /**
+   * 获取所有资源条目
+   * @returns {import('../core/ResourceEntry.js').ResourceEntry[]}
+   */
+  getAllEntries() {
+    return [...this._entries.values()]
+  }
+
+  /**
+   * 获取所有分组名称
+   * @returns {string[]}
+   */
+  getGroupNames() {
+    return [...this._groups.keys()]
+  }
+
+  /**
+   * 获取统计信息
+   * @returns {Object}
+   */
+  getStats() {
+    let loadedCount = 0
+    let loadingCount = 0
+    let errorCount = 0
+    let registeredCount = 0
+
+    for (const entry of this._entries.values()) {
+      // 使用 ResourceState 枚举值比较，避免硬编码字符串
+      switch (entry.state) {
+        case ResourceState.LOADED: loadedCount++; break
+        case ResourceState.LOADING: loadingCount++; break
+        case ResourceState.ERROR: errorCount++; break
+        case ResourceState.REGISTERED: registeredCount++; break
+      }
+    }
+
+    return {
+      total: this._entries.size,
+      loaded: loadedCount,
+      loading: loadingCount,
+      error: errorCount,
+      registered: registeredCount,
+      groups: this._groups.size,
+      tags: this._tags.size
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // 清理
+  // --------------------------------------------------------------------------
+
+  /**
+   * 清空所有缓存
+   */
+  clear() {
+    this._entries.clear()
+    this._groups.clear()
+    this._tags.clear()
+  }
+
+  /**
+   * 获取资源总数
+   * @type {number}
+   */
+  get size() {
+    return this._entries.size
+  }
+}
+
+export { ResourceCache }