@esengine/ecs-framework 2.1.26 → 2.1.28

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.26
+ * @esengine/ecs-framework v2.1.28
  * TypeScript definitions
  */
 /**
@@ -1119,6 +1119,106 @@ declare abstract class Component implements IComponent {
     update(): void;
 }
 
+/**
+ * BigInt兼容性抽象层
+ *
+ * 为不支持BigInt的环境提供兼容实现，确保ECS框架在所有平台上都能正常运行。
+ * 自动检测运行时环境的BigInt支持情况，并提供统一的接口。
+ *
+ * @example
+ * ```typescript
+ * // 创建兼容的BigInt值
+ * const value = BigIntFactory.create(123);
+ *
+ * // 位运算
+ * const result = value.or(BigIntFactory.create(456));
+ *
+ * // 检查兼容性
+ * console.log(BigIntFactory.isNativeSupported()); // true/false
+ * ```
+ */
+/**
+ * BigInt兼容接口
+ *
+ * 定义了BigInt的基本操作接口，支持原生BigInt和兼容实现的统一调用。
+ */
+interface IBigIntLike {
+    /**
+     * 获取数值表示
+     * @returns 数值
+     */
+    valueOf(): number;
+    /**
+     * 转换为字符串
+     * @param radix 进制，支持2、10、16
+     * @returns 字符串表示
+     */
+    toString(radix?: number): string;
+    /**
+     * 位运算：与
+     * @param other 另一个BigInt值
+     * @returns 运算结果
+     */
+    and(other: IBigIntLike): IBigIntLike;
+    /**
+     * 位运算：或
+     * @param other 另一个BigInt值
+     * @returns 运算结果
+     */
+    or(other: IBigIntLike): IBigIntLike;
+    /**
+     * 位运算：异或
+     * @param other 另一个BigInt值
+     * @returns 运算结果
+     */
+    xor(other: IBigIntLike): IBigIntLike;
+    /**
+     * 位运算：非
+     * @param maxBits 最大位数限制
+     * @returns 运算结果
+     */
+    not(maxBits?: number): IBigIntLike;
+    /**
+     * 左移位运算
+     * @param bits 移位数
+     * @returns 运算结果
+     */
+    shiftLeft(bits: number): IBigIntLike;
+    /**
+     * 右移位运算
+     * @param bits 移位数
+     * @returns 运算结果
+     */
+    shiftRight(bits: number): IBigIntLike;
+    /**
+     * 相等比较
+     * @param other 另一个BigInt值
+     * @returns 是否相等
+     */
+    equals(other: IBigIntLike): boolean;
+    /**
+     * 检查是否为零
+     * @returns 是否为零
+     */
+    isZero(): boolean;
+    /**
+     * 创建副本
+     * @returns 新的实例
+     */
+    clone(): IBigIntLike;
+}
+/**
+ * 环境信息接口
+ */
+interface EnvironmentInfo {
+    /** 是否支持BigInt */
+    supportsBigInt: boolean;
+    /** 运行环境 */
+    environment: string;
+    /** JavaScript引擎 */
+    jsEngine: string;
+}
+
 /**
  * 组件类型定义
  */
@@ -1247,7 +1347,7 @@ declare class ComponentStorageManager {
      * @param entityId 实体ID
      * @returns 组件位掩码
      */
-    getComponentMask(entityId: number): bigint;
+    getComponentMask(entityId: number): IBigIntLike;
     /**
      * 压缩所有存储器
      */
@@ -1493,37 +1593,6 @@ declare class EntityComparer {
      */
     compare(self: Entity, other: Entity): number;
 }
-/**
- * 组件缓存配置
- */
-interface ComponentCacheConfig {
-    maxSize: number;
-    ttl: number;
-    enableLRU: boolean;
-}
-/**
- * 高性能组件缓存
- */
-declare class ComponentCache {
-    private cache;
-    private accessOrder;
-    private config;
-    constructor(config?: ComponentCacheConfig);
-    get<T extends Component>(type: ComponentType<T>): T | null;
-    set<T extends Component>(type: ComponentType<T>, component: T): void;
-    delete(type: ComponentType): boolean;
-    clear(): void;
-    has(type: ComponentType): boolean;
-    private evictLeastRecentlyUsed;
-    private updateAccessOrder;
-    private removeFromAccessOrder;
-    getStats(): {
-        size: number;
-        maxSize: number;
-        hitRate: number;
-        averageAccessCount: number;
-    };
-}
 /**
  * 游戏实体类
  *
@@ -1644,18 +1713,6 @@ declare class Entity {
      * 用于快速定位组件在数组中的位置。
      */
     private _componentTypeToIndex;
-    /**
-     * 组件缓存
-     *
-     * 高性能组件访问缓存。
-     */
-    private _componentCache;
-    /**
-     * 组件访问统计
-     *
-     * 记录组件访问的性能统计信息。
-     */
-    private _componentAccessStats;
     /**
      * 构造函数
      *
@@ -1750,7 +1807,7 @@ declare class Entity {
      *
      * @returns 实体的组件位掩码
      */
-    get componentMask(): bigint;
+    get componentMask(): IBigIntLike;
     /**
      * 创建并添加组件
      *
@@ -1781,24 +1838,6 @@ declare class Entity {
      * @returns 组件实例或null
      */
     getComponent<T extends Component>(type: ComponentType<T>): T | null;
-    /**
-     * 更新组件访问统计
-     *
-     * @param type - 组件类型
-     */
-    private updateComponentAccessStats;
-    /**
-     * 记录缓存命中
-     *
-     * @param type - 组件类型
-     */
-    private recordCacheHit;
-    /**
-     * 记录缓存未命中
-     *
-     * @param type - 组件类型
-     */
-    private recordCacheMiss;
     /**
      * 重建组件索引映射
      */
@@ -1849,35 +1888,6 @@ declare class Entity {
      * @returns 被移除的组件数组
      */
     removeComponentsByTypes<T extends Component>(componentTypes: ComponentType<T>[]): (T | null)[];
-    /**
-     * 获取组件缓存统计信息
-     *
-     * @returns 缓存统计信息
-     */
-    getComponentCacheStats(): {
-        cacheStats: ReturnType<ComponentCache['getStats']>;
-        accessStats: Map<string, {
-            accessCount: number;
-            lastAccessed: number;
-            cacheHits: number;
-            cacheMisses: number;
-            hitRate: number;
-        }>;
-        indexMappingSize: number;
-        totalComponents: number;
-    };
-    /**
-     * 预热组件缓存
-     *
-     * 将所有组件添加到缓存中，提升后续访问性能
-     */
-    warmUpComponentCache(): void;
-    /**
-     * 清理组件缓存
-     *
-     * 清除过期的缓存项，释放内存
-     */
-    cleanupComponentCache(): void;
     /**
      * 获取所有指定类型的组件
      *
@@ -2000,20 +2010,6 @@ declare class Entity {
         childCount: number;
         childIds: number[];
         depth: number;
-        componentCache: {
-            size: number;
-            maxSize: number;
-            hitRate: number;
-            averageAccessCount: number;
-        };
-        componentAccessStats: Array<{
-            componentType: string;
-            accessCount: number;
-            cacheHits: number;
-            cacheMisses: number;
-            hitRate: number;
-            lastAccessed: string;
-        }>;
         indexMappingSize: number;
     };
 }
@@ -2126,33 +2122,60 @@ declare class EntityList {
 
 /**
  * 高性能位操作类
- * 基于BigInt实现，支持任意数量的位操作
+ *
+ * 基于BigInt实现，支持任意数量的位操作。
+ * 自动适配运行环境，在不支持BigInt的环境中使用兼容实现。
+ *
+ * @example
+ * ```typescript
+ * const bits = new Bits();
+ * bits.set(0);
+ * bits.set(5);
+ * console.log(bits.get(0)); // true
+ * console.log(bits.get(1)); // false
+ * ```
  */
 declare class Bits {
     private _value;
-    constructor(initialValue?: bigint);
+    /**
+     * 构造函数
+     * @param initialValue 初始值，可以是IBigIntLike或数值
+     */
+    constructor(initialValue?: IBigIntLike | number | string);
     /**
      * 设置指定位置的位为1
+     * @param index 位索引（从0开始）
+     * @throws {Error} 当索引为负数时抛出错误
      */
     set(index: number): void;
     /**
      * 清除指定位置的位（设为0）
+     * @param index 位索引（从0开始）
+     * @throws {Error} 当索引为负数时抛出错误
      */
     clear(index: number): void;
     /**
      * 获取指定位置的位值
+     * @param index 位索引（从0开始）
+     * @returns 位值（true表示1，false表示0）
      */
     get(index: number): boolean;
     /**
      * 检查是否包含所有指定的位
+     * @param other 另一个Bits对象
+     * @returns 是否包含所有指定的位
      */
     containsAll(other: Bits): boolean;
     /**
      * 检查是否包含任意一个指定的位
+     * @param other 另一个Bits对象
+     * @returns 是否包含任意一个指定的位
      */
     intersects(other: Bits): boolean;
     /**
      * 检查是否不包含任何指定的位
+     * @param other 另一个Bits对象
+     * @returns 是否不包含任何指定的位
      */
     excludes(other: Bits): boolean;
     /**
@@ -2161,74 +2184,100 @@ declare class Bits {
     clearAll(): void;
     /**
      * 检查是否为空（没有设置任何位）
+     * @returns 是否为空
      */
     isEmpty(): boolean;
     /**
      * 获取设置的位数量
+     * @returns 设置为1的位数量
      */
     cardinality(): number;
     /**
      * 位运算：与
+     * @param other 另一个Bits对象
+     * @returns 新的Bits对象，包含与运算结果
      */
     and(other: Bits): Bits;
     /**
      * 位运算：或
+     * @param other 另一个Bits对象
+     * @returns 新的Bits对象，包含或运算结果
      */
     or(other: Bits): Bits;
     /**
      * 位运算：异或
+     * @param other 另一个Bits对象
+     * @returns 新的Bits对象，包含异或运算结果
      */
     xor(other: Bits): Bits;
     /**
      * 位运算：非
+     * @param maxBits 最大位数限制，默认64位
+     * @returns 新的Bits对象，包含非运算结果
      */
     not(maxBits?: number): Bits;
     /**
      * 复制另一个Bits对象
+     * @param other 要复制的Bits对象
      */
     copyFrom(other: Bits): void;
     /**
      * 创建当前Bits的副本
+     * @returns 新的Bits对象副本
      */
     clone(): Bits;
     /**
-     * 获取原始BigInt值
+     * 获取原始值
+     * @returns 原始的IBigIntLike值
      */
-    getValue(): bigint;
+    getValue(): IBigIntLike;
     /**
-     * 设置原始BigInt值
+     * 设置原始值
+     * @param value 新的值，可以是IBigIntLike或数值
      */
-    setValue(value: bigint): void;
+    setValue(value: IBigIntLike | number | string): void;
     /**
      * 获取调试信息
+     * @returns 返回显示设置位索引的字符串
      */
     toString(): string;
     /**
      * 获取二进制表示
+     * @param maxBits 最大位数，默认64位
+     * @returns 二进制字符串表示
      */
     toBinaryString(maxBits?: number): string;
     /**
      * 获取十六进制表示
+     * @returns 十六进制字符串表示
      */
     toHexString(): string;
     /**
      * 从二进制字符串创建Bits
+     * @param binaryString 二进制字符串
+     * @returns 新的Bits对象
      */
     static fromBinaryString(binaryString: string): Bits;
     /**
      * 从十六进制字符串创建Bits
+     * @param hexString 十六进制字符串
+     * @returns 新的Bits对象
      */
     static fromHexString(hexString: string): Bits;
     /**
      * 比较两个Bits对象是否相等
+     * @param other 另一个Bits对象
+     * @returns 是否相等
      */
     equals(other: Bits): boolean;
     /**
      * 获取最高位的索引
+     * @returns 最高位的索引，如果为空则返回-1
      */
     getHighestBitIndex(): number;
     /**
      * 获取最低位的索引
+     * @returns 最低位的索引，如果为空则返回-1
      */
     getLowestBitIndex(): number;
 }
@@ -2348,8 +2397,8 @@ declare abstract class EntitySystem implements ISystemBase {
     /**
      * 这个系统所属的场景
      */
-    get scene(): Scene;
-    set scene(value: Scene);
+    get scene(): Scene | null;
+    set scene(value: Scene | null);
     private _matcher;
     /**
      * 获取实体匹配器
@@ -2529,21 +2578,206 @@ declare class EntityProcessorList {
 }
 
 /**
- * ID池管理器
- * 用于管理实体ID的分配和回收
+ * 世代式ID池管理器
+ *
+ * 用于管理实体ID的分配和回收，支持世代版本控制以防止悬空引用问题。
+ * 世代式ID由索引和版本组成，当ID被回收时版本会递增，确保旧引用失效。
+ *
+ * 支持动态扩展，理论上可以支持到65535个索引（16位），每个索引65535个版本（16位）。
+ * 总计可以处理超过42亿个独特的ID组合，完全满足ECS大规模实体需求。
+ *
+ * @example
+ * ```typescript
+ * const pool = new IdentifierPool();
+ *
+ * // 分配ID
+ * const id = pool.checkOut(); // 例如: 65536 (版本1，索引0)
+ *
+ * // 回收ID
+ * pool.checkIn(id);
+ *
+ * // 验证ID是否有效
+ * const isValid = pool.isValid(id); // false，因为版本已递增
+ * ```
  */
 declare class IdentifierPool {
-    private _nextAvailableId;
-    private _ids;
+    /**
+     * 下一个可用的索引
+     */
+    private _nextAvailableIndex;
+    /**
+     * 空闲的索引列表
+     */
+    private _freeIndices;
+    /**
+     * 每个索引对应的世代版本
+     * 动态扩展的Map，按需分配内存
+     */
+    private _generations;
+    /**
+     * 延迟回收队列
+     * 防止在同一帧内立即重用ID，避免时序问题
+     */
+    private _pendingRecycle;
+    /**
+     * 延迟回收时间（毫秒）
+     */
+    private _recycleDelay;
+    /**
+     * 最大索引限制（16位）
+     * 这是框架设计选择：16位索引 + 16位版本 = 32位ID，确保高效位操作
+     * 不是硬件限制，而是性能和内存效率的权衡
+     */
+    private static readonly MAX_INDEX;
+    /**
+     * 最大世代限制（16位）
+     */
+    private static readonly MAX_GENERATION;
+    /**
+     * 内存扩展块大小
+     * 当需要更多内存时，一次性预分配的索引数量
+     */
+    private _expansionBlockSize;
+    /**
+     * 统计信息
+     */
+    private _stats;
+    /**
+     * 构造函数
+     *
+     * @param recycleDelay 延迟回收时间（毫秒），默认为100ms
+     * @param expansionBlockSize 内存扩展块大小，默认为1024
+     */
+    constructor(recycleDelay?: number, expansionBlockSize?: number);
     /**
      * 获取一个可用的ID
+     *
+     * 返回一个32位ID，高16位为世代版本，低16位为索引。
+     *
+     * @returns 新分配的实体ID
+     * @throws {Error} 当达到索引限制时抛出错误
      */
     checkOut(): number;
     /**
      * 回收一个ID
-     * @param id 要回收的ID
+     *
+     * 验证ID的有效性后，将其加入延迟回收队列。
+     * ID不会立即可重用，而是在延迟时间后才真正回收。
+     *
+     * @param id 要回收的实体ID
+     * @returns 是否成功回收（ID是否有效且未被重复回收）
+     */
+    checkIn(id: number): boolean;
+    /**
+     * 验证ID是否有效
+     *
+     * 检查ID的索引和世代版本是否匹配当前状态。
+     *
+     * @param id 要验证的实体ID
+     * @returns ID是否有效
      */
-    checkIn(id: number): void;
+    isValid(id: number): boolean;
+    /**
+     * 获取统计信息
+     *
+     * @returns 池的当前状态统计
+     */
+    getStats(): {
+        /** 已分配的总索引数 */
+        totalAllocated: number;
+        /** 总计回收次数 */
+        totalRecycled: number;
+        /** 当前活跃实体数 */
+        currentActive: number;
+        /** 当前空闲的索引数 */
+        currentlyFree: number;
+        /** 等待回收的ID数 */
+        pendingRecycle: number;
+        /** 理论最大实体数（设计限制） */
+        maxPossibleEntities: number;
+        /** 当前使用的最大索引 */
+        maxUsedIndex: number;
+        /** 内存使用（字节） */
+        memoryUsage: number;
+        /** 内存扩展次数 */
+        memoryExpansions: number;
+        /** 平均世代版本 */
+        averageGeneration: number;
+        /** 世代存储大小 */
+        generationStorageSize: number;
+    };
+    /**
+     * 强制执行延迟回收处理
+     *
+     * 在某些情况下可能需要立即处理延迟回收队列，
+     * 比如内存压力大或者需要精确的统计信息时。
+     */
+    forceProcessDelayedRecycle(): void;
+    /**
+     * 清理过期的延迟回收项
+     *
+     * 将超过延迟时间的回收项真正回收到空闲列表中。
+     *
+     * @param forceAll 是否强制处理所有延迟回收项
+     * @private
+     */
+    private _processDelayedRecycle;
+    /**
+     * 预分配世代信息
+     *
+     * @param startIndex 起始索引
+     * @param count 分配数量
+     * @private
+     */
+    private _preAllocateGenerations;
+    /**
+     * 确保指定索引的世代信息存在
+     *
+     * @param index 索引
+     * @private
+     */
+    private _ensureGenerationCapacity;
+    /**
+     * 计算内存使用量
+     *
+     * @returns 内存使用字节数
+     * @private
+     */
+    private _calculateMemoryUsage;
+    /**
+     * 打包索引和世代为32位ID
+     *
+     * @param index 索引（16位）
+     * @param generation 世代版本（16位）
+     * @returns 打包后的32位ID
+     * @private
+     */
+    private _packId;
+    /**
+     * 从ID中解包索引
+     *
+     * @param id 32位ID
+     * @returns 索引部分（16位）
+     * @private
+     */
+    private _unpackIndex;
+    /**
+     * 从ID中解包世代版本
+     *
+     * @param id 32位ID
+     * @returns 世代版本部分（16位）
+     * @private
+     */
+    private _unpackGeneration;
+    /**
+     * 内部ID有效性检查
+     *
+     * @param index 索引
+     * @param generation 世代版本
+     * @returns 是否有效
+     * @private
+     */
+    private _isValidId;
 }
 
 /**
@@ -4429,6 +4663,10 @@ declare class Core {
      * Core配置
      */
     private _config;
+    /**
+     * 兼容性信息
+     */
+    private _environmentInfo;
     /**
      * 创建核心实例
      *
@@ -4552,6 +4790,18 @@ declare class Core {
      * @returns 调试状态
      */
     static get isDebugEnabled(): boolean;
+    /**
+     * 获取环境兼容性信息
+     *
+     * @returns 环境兼容性信息
+     */
+    static getEnvironmentInfo(): EnvironmentInfo | null;
+    /**
+     * 检查BigInt是否支持
+     *
+     * @returns 是否支持BigInt
+     */
+    static get supportsBigInt(): boolean;
     /**
      * 场景切换回调
      *
@@ -4564,6 +4814,12 @@ declare class Core {
      * 执行核心系统的初始化逻辑。
      */
     protected initialize(): void;
+    /**
+     * 记录兼容性信息
+     *
+     * 在控制台输出当前环境的兼容性信息和建议。
+     */
+    private logCompatibilityInfo;
     /**
      * 内部更新方法
      *
@@ -5519,6 +5775,8 @@ declare class IndexUpdateBatcher {
 
 /**
  * 位掩码优化器，用于预计算和缓存常用的组件掩码
+ *
+ * 使用BigInt兼容层确保在所有平台上的正常运行。
  */
 declare class BitMaskOptimizer {
     private static instance;
@@ -5537,32 +5795,51 @@ declare class BitMaskOptimizer {
     getComponentTypeId(componentName: string): number | undefined;
     /**
      * 创建单个组件的掩码
+     * @param componentName 组件名称
+     * @returns 组件掩码
      */
-    createSingleComponentMask(componentName: string): bigint;
+    createSingleComponentMask(componentName: string): IBigIntLike;
     /**
      * 创建多个组件的组合掩码
+     * @param componentNames 组件名称数组
+     * @returns 组合掩码
      */
-    createCombinedMask(componentNames: string[]): bigint;
+    createCombinedMask(componentNames: string[]): IBigIntLike;
     /**
      * 检查掩码是否包含指定组件
+     * @param mask 要检查的掩码
+     * @param componentName 组件名称
+     * @returns 是否包含指定组件
      */
-    maskContainsComponent(mask: bigint, componentName: string): boolean;
+    maskContainsComponent(mask: IBigIntLike, componentName: string): boolean;
     /**
      * 检查掩码是否包含所有指定组件
+     * @param mask 要检查的掩码
+     * @param componentNames 组件名称数组
+     * @returns 是否包含所有指定组件
      */
-    maskContainsAllComponents(mask: bigint, componentNames: string[]): boolean;
+    maskContainsAllComponents(mask: IBigIntLike, componentNames: string[]): boolean;
     /**
      * 检查掩码是否包含任一指定组件
+     * @param mask 要检查的掩码
+     * @param componentNames 组件名称数组
+     * @returns 是否包含任一指定组件
      */
-    maskContainsAnyComponent(mask: bigint, componentNames: string[]): boolean;
+    maskContainsAnyComponent(mask: IBigIntLike, componentNames: string[]): boolean;
     /**
      * 添加组件到掩码
+     * @param mask 原始掩码
+     * @param componentName 要添加的组件名称
+     * @returns 新的掩码
      */
-    addComponentToMask(mask: bigint, componentName: string): bigint;
+    addComponentToMask(mask: IBigIntLike, componentName: string): IBigIntLike;
     /**
      * 从掩码中移除组件
+     * @param mask 原始掩码
+     * @param componentName 要移除的组件名称
+     * @returns 新的掩码
      */
-    removeComponentFromMask(mask: bigint, componentName: string): bigint;
+    removeComponentFromMask(mask: IBigIntLike, componentName: string): IBigIntLike;
     /**
      * 预计算常用掩码组合
      */
@@ -5585,11 +5862,11 @@ declare class BitMaskOptimizer {
     /**
      * 将掩码转换为组件名称数组
      */
-    maskToComponentNames(mask: bigint): string[];
+    maskToComponentNames(mask: IBigIntLike): string[];
     /**
      * 获取掩码中组件的数量
      */
-    getComponentCount(mask: bigint): number;
+    getComponentCount(mask: IBigIntLike): number;
 }
 
 /**
@@ -5654,6 +5931,10 @@ declare class ComponentPoolManager {
      * 清空所有池
      */
     clearAll(): void;
+    /**
+     * 重置管理器，移除所有注册的池
+     */
+    reset(): void;
     /**
      * 获取池统计信息
      */