@esengine/ecs-framework 2.1.43 → 2.1.44

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.43
+ * @esengine/ecs-framework v2.1.44
  * TypeScript definitions
  */
 /**
@@ -1838,6 +1838,9 @@ declare class SoAStorage<T extends Component> {
     private resize;
     getActiveIndices(): number[];
     getFieldArray(fieldName: string): Float32Array | Float64Array | Int32Array | null;
+    getTypedFieldArray<K extends keyof T>(fieldName: K): Float32Array | Float64Array | Int32Array | null;
+    getEntityIndex(entityId: number): number | undefined;
+    getEntityIdByIndex(index: number): number | undefined;
     size(): number;
     clear(): void;
     compact(): void;
@@ -2021,6 +2024,52 @@ declare class ComponentStorage<T extends Component> {
 declare class ComponentStorageManager {
     private static readonly _logger;
     private storages;
+    /**
+     * 检查组件类型是否启用SoA存储
+     * @param componentType 组件类型
+     * @returns 是否为SoA存储
+     */
+    isSoAStorage<T extends Component>(componentType: ComponentType<T>): boolean;
+    /**
+     * 获取SoA存储器（类型安全）
+     * @param componentType 组件类型
+     * @returns SoA存储器或null
+     */
+    getSoAStorage<T extends Component>(componentType: ComponentType<T>): SoAStorage<T> | null;
+    /**
+     * 直接获取SoA字段数组（类型安全）
+     * @param componentType 组件类型
+     * @param fieldName 字段名
+     * @returns TypedArray或null
+     */
+    getFieldArray<T extends Component>(componentType: ComponentType<T>, fieldName: string): Float32Array | Float64Array | Int32Array | null;
+    /**
+     * 直接获取SoA字段数组（类型安全，带字段名检查）
+     * @param componentType 组件类型
+     * @param fieldName 字段名（类型检查）
+     * @returns TypedArray或null
+     */
+    getTypedFieldArray<T extends Component, K extends keyof T>(componentType: ComponentType<T>, fieldName: K): Float32Array | Float64Array | Int32Array | null;
+    /**
+     * 获取SoA存储的活跃索引
+     * @param componentType 组件类型
+     * @returns 活跃索引数组或空数组
+     */
+    getActiveIndices<T extends Component>(componentType: ComponentType<T>): number[];
+    /**
+     * 获取实体在SoA存储中的索引
+     * @param componentType 组件类型
+     * @param entityId 实体ID
+     * @returns 存储索引或undefined
+     */
+    getEntityIndex<T extends Component>(componentType: ComponentType<T>, entityId: number): number | undefined;
+    /**
+     * 根据索引获取实体ID
+     * @param componentType 组件类型
+     * @param index 存储索引
+     * @returns 实体ID或undefined
+     */
+    getEntityIdByIndex<T extends Component>(componentType: ComponentType<T>, index: number): number | undefined;
     /**
      * 获取或创建组件存储器（默认原始存储）
      * @param componentType 组件类型
@@ -2079,155 +2128,6 @@ declare class ComponentStorageManager {
     clear(): void;
 }
 
-/**
- * 组件索引类型
- */
-declare enum IndexType {
-    /** 哈希索引 - 最快查找 */
-    HASH = "hash",
-    /** 位图索引 - 内存高效 */
-    BITMAP = "bitmap",
-    /** 排序索引 - 支持范围查询 */
-    SORTED = "sorted"
-}
-/**
- * 索引统计信息
- */
-interface IndexStats {
-    /** 索引类型 */
-    type: IndexType;
-    /** 索引大小 */
-    size: number;
-    /** 内存使用量（字节） */
-    memoryUsage: number;
-    /** 查询次数 */
-    queryCount: number;
-    /** 平均查询时间（毫秒） */
-    avgQueryTime: number;
-    /** 最后更新时间 */
-    lastUpdated: number;
-}
-/**
- * 组件索引接口
- */
-interface IComponentIndex {
-    /** 索引类型 */
-    readonly type: IndexType;
-    /** 添加实体到索引 */
-    addEntity(entity: Entity): void;
-    /** 从索引中移除实体 */
-    removeEntity(entity: Entity): void;
-    /** 查询包含指定组件的实体 */
-    query(componentType: ComponentType): Set<Entity>;
-    /** 批量查询多个组件 */
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    /** 清空索引 */
-    clear(): void;
-    /** 获取索引统计信息 */
-    getStats(): IndexStats;
-}
-/**
- * 哈希索引实现
- *
- * 使用Map数据结构，提供O(1)的查找性能。
- * 适合大多数查询场景。
- */
-declare class HashComponentIndex implements IComponentIndex {
-    readonly type = IndexType.HASH;
-    private _componentToEntities;
-    private _entityToComponents;
-    private _queryCount;
-    private _totalQueryTime;
-    private _lastUpdated;
-    private _setPool;
-    private _componentTypeSetPool;
-    addEntity(entity: Entity): void;
-    removeEntity(entity: Entity): void;
-    query(componentType: ComponentType): Set<Entity>;
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    clear(): void;
-    getStats(): IndexStats;
-}
-/**
- * 位图索引实现
- *
- * 使用位操作进行快速集合运算，内存效率高。
- * 适合有限组件类型和大量实体的场景。
- */
-declare class BitmapComponentIndex implements IComponentIndex {
-    readonly type = IndexType.BITMAP;
-    private _componentTypeToBit;
-    private _entityToBitmap;
-    private _bitToEntities;
-    private _nextBit;
-    private _queryCount;
-    private _totalQueryTime;
-    private _lastUpdated;
-    addEntity(entity: Entity): void;
-    removeEntity(entity: Entity): void;
-    query(componentType: ComponentType): Set<Entity>;
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    clear(): void;
-    getStats(): IndexStats;
-}
-/**
- * 智能组件索引管理器
- *
- * 根据使用模式自动选择最优的索引策略。
- * 支持动态切换索引类型以获得最佳性能。
- */
-declare class ComponentIndexManager {
-    private _activeIndex;
-    private _indexHistory;
-    private _autoOptimize;
-    private _optimizationThreshold;
-    constructor(initialType?: IndexType);
-    /**
-     * 添加实体到索引
-     */
-    addEntity(entity: Entity): void;
-    /**
-     * 从索引中移除实体
-     */
-    removeEntity(entity: Entity): void;
-    /**
-     * 查询包含指定组件的实体
-     */
-    query(componentType: ComponentType): Set<Entity>;
-    /**
-     * 批量查询多个组件
-     */
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    /**
-     * 手动切换索引类型
-     */
-    switchIndexType(type: IndexType): void;
-    /**
-     * 启用/禁用自动优化
-     */
-    setAutoOptimize(enabled: boolean): void;
-    /**
-     * 获取当前索引统计信息
-     */
-    getStats(): IndexStats;
-    /**
-     * 获取所有索引类型的历史统计信息
-     */
-    getAllStats(): Map<IndexType, IndexStats>;
-    /**
-     * 清空索引
-     */
-    clear(): void;
-    /**
-     * 创建指定类型的索引
-     */
-    private createIndex;
-    /**
-     * 检查是否需要优化索引
-     */
-    private checkOptimization;
-}
-
 /**
  * 原型标识符
  */
@@ -2638,12 +2538,6 @@ declare class QuerySystem {
             hitRate: string;
         };
     };
-    /**
-     * 切换组件索引类型
-     *
-     * @param indexType 新的索引类型
-     */
-    switchComponentIndexType(indexType: IndexType): void;
     /**
      * 配置脏标记系统
      *
@@ -5784,6 +5678,316 @@ declare class ComponentTypeManager {
     get registeredTypeCount(): number;
 }
 
+/**
+ * 稀疏集合实现
+ *
+ * 提供O(1)的插入、删除、查找操作，同时保持数据的紧凑存储。
+ * 使用密集数组存储实际数据，稀疏映射提供快速访问
+ *
+ * @template T 存储的数据类型
+ *
+ * @example
+ * ```typescript
+ * const sparseSet = new SparseSet<Entity>();
+ *
+ * sparseSet.add(entity1);
+ * sparseSet.add(entity2);
+ *
+ * if (sparseSet.has(entity1)) {
+ *     sparseSet.remove(entity1);
+ * }
+ *
+ * sparseSet.forEach((entity, index) => {
+ *     console.log(`Entity at index ${index}: ${entity.name}`);
+ * });
+ * ```
+ */
+declare class SparseSet<T> {
+    /**
+     * 密集存储数组
+     *
+     * 连续存储所有有效数据，确保遍历时的缓存友好性。
+     */
+    private _dense;
+    /**
+     * 稀疏映射表
+     *
+     * 将数据项映射到密集数组中的索引，提供O(1)的查找性能。
+     */
+    private _sparse;
+    /**
+     * 添加元素到集合
+     *
+     * @param item 要添加的元素
+     * @returns 是否成功添加（false表示元素已存在）
+     */
+    add(item: T): boolean;
+    /**
+     * 从集合中移除元素
+     *
+     * 使用swap-and-pop技术保持数组紧凑性：
+     * 1. 将要删除的元素与最后一个元素交换
+     * 2. 删除最后一个元素
+     * 3. 更新映射表
+     *
+     * @param item 要移除的元素
+     * @returns 是否成功移除（false表示元素不存在）
+     */
+    remove(item: T): boolean;
+    /**
+     * 检查元素是否存在于集合中
+     *
+     * @param item 要检查的元素
+     * @returns 元素是否存在
+     */
+    has(item: T): boolean;
+    /**
+     * 获取元素在密集数组中的索引
+     *
+     * @param item 要查询的元素
+     * @returns 索引，如果元素不存在则返回undefined
+     */
+    getIndex(item: T): number | undefined;
+    /**
+     * 根据索引获取元素
+     *
+     * @param index 索引
+     * @returns 元素，如果索引无效则返回undefined
+     */
+    getByIndex(index: number): T | undefined;
+    /**
+     * 获取集合大小
+     */
+    get size(): number;
+    /**
+     * 检查集合是否为空
+     */
+    get isEmpty(): boolean;
+    /**
+     * 遍历集合中的所有元素
+     *
+     * 保证遍历顺序与添加顺序一致（除非中间有删除操作）。
+     * 遍历性能优秀，因为数据在内存中连续存储。
+     *
+     * @param callback 遍历回调函数
+     */
+    forEach(callback: (item: T, index: number) => void): void;
+    /**
+     * 映射集合中的所有元素
+     *
+     * @param callback 映射回调函数
+     * @returns 映射后的新数组
+     */
+    map<U>(callback: (item: T, index: number) => U): U[];
+    /**
+     * 过滤集合中的元素
+     *
+     * @param predicate 过滤条件
+     * @returns 满足条件的元素数组
+     */
+    filter(predicate: (item: T, index: number) => boolean): T[];
+    /**
+     * 查找第一个满足条件的元素
+     *
+     * @param predicate 查找条件
+     * @returns 找到的元素，如果没有则返回undefined
+     */
+    find(predicate: (item: T, index: number) => boolean): T | undefined;
+    /**
+     * 检查是否存在满足条件的元素
+     *
+     * @param predicate 检查条件
+     * @returns 是否存在满足条件的元素
+     */
+    some(predicate: (item: T, index: number) => boolean): boolean;
+    /**
+     * 检查是否所有元素都满足条件
+     *
+     * @param predicate 检查条件
+     * @returns 是否所有元素都满足条件
+     */
+    every(predicate: (item: T, index: number) => boolean): boolean;
+    /**
+     * 获取密集数组的只读副本
+     *
+     * 返回数组的浅拷贝，确保外部无法直接修改内部数据。
+     */
+    getDenseArray(): readonly T[];
+    /**
+     * 获取密集数组的直接引用（内部使用）
+     *
+     * 警告：直接修改返回的数组会破坏数据结构的完整性。
+     * 仅在性能关键场景下使用，并确保不会修改数组内容。
+     */
+    getDenseArrayUnsafe(): readonly T[];
+    /**
+     * 清空集合
+     */
+    clear(): void;
+    /**
+     * 转换为数组
+     */
+    toArray(): T[];
+    /**
+     * 转换为Set
+     */
+    toSet(): Set<T>;
+    /**
+     * 获取内存使用统计信息
+     */
+    getMemoryStats(): {
+        denseArraySize: number;
+        sparseMapSize: number;
+        totalMemory: number;
+    };
+    /**
+     * 验证数据结构的完整性
+     *
+     * 调试用方法，检查内部数据结构是否一致。
+     */
+    validate(): boolean;
+}
+
+/**
+ * 组件稀疏集合实现
+ *
+ * 结合通用稀疏集合和组件位掩码
+ *
+ * 存储结构：
+ * - 稀疏集合存储实体
+ * - 位掩码数组存储组件信息
+ * - 组件类型映射表
+ */
+declare class ComponentSparseSet {
+    /**
+     * 实体稀疏集合
+     *
+     * 存储所有拥有组件的实体，提供O(1)的实体操作。
+     */
+    private _entities;
+    /**
+     * 组件位掩码数组
+     *
+     * 与实体稀疏集合的密集数组对应，存储每个实体的组件位掩码。
+     * 数组索引与稀疏集合的密集数组索引一一对应。
+     */
+    private _componentMasks;
+    /**
+     * 组件类型到实体集合的映射
+     *
+     * 维护每个组件类型对应的实体集合，用于快速的单组件查询。
+     */
+    private _componentToEntities;
+    /**
+     * 实体集合对象池
+     *
+     * 使用core库的Pool系统来管理PoolableEntitySet对象的复用。
+     */
+    private static _entitySetPool;
+    constructor();
+    /**
+     * 添加实体到组件索引
+     *
+     * 分析实体的组件组成，生成位掩码，并更新所有相关索引。
+     *
+     * @param entity 要添加的实体
+     */
+    addEntity(entity: Entity): void;
+    /**
+     * 从组件索引中移除实体
+     *
+     * 清理实体相关的所有索引数据，保持数据结构的紧凑性。
+     *
+     * @param entity 要移除的实体
+     */
+    removeEntity(entity: Entity): void;
+    /**
+     * 查询包含指定组件的所有实体
+     *
+     * @param componentType 组件类型
+     * @returns 包含该组件的实体集合
+     */
+    queryByComponent(componentType: ComponentType): Set<Entity>;
+    /**
+     * 多组件查询（AND操作）
+     *
+     * 查找同时包含所有指定组件的实体。
+     *
+     * @param componentTypes 组件类型数组
+     * @returns 满足条件的实体集合
+     */
+    queryMultipleAnd(componentTypes: ComponentType[]): Set<Entity>;
+    /**
+     * 多组件查询（OR操作）
+     *
+     * 查找包含任意一个指定组件的实体。
+     *
+     * @param componentTypes 组件类型数组
+     * @returns 满足条件的实体集合
+     */
+    queryMultipleOr(componentTypes: ComponentType[]): Set<Entity>;
+    /**
+     * 检查实体是否包含指定组件
+     *
+     * @param entity 实体
+     * @param componentType 组件类型
+     * @returns 是否包含该组件
+     */
+    hasComponent(entity: Entity, componentType: ComponentType): boolean;
+    /**
+     * 获取实体的组件位掩码
+     *
+     * @param entity 实体
+     * @returns 组件位掩码，如果实体不存在则返回undefined
+     */
+    getEntityMask(entity: Entity): IBigIntLike | undefined;
+    /**
+     * 获取所有实体
+     *
+     * @returns 所有实体的数组
+     */
+    getAllEntities(): Entity[];
+    /**
+     * 获取实体数量
+     */
+    get size(): number;
+    /**
+     * 检查是否为空
+     */
+    get isEmpty(): boolean;
+    /**
+     * 遍历所有实体
+     *
+     * @param callback 遍历回调函数
+     */
+    forEach(callback: (entity: Entity, mask: IBigIntLike, index: number) => void): void;
+    /**
+     * 清空所有数据
+     */
+    clear(): void;
+    /**
+     * 获取内存使用统计
+     */
+    getMemoryStats(): {
+        entitiesMemory: number;
+        masksMemory: number;
+        mappingsMemory: number;
+        totalMemory: number;
+    };
+    /**
+     * 验证数据结构完整性
+     */
+    validate(): boolean;
+    /**
+     * 获取实体的组件类型集合
+     */
+    private getEntityComponentTypes;
+    /**
+     * 更新组件类型到实体的映射
+     */
+    private updateComponentMappings;
+}
+
 /**
  * 存储组件类型名称的Symbol键
  */
@@ -6227,6 +6431,99 @@ declare class EntityManager {
     private updateTagIndex;
 }
 
+/**
+ * 索引统计信息
+ */
+interface IndexStats {
+    /** 索引大小 */
+    size: number;
+    /** 内存使用量（字节） */
+    memoryUsage: number;
+    /** 查询次数 */
+    queryCount: number;
+    /** 平均查询时间（毫秒） */
+    avgQueryTime: number;
+    /** 最后更新时间 */
+    lastUpdated: number;
+}
+/**
+ * 组件索引接口
+ */
+interface IComponentIndex {
+    /** 添加实体到索引 */
+    addEntity(entity: Entity): void;
+    /** 从索引中移除实体 */
+    removeEntity(entity: Entity): void;
+    /** 查询包含指定组件的实体 */
+    query(componentType: ComponentType): Set<Entity>;
+    /** 批量查询多个组件 */
+    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    /** 清空索引 */
+    clear(): void;
+    /** 获取索引统计信息 */
+    getStats(): IndexStats;
+}
+/**
+ * 通用组件索引实现
+ *
+ * 基于Sparse Set算法：
+ * - O(1)的实体添加、删除、查找
+ * - 高效的位运算查询
+ * - 内存紧凑的存储结构
+ * - 缓存友好的遍历性能
+ */
+declare class ComponentIndex implements IComponentIndex {
+    /**
+     * 组件稀疏集合
+     *
+     * 核心存储结构，处理所有实体和组件的索引操作。
+     */
+    private _sparseSet;
+    private _queryCount;
+    private _totalQueryTime;
+    private _lastUpdated;
+    constructor();
+    addEntity(entity: Entity): void;
+    removeEntity(entity: Entity): void;
+    query(componentType: ComponentType): Set<Entity>;
+    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    clear(): void;
+    getStats(): IndexStats;
+}
+/**
+ * 组件索引管理器
+ *
+ * 使用统一的组件索引实现，自动优化查询性能。
+ */
+declare class ComponentIndexManager {
+    private _index;
+    constructor();
+    /**
+     * 添加实体到索引
+     */
+    addEntity(entity: Entity): void;
+    /**
+     * 从索引中移除实体
+     */
+    removeEntity(entity: Entity): void;
+    /**
+     * 查询包含指定组件的实体
+     */
+    query(componentType: ComponentType): Set<Entity>;
+    /**
+     * 批量查询多个组件
+     */
+    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    /**
+     * 获取索引统计信息
+     */
+    getStats(): IndexStats;
+    /**
+     * 清空索引
+     */
+    clear(): void;
+}
+
 /**
  * 脏标记类型
  */
@@ -6582,5 +6879,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler, BigIntFactory, BitmapComponentIndex, Bits, COMPONENT_TYPE_NAME, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, HighPrecision, IdentifierPool, IndexType, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeMap, SoAStorage, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI, createLogger, getComponentInstanceTypeName, getComponentTypeName, getSystemInstanceTypeName, getSystemTypeName, setGlobalLogLevel };
-export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+export { ArchetypeSystem, AsyncEventHandler, BigIntFactory, Bits, COMPONENT_TYPE_NAME, Component, ComponentDataCollector, ComponentIndex, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSparseSet, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeMap, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI, createLogger, getComponentInstanceTypeName, getComponentTypeName, getSystemInstanceTypeName, getSystemTypeName, setGlobalLogLevel };
+export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, IComponentIndex, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IndexStats, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };