@esengine/ecs-framework 2.1.41 → 2.1.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @esengine/ecs-framework v2.1.41
2
+ * @esengine/ecs-framework v2.1.44
3
3
  * TypeScript definitions
4
4
  */
5
5
  /**
@@ -1838,6 +1838,9 @@ declare class SoAStorage<T extends Component> {
1838
1838
  private resize;
1839
1839
  getActiveIndices(): number[];
1840
1840
  getFieldArray(fieldName: string): Float32Array | Float64Array | Int32Array | null;
1841
+ getTypedFieldArray<K extends keyof T>(fieldName: K): Float32Array | Float64Array | Int32Array | null;
1842
+ getEntityIndex(entityId: number): number | undefined;
1843
+ getEntityIdByIndex(index: number): number | undefined;
1841
1844
  size(): number;
1842
1845
  clear(): void;
1843
1846
  compact(): void;
@@ -2021,6 +2024,52 @@ declare class ComponentStorage<T extends Component> {
2021
2024
  declare class ComponentStorageManager {
2022
2025
  private static readonly _logger;
2023
2026
  private storages;
2027
+ /**
2028
+ * 检查组件类型是否启用SoA存储
2029
+ * @param componentType 组件类型
2030
+ * @returns 是否为SoA存储
2031
+ */
2032
+ isSoAStorage<T extends Component>(componentType: ComponentType<T>): boolean;
2033
+ /**
2034
+ * 获取SoA存储器(类型安全)
2035
+ * @param componentType 组件类型
2036
+ * @returns SoA存储器或null
2037
+ */
2038
+ getSoAStorage<T extends Component>(componentType: ComponentType<T>): SoAStorage<T> | null;
2039
+ /**
2040
+ * 直接获取SoA字段数组(类型安全)
2041
+ * @param componentType 组件类型
2042
+ * @param fieldName 字段名
2043
+ * @returns TypedArray或null
2044
+ */
2045
+ getFieldArray<T extends Component>(componentType: ComponentType<T>, fieldName: string): Float32Array | Float64Array | Int32Array | null;
2046
+ /**
2047
+ * 直接获取SoA字段数组(类型安全,带字段名检查)
2048
+ * @param componentType 组件类型
2049
+ * @param fieldName 字段名(类型检查)
2050
+ * @returns TypedArray或null
2051
+ */
2052
+ getTypedFieldArray<T extends Component, K extends keyof T>(componentType: ComponentType<T>, fieldName: K): Float32Array | Float64Array | Int32Array | null;
2053
+ /**
2054
+ * 获取SoA存储的活跃索引
2055
+ * @param componentType 组件类型
2056
+ * @returns 活跃索引数组或空数组
2057
+ */
2058
+ getActiveIndices<T extends Component>(componentType: ComponentType<T>): number[];
2059
+ /**
2060
+ * 获取实体在SoA存储中的索引
2061
+ * @param componentType 组件类型
2062
+ * @param entityId 实体ID
2063
+ * @returns 存储索引或undefined
2064
+ */
2065
+ getEntityIndex<T extends Component>(componentType: ComponentType<T>, entityId: number): number | undefined;
2066
+ /**
2067
+ * 根据索引获取实体ID
2068
+ * @param componentType 组件类型
2069
+ * @param index 存储索引
2070
+ * @returns 实体ID或undefined
2071
+ */
2072
+ getEntityIdByIndex<T extends Component>(componentType: ComponentType<T>, index: number): number | undefined;
2024
2073
  /**
2025
2074
  * 获取或创建组件存储器(默认原始存储)
2026
2075
  * @param componentType 组件类型
@@ -2079,155 +2128,6 @@ declare class ComponentStorageManager {
2079
2128
  clear(): void;
2080
2129
  }
2081
2130
 
2082
- /**
2083
- * 组件索引类型
2084
- */
2085
- declare enum IndexType {
2086
- /** 哈希索引 - 最快查找 */
2087
- HASH = "hash",
2088
- /** 位图索引 - 内存高效 */
2089
- BITMAP = "bitmap",
2090
- /** 排序索引 - 支持范围查询 */
2091
- SORTED = "sorted"
2092
- }
2093
- /**
2094
- * 索引统计信息
2095
- */
2096
- interface IndexStats {
2097
- /** 索引类型 */
2098
- type: IndexType;
2099
- /** 索引大小 */
2100
- size: number;
2101
- /** 内存使用量(字节) */
2102
- memoryUsage: number;
2103
- /** 查询次数 */
2104
- queryCount: number;
2105
- /** 平均查询时间(毫秒) */
2106
- avgQueryTime: number;
2107
- /** 最后更新时间 */
2108
- lastUpdated: number;
2109
- }
2110
- /**
2111
- * 组件索引接口
2112
- */
2113
- interface IComponentIndex {
2114
- /** 索引类型 */
2115
- readonly type: IndexType;
2116
- /** 添加实体到索引 */
2117
- addEntity(entity: Entity): void;
2118
- /** 从索引中移除实体 */
2119
- removeEntity(entity: Entity): void;
2120
- /** 查询包含指定组件的实体 */
2121
- query(componentType: ComponentType): Set<Entity>;
2122
- /** 批量查询多个组件 */
2123
- queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
2124
- /** 清空索引 */
2125
- clear(): void;
2126
- /** 获取索引统计信息 */
2127
- getStats(): IndexStats;
2128
- }
2129
- /**
2130
- * 哈希索引实现
2131
- *
2132
- * 使用Map数据结构,提供O(1)的查找性能。
2133
- * 适合大多数查询场景。
2134
- */
2135
- declare class HashComponentIndex implements IComponentIndex {
2136
- readonly type = IndexType.HASH;
2137
- private _componentToEntities;
2138
- private _entityToComponents;
2139
- private _queryCount;
2140
- private _totalQueryTime;
2141
- private _lastUpdated;
2142
- private _setPool;
2143
- private _componentTypeSetPool;
2144
- addEntity(entity: Entity): void;
2145
- removeEntity(entity: Entity): void;
2146
- query(componentType: ComponentType): Set<Entity>;
2147
- queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
2148
- clear(): void;
2149
- getStats(): IndexStats;
2150
- }
2151
- /**
2152
- * 位图索引实现
2153
- *
2154
- * 使用位操作进行快速集合运算,内存效率高。
2155
- * 适合有限组件类型和大量实体的场景。
2156
- */
2157
- declare class BitmapComponentIndex implements IComponentIndex {
2158
- readonly type = IndexType.BITMAP;
2159
- private _componentTypeToBit;
2160
- private _entityToBitmap;
2161
- private _bitToEntities;
2162
- private _nextBit;
2163
- private _queryCount;
2164
- private _totalQueryTime;
2165
- private _lastUpdated;
2166
- addEntity(entity: Entity): void;
2167
- removeEntity(entity: Entity): void;
2168
- query(componentType: ComponentType): Set<Entity>;
2169
- queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
2170
- clear(): void;
2171
- getStats(): IndexStats;
2172
- }
2173
- /**
2174
- * 智能组件索引管理器
2175
- *
2176
- * 根据使用模式自动选择最优的索引策略。
2177
- * 支持动态切换索引类型以获得最佳性能。
2178
- */
2179
- declare class ComponentIndexManager {
2180
- private _activeIndex;
2181
- private _indexHistory;
2182
- private _autoOptimize;
2183
- private _optimizationThreshold;
2184
- constructor(initialType?: IndexType);
2185
- /**
2186
- * 添加实体到索引
2187
- */
2188
- addEntity(entity: Entity): void;
2189
- /**
2190
- * 从索引中移除实体
2191
- */
2192
- removeEntity(entity: Entity): void;
2193
- /**
2194
- * 查询包含指定组件的实体
2195
- */
2196
- query(componentType: ComponentType): Set<Entity>;
2197
- /**
2198
- * 批量查询多个组件
2199
- */
2200
- queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
2201
- /**
2202
- * 手动切换索引类型
2203
- */
2204
- switchIndexType(type: IndexType): void;
2205
- /**
2206
- * 启用/禁用自动优化
2207
- */
2208
- setAutoOptimize(enabled: boolean): void;
2209
- /**
2210
- * 获取当前索引统计信息
2211
- */
2212
- getStats(): IndexStats;
2213
- /**
2214
- * 获取所有索引类型的历史统计信息
2215
- */
2216
- getAllStats(): Map<IndexType, IndexStats>;
2217
- /**
2218
- * 清空索引
2219
- */
2220
- clear(): void;
2221
- /**
2222
- * 创建指定类型的索引
2223
- */
2224
- private createIndex;
2225
- /**
2226
- * 检查是否需要优化索引
2227
- */
2228
- private checkOptimization;
2229
- }
2230
-
2231
2131
  /**
2232
2132
  * 原型标识符
2233
2133
  */
@@ -2638,12 +2538,6 @@ declare class QuerySystem {
2638
2538
  hitRate: string;
2639
2539
  };
2640
2540
  };
2641
- /**
2642
- * 切换组件索引类型
2643
- *
2644
- * @param indexType 新的索引类型
2645
- */
2646
- switchComponentIndexType(indexType: IndexType): void;
2647
2541
  /**
2648
2542
  * 配置脏标记系统
2649
2543
  *
@@ -3978,7 +3872,6 @@ declare abstract class EntitySystem implements ISystemBase {
3978
3872
  private _initialized;
3979
3873
  private _matcher;
3980
3874
  private _trackedEntities;
3981
- private _lastQueryResult;
3982
3875
  /**
3983
3876
  * 获取系统处理的实体列表(动态查询)
3984
3877
  */
@@ -4075,7 +3968,7 @@ declare abstract class EntitySystem implements ISystemBase {
4075
3968
  *
4076
3969
  * @param entities 要处理的实体列表
4077
3970
  */
4078
- protected process(entities: Entity[]): void;
3971
+ protected process(_entities: Entity[]): void;
4079
3972
  /**
4080
3973
  * 后期处理实体列表
4081
3974
  *
@@ -4083,7 +3976,7 @@ declare abstract class EntitySystem implements ISystemBase {
4083
3976
  *
4084
3977
  * @param entities 要处理的实体列表
4085
3978
  */
4086
- protected lateProcess(entities: Entity[]): void;
3979
+ protected lateProcess(_entities: Entity[]): void;
4087
3980
  /**
4088
3981
  * 系统处理完毕后调用
4089
3982
  *
@@ -5785,6 +5678,384 @@ declare class ComponentTypeManager {
5785
5678
  get registeredTypeCount(): number;
5786
5679
  }
5787
5680
 
5681
+ /**
5682
+ * 稀疏集合实现
5683
+ *
5684
+ * 提供O(1)的插入、删除、查找操作,同时保持数据的紧凑存储。
5685
+ * 使用密集数组存储实际数据,稀疏映射提供快速访问
5686
+ *
5687
+ * @template T 存储的数据类型
5688
+ *
5689
+ * @example
5690
+ * ```typescript
5691
+ * const sparseSet = new SparseSet<Entity>();
5692
+ *
5693
+ * sparseSet.add(entity1);
5694
+ * sparseSet.add(entity2);
5695
+ *
5696
+ * if (sparseSet.has(entity1)) {
5697
+ * sparseSet.remove(entity1);
5698
+ * }
5699
+ *
5700
+ * sparseSet.forEach((entity, index) => {
5701
+ * console.log(`Entity at index ${index}: ${entity.name}`);
5702
+ * });
5703
+ * ```
5704
+ */
5705
+ declare class SparseSet<T> {
5706
+ /**
5707
+ * 密集存储数组
5708
+ *
5709
+ * 连续存储所有有效数据,确保遍历时的缓存友好性。
5710
+ */
5711
+ private _dense;
5712
+ /**
5713
+ * 稀疏映射表
5714
+ *
5715
+ * 将数据项映射到密集数组中的索引,提供O(1)的查找性能。
5716
+ */
5717
+ private _sparse;
5718
+ /**
5719
+ * 添加元素到集合
5720
+ *
5721
+ * @param item 要添加的元素
5722
+ * @returns 是否成功添加(false表示元素已存在)
5723
+ */
5724
+ add(item: T): boolean;
5725
+ /**
5726
+ * 从集合中移除元素
5727
+ *
5728
+ * 使用swap-and-pop技术保持数组紧凑性:
5729
+ * 1. 将要删除的元素与最后一个元素交换
5730
+ * 2. 删除最后一个元素
5731
+ * 3. 更新映射表
5732
+ *
5733
+ * @param item 要移除的元素
5734
+ * @returns 是否成功移除(false表示元素不存在)
5735
+ */
5736
+ remove(item: T): boolean;
5737
+ /**
5738
+ * 检查元素是否存在于集合中
5739
+ *
5740
+ * @param item 要检查的元素
5741
+ * @returns 元素是否存在
5742
+ */
5743
+ has(item: T): boolean;
5744
+ /**
5745
+ * 获取元素在密集数组中的索引
5746
+ *
5747
+ * @param item 要查询的元素
5748
+ * @returns 索引,如果元素不存在则返回undefined
5749
+ */
5750
+ getIndex(item: T): number | undefined;
5751
+ /**
5752
+ * 根据索引获取元素
5753
+ *
5754
+ * @param index 索引
5755
+ * @returns 元素,如果索引无效则返回undefined
5756
+ */
5757
+ getByIndex(index: number): T | undefined;
5758
+ /**
5759
+ * 获取集合大小
5760
+ */
5761
+ get size(): number;
5762
+ /**
5763
+ * 检查集合是否为空
5764
+ */
5765
+ get isEmpty(): boolean;
5766
+ /**
5767
+ * 遍历集合中的所有元素
5768
+ *
5769
+ * 保证遍历顺序与添加顺序一致(除非中间有删除操作)。
5770
+ * 遍历性能优秀,因为数据在内存中连续存储。
5771
+ *
5772
+ * @param callback 遍历回调函数
5773
+ */
5774
+ forEach(callback: (item: T, index: number) => void): void;
5775
+ /**
5776
+ * 映射集合中的所有元素
5777
+ *
5778
+ * @param callback 映射回调函数
5779
+ * @returns 映射后的新数组
5780
+ */
5781
+ map<U>(callback: (item: T, index: number) => U): U[];
5782
+ /**
5783
+ * 过滤集合中的元素
5784
+ *
5785
+ * @param predicate 过滤条件
5786
+ * @returns 满足条件的元素数组
5787
+ */
5788
+ filter(predicate: (item: T, index: number) => boolean): T[];
5789
+ /**
5790
+ * 查找第一个满足条件的元素
5791
+ *
5792
+ * @param predicate 查找条件
5793
+ * @returns 找到的元素,如果没有则返回undefined
5794
+ */
5795
+ find(predicate: (item: T, index: number) => boolean): T | undefined;
5796
+ /**
5797
+ * 检查是否存在满足条件的元素
5798
+ *
5799
+ * @param predicate 检查条件
5800
+ * @returns 是否存在满足条件的元素
5801
+ */
5802
+ some(predicate: (item: T, index: number) => boolean): boolean;
5803
+ /**
5804
+ * 检查是否所有元素都满足条件
5805
+ *
5806
+ * @param predicate 检查条件
5807
+ * @returns 是否所有元素都满足条件
5808
+ */
5809
+ every(predicate: (item: T, index: number) => boolean): boolean;
5810
+ /**
5811
+ * 获取密集数组的只读副本
5812
+ *
5813
+ * 返回数组的浅拷贝,确保外部无法直接修改内部数据。
5814
+ */
5815
+ getDenseArray(): readonly T[];
5816
+ /**
5817
+ * 获取密集数组的直接引用(内部使用)
5818
+ *
5819
+ * 警告:直接修改返回的数组会破坏数据结构的完整性。
5820
+ * 仅在性能关键场景下使用,并确保不会修改数组内容。
5821
+ */
5822
+ getDenseArrayUnsafe(): readonly T[];
5823
+ /**
5824
+ * 清空集合
5825
+ */
5826
+ clear(): void;
5827
+ /**
5828
+ * 转换为数组
5829
+ */
5830
+ toArray(): T[];
5831
+ /**
5832
+ * 转换为Set
5833
+ */
5834
+ toSet(): Set<T>;
5835
+ /**
5836
+ * 获取内存使用统计信息
5837
+ */
5838
+ getMemoryStats(): {
5839
+ denseArraySize: number;
5840
+ sparseMapSize: number;
5841
+ totalMemory: number;
5842
+ };
5843
+ /**
5844
+ * 验证数据结构的完整性
5845
+ *
5846
+ * 调试用方法,检查内部数据结构是否一致。
5847
+ */
5848
+ validate(): boolean;
5849
+ }
5850
+
5851
+ /**
5852
+ * 组件稀疏集合实现
5853
+ *
5854
+ * 结合通用稀疏集合和组件位掩码
5855
+ *
5856
+ * 存储结构:
5857
+ * - 稀疏集合存储实体
5858
+ * - 位掩码数组存储组件信息
5859
+ * - 组件类型映射表
5860
+ */
5861
+ declare class ComponentSparseSet {
5862
+ /**
5863
+ * 实体稀疏集合
5864
+ *
5865
+ * 存储所有拥有组件的实体,提供O(1)的实体操作。
5866
+ */
5867
+ private _entities;
5868
+ /**
5869
+ * 组件位掩码数组
5870
+ *
5871
+ * 与实体稀疏集合的密集数组对应,存储每个实体的组件位掩码。
5872
+ * 数组索引与稀疏集合的密集数组索引一一对应。
5873
+ */
5874
+ private _componentMasks;
5875
+ /**
5876
+ * 组件类型到实体集合的映射
5877
+ *
5878
+ * 维护每个组件类型对应的实体集合,用于快速的单组件查询。
5879
+ */
5880
+ private _componentToEntities;
5881
+ /**
5882
+ * 实体集合对象池
5883
+ *
5884
+ * 使用core库的Pool系统来管理PoolableEntitySet对象的复用。
5885
+ */
5886
+ private static _entitySetPool;
5887
+ constructor();
5888
+ /**
5889
+ * 添加实体到组件索引
5890
+ *
5891
+ * 分析实体的组件组成,生成位掩码,并更新所有相关索引。
5892
+ *
5893
+ * @param entity 要添加的实体
5894
+ */
5895
+ addEntity(entity: Entity): void;
5896
+ /**
5897
+ * 从组件索引中移除实体
5898
+ *
5899
+ * 清理实体相关的所有索引数据,保持数据结构的紧凑性。
5900
+ *
5901
+ * @param entity 要移除的实体
5902
+ */
5903
+ removeEntity(entity: Entity): void;
5904
+ /**
5905
+ * 查询包含指定组件的所有实体
5906
+ *
5907
+ * @param componentType 组件类型
5908
+ * @returns 包含该组件的实体集合
5909
+ */
5910
+ queryByComponent(componentType: ComponentType): Set<Entity>;
5911
+ /**
5912
+ * 多组件查询(AND操作)
5913
+ *
5914
+ * 查找同时包含所有指定组件的实体。
5915
+ *
5916
+ * @param componentTypes 组件类型数组
5917
+ * @returns 满足条件的实体集合
5918
+ */
5919
+ queryMultipleAnd(componentTypes: ComponentType[]): Set<Entity>;
5920
+ /**
5921
+ * 多组件查询(OR操作)
5922
+ *
5923
+ * 查找包含任意一个指定组件的实体。
5924
+ *
5925
+ * @param componentTypes 组件类型数组
5926
+ * @returns 满足条件的实体集合
5927
+ */
5928
+ queryMultipleOr(componentTypes: ComponentType[]): Set<Entity>;
5929
+ /**
5930
+ * 检查实体是否包含指定组件
5931
+ *
5932
+ * @param entity 实体
5933
+ * @param componentType 组件类型
5934
+ * @returns 是否包含该组件
5935
+ */
5936
+ hasComponent(entity: Entity, componentType: ComponentType): boolean;
5937
+ /**
5938
+ * 获取实体的组件位掩码
5939
+ *
5940
+ * @param entity 实体
5941
+ * @returns 组件位掩码,如果实体不存在则返回undefined
5942
+ */
5943
+ getEntityMask(entity: Entity): IBigIntLike | undefined;
5944
+ /**
5945
+ * 获取所有实体
5946
+ *
5947
+ * @returns 所有实体的数组
5948
+ */
5949
+ getAllEntities(): Entity[];
5950
+ /**
5951
+ * 获取实体数量
5952
+ */
5953
+ get size(): number;
5954
+ /**
5955
+ * 检查是否为空
5956
+ */
5957
+ get isEmpty(): boolean;
5958
+ /**
5959
+ * 遍历所有实体
5960
+ *
5961
+ * @param callback 遍历回调函数
5962
+ */
5963
+ forEach(callback: (entity: Entity, mask: IBigIntLike, index: number) => void): void;
5964
+ /**
5965
+ * 清空所有数据
5966
+ */
5967
+ clear(): void;
5968
+ /**
5969
+ * 获取内存使用统计
5970
+ */
5971
+ getMemoryStats(): {
5972
+ entitiesMemory: number;
5973
+ masksMemory: number;
5974
+ mappingsMemory: number;
5975
+ totalMemory: number;
5976
+ };
5977
+ /**
5978
+ * 验证数据结构完整性
5979
+ */
5980
+ validate(): boolean;
5981
+ /**
5982
+ * 获取实体的组件类型集合
5983
+ */
5984
+ private getEntityComponentTypes;
5985
+ /**
5986
+ * 更新组件类型到实体的映射
5987
+ */
5988
+ private updateComponentMappings;
5989
+ }
5990
+
5991
+ /**
5992
+ * 存储组件类型名称的Symbol键
5993
+ */
5994
+ declare const COMPONENT_TYPE_NAME: unique symbol;
5995
+ /**
5996
+ * 存储系统类型名称的Symbol键
5997
+ */
5998
+ declare const SYSTEM_TYPE_NAME: unique symbol;
5999
+ /**
6000
+ * 组件类型装饰器
6001
+ * 用于为组件类指定固定的类型名称,避免在代码混淆后失效
6002
+ *
6003
+ * @param typeName 组件类型名称
6004
+ * @example
6005
+ * ```typescript
6006
+ * @ECSComponent('Position')
6007
+ * class PositionComponent extends Component {
6008
+ * x: number = 0;
6009
+ * y: number = 0;
6010
+ * }
6011
+ * ```
6012
+ */
6013
+ declare function ECSComponent(typeName: string): <T extends new (...args: any[]) => Component>(target: T) => T;
6014
+ /**
6015
+ * 系统类型装饰器
6016
+ * 用于为系统类指定固定的类型名称,避免在代码混淆后失效
6017
+ *
6018
+ * @param typeName 系统类型名称
6019
+ * @example
6020
+ * ```typescript
6021
+ * @ECSSystem('Movement')
6022
+ * class MovementSystem extends EntitySystem {
6023
+ * protected process(entities: Entity[]): void {
6024
+ * // 系统逻辑
6025
+ * }
6026
+ * }
6027
+ * ```
6028
+ */
6029
+ declare function ECSSystem(typeName: string): <T extends new (...args: any[]) => EntitySystem>(target: T) => T;
6030
+ /**
6031
+ * 获取组件类型的名称,优先使用装饰器指定的名称
6032
+ *
6033
+ * @param componentType 组件构造函数
6034
+ * @returns 组件类型名称
6035
+ */
6036
+ declare function getComponentTypeName<T extends Component>(componentType: new (...args: any[]) => T): string;
6037
+ /**
6038
+ * 获取系统类型的名称,优先使用装饰器指定的名称
6039
+ *
6040
+ * @param systemType 系统构造函数
6041
+ * @returns 系统类型名称
6042
+ */
6043
+ declare function getSystemTypeName<T extends EntitySystem>(systemType: new (...args: any[]) => T): string;
6044
+ /**
6045
+ * 从组件实例获取类型名称
6046
+ *
6047
+ * @param component 组件实例
6048
+ * @returns 组件类型名称
6049
+ */
6050
+ declare function getComponentInstanceTypeName(component: Component): string;
6051
+ /**
6052
+ * 从系统实例获取类型名称
6053
+ *
6054
+ * @param system 系统实例
6055
+ * @returns 系统类型名称
6056
+ */
6057
+ declare function getSystemInstanceTypeName(system: EntitySystem): string;
6058
+
5788
6059
  /**
5789
6060
  * 实体查询构建器
5790
6061
  *
@@ -6160,6 +6431,99 @@ declare class EntityManager {
6160
6431
  private updateTagIndex;
6161
6432
  }
6162
6433
 
6434
+ /**
6435
+ * 索引统计信息
6436
+ */
6437
+ interface IndexStats {
6438
+ /** 索引大小 */
6439
+ size: number;
6440
+ /** 内存使用量(字节) */
6441
+ memoryUsage: number;
6442
+ /** 查询次数 */
6443
+ queryCount: number;
6444
+ /** 平均查询时间(毫秒) */
6445
+ avgQueryTime: number;
6446
+ /** 最后更新时间 */
6447
+ lastUpdated: number;
6448
+ }
6449
+ /**
6450
+ * 组件索引接口
6451
+ */
6452
+ interface IComponentIndex {
6453
+ /** 添加实体到索引 */
6454
+ addEntity(entity: Entity): void;
6455
+ /** 从索引中移除实体 */
6456
+ removeEntity(entity: Entity): void;
6457
+ /** 查询包含指定组件的实体 */
6458
+ query(componentType: ComponentType): Set<Entity>;
6459
+ /** 批量查询多个组件 */
6460
+ queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
6461
+ /** 清空索引 */
6462
+ clear(): void;
6463
+ /** 获取索引统计信息 */
6464
+ getStats(): IndexStats;
6465
+ }
6466
+ /**
6467
+ * 通用组件索引实现
6468
+ *
6469
+ * 基于Sparse Set算法:
6470
+ * - O(1)的实体添加、删除、查找
6471
+ * - 高效的位运算查询
6472
+ * - 内存紧凑的存储结构
6473
+ * - 缓存友好的遍历性能
6474
+ */
6475
+ declare class ComponentIndex implements IComponentIndex {
6476
+ /**
6477
+ * 组件稀疏集合
6478
+ *
6479
+ * 核心存储结构,处理所有实体和组件的索引操作。
6480
+ */
6481
+ private _sparseSet;
6482
+ private _queryCount;
6483
+ private _totalQueryTime;
6484
+ private _lastUpdated;
6485
+ constructor();
6486
+ addEntity(entity: Entity): void;
6487
+ removeEntity(entity: Entity): void;
6488
+ query(componentType: ComponentType): Set<Entity>;
6489
+ queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
6490
+ clear(): void;
6491
+ getStats(): IndexStats;
6492
+ }
6493
+ /**
6494
+ * 组件索引管理器
6495
+ *
6496
+ * 使用统一的组件索引实现,自动优化查询性能。
6497
+ */
6498
+ declare class ComponentIndexManager {
6499
+ private _index;
6500
+ constructor();
6501
+ /**
6502
+ * 添加实体到索引
6503
+ */
6504
+ addEntity(entity: Entity): void;
6505
+ /**
6506
+ * 从索引中移除实体
6507
+ */
6508
+ removeEntity(entity: Entity): void;
6509
+ /**
6510
+ * 查询包含指定组件的实体
6511
+ */
6512
+ query(componentType: ComponentType): Set<Entity>;
6513
+ /**
6514
+ * 批量查询多个组件
6515
+ */
6516
+ queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
6517
+ /**
6518
+ * 获取索引统计信息
6519
+ */
6520
+ getStats(): IndexStats;
6521
+ /**
6522
+ * 清空索引
6523
+ */
6524
+ clear(): void;
6525
+ }
6526
+
6163
6527
  /**
6164
6528
  * 脏标记类型
6165
6529
  */
@@ -6515,5 +6879,5 @@ declare class Time {
6515
6879
  static checkEvery(interval: number, lastTime: number): boolean;
6516
6880
  }
6517
6881
 
6518
- export { ArchetypeSystem, AsyncEventHandler, BigIntFactory, BitmapComponentIndex, Bits, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, 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, Scene, SceneDataCollector, SerializeMap, SoAStorage, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI, createLogger, setGlobalLogLevel };
6519
- 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 };
6882
+ 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 };
6883
+ 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 };