@esengine/ecs-framework 2.1.25 → 2.1.27

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.25
+ * @esengine/ecs-framework v2.1.27
  * TypeScript definitions
  */
 /**
@@ -1493,37 +1493,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 +1613,6 @@ declare class Entity {
      * 用于快速定位组件在数组中的位置。
      */
     private _componentTypeToIndex;
-    /**
-     * 组件缓存
-     *
-     * 高性能组件访问缓存。
-     */
-    private _componentCache;
-    /**
-     * 组件访问统计
-     *
-     * 记录组件访问的性能统计信息。
-     */
-    private _componentAccessStats;
     /**
      * 构造函数
      *
@@ -1781,24 +1738,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 +1788,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 +1910,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;
     };
 }
@@ -2348,8 +2244,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 +2425,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是否有效
+     */
+    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
      */
-    checkIn(id: number): void;
+    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;
 }
 
 /**
@@ -5654,6 +5735,10 @@ declare class ComponentPoolManager {
      * 清空所有池
      */
     clearAll(): void;
+    /**
+     * 重置管理器，移除所有注册的池
+     */
+    reset(): void;
     /**
      * 获取池统计信息
      */
@@ -5748,5 +5833,355 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentStorage, ComponentTypeManager, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, IdentifierPool, IndexType, IndexUpdateBatcher, IntervalSystem, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, SceneDataCollector, SystemDataCollector, TieredObjectPool, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI };
-export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEventBus, IEventData, IEventListenerConfig, IEventStats, IPerformanceDebugData, IPerformanceEventData, IPoolable, ISceneDebugData, ISceneEventData, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+/**
+ * 可序列化接口
+ *
+ * 实现此接口的类可以被快照系统序列化和反序列化
+ */
+interface ISnapshotable {
+    /**
+     * 序列化对象到可传输的数据格式
+     *
+     * @returns 序列化后的数据
+     */
+    serialize(): any;
+    /**
+     * 从序列化数据恢复对象状态
+     *
+     * @param data - 序列化数据
+     */
+    deserialize(data: any): void;
+}
+/**
+ * 快照配置接口
+ */
+interface SnapshotConfig {
+    /** 是否包含在快照中 */
+    includeInSnapshot: boolean;
+    /** 压缩级别 (0-9) */
+    compressionLevel: number;
+    /** 同步优先级 (数字越大优先级越高) */
+    syncPriority: number;
+    /** 是否启用增量快照 */
+    enableIncremental: boolean;
+}
+/**
+ * 组件快照数据
+ */
+interface ComponentSnapshot {
+    /** 组件类型名称 */
+    type: string;
+    /** 组件ID */
+    id: number;
+    /** 序列化数据 */
+    data: any;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 快照配置 */
+    config?: SnapshotConfig;
+}
+/**
+ * 实体快照数据
+ */
+interface EntitySnapshot {
+    /** 实体ID */
+    id: number;
+    /** 实体名称 */
+    name: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 是否激活 */
+    active: boolean;
+    /** 标签 */
+    tag: number;
+    /** 更新顺序 */
+    updateOrder: number;
+    /** 组件快照列表 */
+    components: ComponentSnapshot[];
+    /** 子实体ID列表 */
+    children: number[];
+    /** 父实体ID */
+    parent?: number;
+    /** 快照时间戳 */
+    timestamp: number;
+}
+/**
+ * 场景快照数据
+ */
+interface SceneSnapshot {
+    /** 实体快照列表 */
+    entities: EntitySnapshot[];
+    /** 快照时间戳 */
+    timestamp: number;
+    /** 框架版本 */
+    version: string;
+    /** 快照类型 */
+    type: 'full' | 'incremental';
+    /** 基础快照ID（增量快照使用） */
+    baseSnapshotId?: string;
+}
+
+/**
+ * 快照管理器
+ *
+ * 负责创建和管理ECS系统的快照，支持完整快照和增量快照
+ */
+declare class SnapshotManager {
+    /** 默认快照配置 */
+    private static readonly DEFAULT_CONFIG;
+    /** 框架版本 */
+    private readonly version;
+    /** 最后快照时间戳 */
+    private lastSnapshotTime;
+    /** 快照缓存 */
+    private snapshotCache;
+    /** 最大缓存数量 */
+    private maxCacheSize;
+    /**
+     * 创建场景快照
+     *
+     * @param entities - 实体列表
+     * @param type - 快照类型
+     * @returns 场景快照
+     */
+    createSceneSnapshot(entities: Entity[], type?: 'full' | 'incremental'): SceneSnapshot;
+    /**
+     * 从快照恢复场景
+     *
+     * @param snapshot - 场景快照
+     * @param targetEntities - 目标实体列表（用于增量恢复）
+     * @param createMissingEntities - 是否创建缺失的实体
+     */
+    restoreFromSnapshot(snapshot: SceneSnapshot, targetEntities?: Entity[], createMissingEntities?: boolean): Entity[];
+    /**
+     * 从快照恢复实体列表
+     *
+     * @param snapshot - 场景快照
+     * @param targetEntities - 目标实体列表
+     * @param createMissingEntities - 是否创建缺失的实体
+     */
+    restoreEntitiesFromSnapshot(snapshot: SceneSnapshot, targetEntities: Entity[], createMissingEntities?: boolean): Entity[];
+    /**
+     * 从快照创建实体
+     */
+    private createEntityFromSnapshot;
+    /**
+     * 从快照创建组件
+     */
+    private createComponentFromSnapshot;
+    /**
+     * 获取组件类型
+     */
+    private getComponentType;
+    /**
+     * 创建快速快照（跳过变化检测）
+     *
+     * @param entities - 实体列表
+     * @returns 场景快照
+     */
+    createQuickSnapshot(entities: Entity[]): SceneSnapshot;
+    /**
+     * 创建增量快照
+     *
+     * @param entities - 实体列表
+     * @param baseSnapshot - 基础快照
+     * @param enableChangeDetection - 是否启用变化检测
+     * @returns 增量快照
+     */
+    createIncrementalSnapshot(entities: Entity[], baseSnapshot: SceneSnapshot, enableChangeDetection?: boolean): SceneSnapshot;
+    /**
+     * 缓存快照
+     *
+     * @param id - 快照ID
+     * @param snapshot - 快照数据
+     */
+    cacheSnapshot(id: string, snapshot: SceneSnapshot): void;
+    /**
+     * 获取缓存的快照
+     *
+     * @param id - 快照ID
+     * @returns 快照数据或undefined
+     */
+    getCachedSnapshot(id: string): SceneSnapshot | undefined;
+    /**
+     * 清空快照缓存
+     */
+    clearCache(): void;
+    /**
+     * 清空所有缓存
+     */
+    clearAllCaches(): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getCacheStats(): {
+        snapshotCacheSize: number;
+    };
+    /**
+     * 创建实体快照
+     */
+    private createEntitySnapshot;
+    /**
+     * 创建组件快照
+     */
+    private createComponentSnapshot;
+    /**
+     * 默认组件序列化
+     */
+    private defaultSerializeComponent;
+    /**
+     * 检查值是否可序列化
+     */
+    private isSerializableValue;
+    /**
+     * 检查组件是否支持快照
+     */
+    private isComponentSnapshotable;
+    /**
+     * 获取组件快照配置
+     */
+    private getComponentSnapshotConfig;
+    /**
+     * 检查组件是否有序列化方法
+     */
+    private hasSerializeMethod;
+    /**
+     * 恢复完整快照
+     */
+    private restoreFullSnapshot;
+    /**
+     * 恢复增量快照
+     */
+    private restoreIncrementalSnapshot;
+    /**
+     * 从快照恢复实体
+     */
+    private restoreEntityFromSnapshot;
+    /**
+     * 从快照恢复组件
+     */
+    private restoreComponentFromSnapshot;
+    /**
+     * 默认组件反序列化
+     */
+    private defaultDeserializeComponent;
+    /**
+     * 检查实体结构是否发生变化（组件数量、类型等）
+     */
+    private hasEntityStructureChanged;
+    /**
+     * 获取发生变化的组件列表
+     */
+    private getChangedComponents;
+    /**
+     * 检查组件数据是否发生变化
+     */
+    private hasComponentDataChanged;
+    /**
+     * 检查组件是否有变化检测方法
+     */
+    private hasChangeDetectionMethod;
+    /**
+     * 创建增量实体快照（只包含变化的组件）
+     */
+    private createIncrementalEntitySnapshot;
+    /**
+     * 生成快照ID
+     */
+    private generateSnapshotId;
+}
+
+/**
+ * 快照扩展接口
+ *
+ * 为Component基类提供快照功能的扩展接口
+ */
+interface ISnapshotExtension {
+    /** 快照配置 */
+    snapshotConfig?: SnapshotConfig;
+    /** 序列化方法 */
+    serialize?(): any;
+    /** 反序列化方法 */
+    deserialize?(data: any): void;
+    /** 变化检测方法 */
+    hasChanged?(baseData: any): boolean;
+}
+/**
+ * 快照装饰器
+ *
+ * 用于标记组件属性为可序列化
+ */
+declare function Serializable(config?: Partial<SnapshotConfig>): (target: any, propertyKey: string) => void;
+/**
+ * 快照配置装饰器
+ *
+ * 用于配置组件的快照行为
+ */
+declare function SnapshotConfigDecorator(config: SnapshotConfig): (target: any) => void;
+/**
+ * 快照扩展工具类
+ */
+declare class SnapshotExtension {
+    /**
+     * 为组件添加快照支持
+     *
+     * @param component - 目标组件
+     * @param config - 快照配置
+     */
+    static enableSnapshot(component: Component, config?: Partial<SnapshotConfig>): void;
+    /**
+     * 禁用组件的快照功能
+     *
+     * @param component - 目标组件
+     */
+    static disableSnapshot(component: Component): void;
+    /**
+     * 检查组件是否支持快照
+     *
+     * @param component - 目标组件
+     * @returns 是否支持快照
+     */
+    static isSnapshotable(component: Component): boolean;
+    /**
+     * 获取组件的可序列化属性
+     *
+     * @param component - 目标组件
+     * @returns 可序列化属性列表
+     */
+    static getSerializableProperties(component: Component): string[];
+    /**
+     * 创建组件的默认序列化方法
+     *
+     * @param component - 目标组件
+     * @returns 序列化数据
+     */
+    static createDefaultSerializer(component: Component): () => any;
+    /**
+     * 创建组件的默认反序列化方法
+     *
+     * @param component - 目标组件
+     * @returns 反序列化函数
+     */
+    static createDefaultDeserializer(component: Component): (data: any) => void;
+    /**
+     * 创建简单的变化检测方法
+     *
+     * @param component - 目标组件
+     * @returns 变化检测函数
+     */
+    static createSimpleChangeDetector(component: Component): (baseData: any) => boolean;
+    /**
+     * 创建深度变化检测方法
+     *
+     * @param component - 目标组件
+     * @returns 变化检测函数
+     */
+    static createDeepChangeDetector(component: Component): (baseData: any) => boolean;
+    /**
+     * 深度比较两个值
+     */
+    private static deepCompare;
+}
+
+export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentStorage, ComponentTypeManager, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, IdentifierPool, IndexType, IndexUpdateBatcher, IntervalSystem, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, SceneDataCollector, Serializable, SnapshotConfigDecorator, SnapshotExtension, SnapshotManager, SystemDataCollector, TieredObjectPool, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI };
+export type { Archetype, ArchetypeQueryResult, ComponentSnapshot, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EntitySnapshot, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEventBus, IEventData, IEventListenerConfig, IEventStats, IPerformanceDebugData, IPerformanceEventData, IPoolable, ISceneDebugData, ISceneEventData, ISnapshotExtension, ISnapshotable, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats, SceneSnapshot, SnapshotConfig };