@esengine/ecs-framework 2.1.48 → 2.1.50

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.48
+ * @esengine/ecs-framework v2.1.50
  * TypeScript definitions
  */
 /**
@@ -557,7 +557,10 @@ interface IComponent {
     onEnabled(): void;
     /** 组件禁用时的回调 */
     onDisabled(): void;
-    /** 更新组件 */
+    /**
+     * 更新组件
+     * @deprecated 不符合ECS架构规范，建议使用EntitySystem来处理更新逻辑
+     */
     update(): void;
 }
 /**
@@ -1053,6 +1056,8 @@ declare abstract class Component implements IComponent {
      * 更新顺序
      *
      * 决定组件在更新循环中的执行顺序。
+     *
+     * @see EntitySystem
      */
     private _updateOrder;
     /**
@@ -1066,6 +1071,7 @@ declare abstract class Component implements IComponent {
      *
      * 组件的实际启用状态取决于自身状态和所属实体的状态。
      *
+     * @deprecated 不符合ECS架构规范，建议自己实现DisabledComponent标记组件替代
      * @returns 如果组件和所属实体都启用则返回true
      */
     get enabled(): boolean;
@@ -1074,18 +1080,23 @@ declare abstract class Component implements IComponent {
      *
      * 当状态改变时会触发相应的生命周期回调。
      *
+     * @deprecated 不符合ECS架构规范，建议自己实现DisabledComponent标记组件替代
      * @param value - 新的启用状态
      */
     set enabled(value: boolean);
     /**
      * 获取更新顺序
      *
+     * @deprecated 不符合ECS架构规范，更新顺序应该由EntitySystem管理
+     * @see EntitySystem
      * @returns 组件的更新顺序值
      */
     get updateOrder(): number;
     /**
      * 设置更新顺序
      *
+     * @deprecated 不符合ECS架构规范，更新顺序应该由EntitySystem管理
+     * @see EntitySystem
      * @param value - 新的更新顺序值
      */
     set updateOrder(value: number);
@@ -1116,8 +1127,7 @@ declare abstract class Component implements IComponent {
     /**
      * 更新组件
      *
-     * 每帧调用，用于更新组件的逻辑。
-     * 子类应该重写此方法来实现具体的更新逻辑。
+     * @deprecated 不符合ECS架构规范，建议使用EntitySystem来处理更新逻辑
      */
     update(): void;
 }
@@ -1828,14 +1838,16 @@ declare class EventBus implements IEventBus {
      * 发射事件
      * @param eventType 事件类型
      * @param data 事件数据
+     * @param enhance 是否增强事件数据（添加timestamp、eventId等），默认false提升性能
      */
-    emit<T>(eventType: string, data: T): void;
+    emit<T>(eventType: string, data: T, enhance?: boolean): void;
     /**
      * 异步发射事件
      * @param eventType 事件类型
      * @param data 事件数据
+     * @param enhance 是否增强事件数据（添加timestamp、eventId等），默认false提升性能
      */
-    emitAsync<T>(eventType: string, data: T): Promise<void>;
+    emitAsync<T>(eventType: string, data: T, enhance?: boolean): Promise<void>;
     /**
      * 监听事件
      * @param eventType 事件类型
@@ -1987,7 +1999,7 @@ declare class EventBus implements IEventBus {
      */
     onPerformanceWarning(handler: (data: IPerformanceEventData) => void, config?: IEventListenerConfig): string;
     /**
-     * 验证事件类型
+     * 验证事件类型（仅在debug模式下执行，提升性能）
      * @param eventType 事件类型
      */
     private validateEventType;
@@ -2020,16 +2032,6 @@ declare class GlobalEventBus {
      */
     static reset(debugMode?: boolean): EventBus;
 }
-/**
- * 事件装饰器工厂
- * 用于自动注册事件监听器
- */
-declare function EventHandler$1(eventType: string, config?: IEventListenerConfig): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-/**
- * 异步事件装饰器工厂
- * 用于自动注册异步事件监听器
- */
-declare function AsyncEventHandler$1(eventType: string, config?: IEventListenerConfig): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 
 /**
  * 高性能实体列表管理器
@@ -2043,8 +2045,13 @@ declare class EntityList {
     private _entitiesToAdd;
     private _entitiesToRemove;
     private _isUpdating;
+    private _enableEntityDirectUpdate;
     get count(): number;
     constructor(scene: any);
+    /**
+     * 设置是否启用实体直接更新
+     */
+    setEnableEntityDirectUpdate(enabled: boolean): void;
     /**
      * 添加实体（立即添加或延迟添加）
      * @param entity 要添加的实体
@@ -2074,7 +2081,7 @@ declare class EntityList {
      */
     updateLists(): void;
     /**
-     * 更新所有实体
+     * 更新实体列表和实体
      */
     update(): void;
     /**
@@ -2106,7 +2113,7 @@ declare class EntityList {
      * @param componentType 组件类型
      * @returns 找到的所有实体数组
      */
-    findEntitiesWithComponent<T extends Component>(componentType: new (...args: unknown[]) => T): Entity[];
+    findEntitiesWithComponent<T extends Component>(componentType: new (...args: any[]) => T): Entity[];
     /**
      * 批量操作：对所有实体执行指定操作
      * @param action 要执行的操作
@@ -2201,7 +2208,7 @@ declare class Matcher {
      */
     static complex(): Matcher;
     /**
-     * 创建空匙配器（向后兼容）
+     * 创建空匙配器
      */
     static empty(): Matcher;
     /**
@@ -2493,97 +2500,15 @@ interface Archetype {
     id: ArchetypeId;
     /** 包含的组件类型 */
     componentTypes: ComponentType[];
-    /** 属于该原型的实体列表 */
-    entities: Entity[];
-    /** 原型创建时间 */
-    createdAt: number;
-    /** 最后更新时间 */
-    updatedAt: number;
-}
-/**
- * 原型查询结果
- */
-interface ArchetypeQueryResult {
-    /** 匹配的原型列表 */
-    archetypes: Archetype[];
-    /** 所有匹配实体的总数 */
-    totalEntities: number;
-    /** 查询执行时间（毫秒） */
-    executionTime: number;
-    /** 是否使用了缓存 */
-    fromCache: boolean;
-}
-/**
- * Archetype系统
- *
- * 根据实体的组件组合将实体分组到不同的原型中，提供高效的查询性能。
- */
-declare class ArchetypeSystem {
-    /** 所有原型的映射表 */
-    private _archetypes;
-    /** 实体到原型的映射 */
-    private _entityToArchetype;
-    /** 组件类型到原型的映射 */
-    private _componentToArchetypes;
-    /** 查询缓存 */
-    private _queryCache;
-    private _cacheTimeout;
-    private _maxCacheSize;
-    /**
-     * 添加实体到原型系统
-     */
-    addEntity(entity: Entity): void;
-    /**
-     * 从原型系统中移除实体
-     */
-    removeEntity(entity: Entity): void;
-    /**
-     * 查询包含指定组件组合的原型
-     */
-    queryArchetypes(componentTypes: ComponentType[], operation?: 'AND' | 'OR'): ArchetypeQueryResult;
-    /**
-     * 获取实体所属的原型
-     */
-    getEntityArchetype(entity: Entity): Archetype | undefined;
-    /**
-     * 获取所有原型
-     */
-    getAllArchetypes(): Archetype[];
-    /**
-     * 清空所有数据
-     */
-    clear(): void;
-    /**
-     * 获取实体的组件类型列表
-     */
-    private getEntityComponentTypes;
-    /**
-     * 生成原型ID
-     */
-    private generateArchetypeId;
-    /**
-     * 创建新原型
-     */
-    private createArchetype;
-    /**
-     * 检查原型是否包含所有指定组件
-     */
-    private archetypeContainsAllComponents;
-    /**
-     * 更新组件索引
-     */
-    private updateComponentIndexes;
-    /**
-     * 使查询缓存失效
-     */
-    private invalidateQueryCache;
+    /** 属于该原型的实体集合 */
+    entities: Set<Entity>;
 }
 
 /**
  * 实体查询结果接口
  */
 interface QueryResult {
-    entities: Entity[];
+    entities: readonly Entity[];
     count: number;
     /** 查询执行时间（毫秒） */
     executionTime: number;
@@ -2594,13 +2519,6 @@ interface QueryResult {
  * 高性能实体查询系统
  *
  * 提供快速的实体查询功能，支持按组件类型、标签、名称等多种方式查询实体。
- * 系统采用多级索引和智能缓存机制，确保在大量实体场景下的查询性能。
- *
- * 主要特性：
- * - 支持单组件和多组件查询
- * - 自动索引管理和缓存优化
- * - WebAssembly计算加速（如果可用）
- * - 详细的性能统计信息
  *
  * @example
  * ```typescript
@@ -2615,15 +2533,13 @@ declare class QuerySystem {
     private _logger;
     private entities;
     private entityIndex;
-    private indexDirty;
     private _version;
     private queryCache;
     private cacheMaxSize;
     private cacheTimeout;
-    private componentPoolManager;
+    private componentMaskCache;
     private componentIndexManager;
     private archetypeSystem;
-    private dirtyTrackingSystem;
     private queryStats;
     constructor();
     /**
@@ -2672,9 +2588,21 @@ declare class QuerySystem {
      */
     removeEntity(entity: Entity): void;
     /**
-     * 将实体添加到各种索引中（优化版本）
+     * 更新实体在查询系统中的索引
+     *
+     * 当实体的组件组合发生变化时调用此方法，高效地更新实体在查询系统中的索引。
+     *
+     * @param entity 要更新的实体
+     */
+    updateEntity(entity: Entity): void;
+    /**
+     * 将实体添加到各种索引中
      */
     private addEntityToIndexes;
+    private createAndSetMaskIndex;
+    private createAndSetComponentIndex;
+    private createAndSetTagIndex;
+    private createAndSetNameIndex;
     /**
      * 从各种索引中移除实体
      */
@@ -2812,37 +2740,20 @@ declare class QuerySystem {
      */
     private clearQueryCache;
     /**
-     * 公共方法：清理查询缓存
-     *
-     * 用于外部调用清理缓存，通常在批量操作后使用。
+     * 高效的缓存键生成
      */
-    clearCache(): void;
+    private generateCacheKey;
     /**
-     * 批量更新实体组件
-     *
-     * 对大量实体进行批量组件更新操作。
+     * 清理查询缓存
      *
-     * @param updates 更新操作列表，包含实体ID和新的组件掩码
-     *
-     * @example
-     * ```typescript
-     * // 批量更新实体的组件配置
-     * const updates = [
-     *     { entityId: 1, componentMask: BigInt(0b1011) },
-     *     { entityId: 2, componentMask: BigInt(0b1101) }
-     * ];
-     * querySystem.batchUpdateComponents(updates);
-     * ```
+     * 用于外部调用清理缓存，通常在批量操作后使用。
      */
-    batchUpdateComponents(updates: Array<{
-        entityId: number;
-        componentMask: bigint;
-    }>): void;
+    clearCache(): void;
     /**
      * 创建组件掩码
      *
      * 根据组件类型列表生成对应的位掩码。
-     * 使用位掩码优化器进行缓存和预计算。
+     * 使用缓存避免重复计算。
      *
      * @param componentTypes 组件类型列表
      * @returns 生成的位掩码
@@ -2855,7 +2766,7 @@ declare class QuerySystem {
     /**
      * 获取所有实体
      */
-    getAllEntities(): Entity[];
+    getAllEntities(): readonly Entity[];
     /**
      * 获取系统统计信息
      *
@@ -2884,39 +2795,12 @@ declare class QuerySystem {
         optimizationStats: {
             componentIndex: any;
             archetypeSystem: any;
-            dirtyTracking: any;
         };
         cacheStats: {
             size: number;
             hitRate: string;
         };
     };
-    /**
-     * 配置脏标记系统
-     *
-     * @param batchSize 批处理大小
-     * @param maxProcessingTime 最大处理时间
-     */
-    configureDirtyTracking(batchSize: number, maxProcessingTime: number): void;
-    /**
-     * 手动触发性能优化
-     */
-    optimizePerformance(): void;
-    /**
-     * 开始新的帧
-     */
-    beginFrame(): void;
-    /**
-     * 结束当前帧
-     */
-    endFrame(): void;
-    /**
-     * 标记实体组件已修改（用于脏标记追踪）
-     *
-     * @param entity 修改的实体
-     * @param componentTypes 修改的组件类型
-     */
-    markEntityDirty(entity: Entity, componentTypes: ComponentType[]): void;
     /**
      * 获取实体所属的原型信息
      *
@@ -3299,7 +3183,7 @@ declare class Scene implements IScene {
      */
     end(): void;
     /**
-     * 更新场景，更新实体组件、实体处理器等
+     * 更新场景
      */
     update(): void;
     /**
@@ -3307,6 +3191,11 @@ declare class Scene implements IScene {
      * @param name 实体名称
      */
     createEntity(name: string): Entity;
+    /**
+     * 清除所有EntitySystem的实体缓存
+     * 当实体或组件发生变化时调用
+     */
+    clearSystemEntityCaches(): void;
     /**
      * 在场景的实体列表中添加一个实体
      * @param entity 要添加的实体
@@ -3364,6 +3253,11 @@ declare class Scene implements IScene {
      * @param processor 要删除的处理器
      */
     removeEntityProcessor(processor: EntitySystem): void;
+    /**
+     * 从场景中删除系统（removeEntityProcessor的别名）
+     * @param system 系统
+     */
+    removeSystem(system: EntitySystem): void;
     /**
      * 获取指定类型的EntitySystem处理器
      * @param type 处理器类型
@@ -3413,7 +3307,7 @@ declare class Scene implements IScene {
  *         super(Transform, Velocity);
  *     }
  *
- *     protected process(entities: Entity[]): void {
+ *     protected process(entities: readonly Entity[]): void {
  *         for (const entity of entities) {
  *             const transform = entity.getComponent(Transform);
  *             const velocity = entity.getComponent(Velocity);
@@ -3430,10 +3324,21 @@ declare abstract class EntitySystem implements ISystemBase {
     private _systemName;
     private _initialized;
     private _matcher;
-    private _trackedEntities;
     private _eventListeners;
+    private _scene;
+    protected logger: ReturnType<typeof createLogger>;
     /**
-     * 获取系统处理的实体列表（动态查询）
+     * 实体ID映射缓存
+     */
+    private _entityIdMap;
+    private _entityIdMapVersion;
+    private _entityIdMapSize;
+    /**
+     * 统一的实体缓存管理器
+     */
+    private _entityCache;
+    /**
+     * 获取系统处理的实体列表
      */
     get entities(): readonly Entity[];
     /**
@@ -3454,7 +3359,6 @@ declare abstract class EntitySystem implements ISystemBase {
      */
     get systemName(): string;
     constructor(matcher?: Matcher);
-    private _scene;
     /**
      * 这个系统所属的场景
      */
@@ -3481,6 +3385,11 @@ declare abstract class EntitySystem implements ISystemBase {
      * 子类可以重写此方法进行初始化操作。
      */
     protected onInitialize(): void;
+    /**
+     * 清除实体缓存（内部使用）
+     * 当Scene中的实体发生变化时调用
+     */
+    clearEntityCache(): void;
     /**
      * 重置系统状态
      *
@@ -3509,20 +3418,22 @@ declare abstract class EntitySystem implements ISystemBase {
     private extractEntityIds;
     /**
      * ID集合交集运算
-     *
-     * 使用单次扫描算法，选择较小集合进行迭代以提高效率
      */
     private intersectIdSets;
     /**
      * ID集合差集运算
-     *
-     * 使用单次扫描算法计算setA - setB
      */
     private differenceIdSets;
+    /**
+     * 获取或构建实体ID映射
+     */
+    private getEntityIdMap;
+    /**
+     * 重建实体ID映射
+     */
+    private rebuildEntityIdMap;
     /**
      * 从ID集合构建Entity数组
-     *
-     * 先构建ID到Entity的映射，然后根据ID集合构建结果数组
      */
     private idSetToEntityArray;
     /**
@@ -3533,14 +3444,10 @@ declare abstract class EntitySystem implements ISystemBase {
     private executeComplexQuery;
     /**
      * 更新系统
-     *
-     * 在每帧调用，处理系统的主要逻辑。
      */
     update(): void;
     /**
      * 后期更新系统
-     *
-     * 在所有系统的update方法执行完毕后调用。
      */
     lateUpdate(): void;
     /**
@@ -3556,7 +3463,7 @@ declare abstract class EntitySystem implements ISystemBase {
      *
      * @param entities 要处理的实体列表
      */
-    protected process(entities: Entity[]): void;
+    protected process(entities: readonly Entity[]): void;
     /**
      * 后期处理实体列表
      *
@@ -3564,7 +3471,7 @@ declare abstract class EntitySystem implements ISystemBase {
      *
      * @param entities 要处理的实体列表
      */
-    protected lateProcess(_entities: Entity[]): void;
+    protected lateProcess(_entities: readonly Entity[]): void;
     /**
      * 系统处理完毕后调用
      *
@@ -3641,13 +3548,21 @@ declare abstract class EntitySystem implements ISystemBase {
      */
     protected removeEventListener<T = any>(eventType: string, handler: EventHandler<T>): void;
     /**
-     * 清理所有事件监听器
-     *
-     * 系统移除时自动调用，清理所有通过addEventListener添加的监听器。
+     * 清理手动添加的事件监听器
+     */
+    private cleanupManualEventListeners;
+    /**
+     * 框架内部销毁方法
+     * 由框架调用，处理系统的完整销毁流程
      */
-    private cleanupEventListeners;
+    destroy(): void;
+    /**
+     * 获取Logger名称
+     * 子类可以重写此方法来自定义logger名称
+     */
+    protected getLoggerName(): string;
     /**
-     * 系统销毁时的回调
+     * 用户销毁回调
      *
      * 当系统从场景中移除时调用，子类可以重写此方法进行清理操作。
      * 注意：事件监听器会被框架自动清理，无需手动处理。
@@ -3776,6 +3691,10 @@ interface IScene {
      * 创建实体
      */
     createEntity(name: string): Entity;
+    /**
+     * 清除所有EntitySystem的实体缓存
+     */
+    clearSystemEntityCaches(): void;
     /**
      * 添加实体
      */
@@ -3830,6 +3749,11 @@ interface ISceneConfig {
      * 调试配置
      */
     debug?: boolean;
+    /**
+     * 是否启用实体直接更新
+     * @default false
+     */
+    enableEntityDirectUpdate?: boolean;
 }
 
 /**
@@ -3887,6 +3811,12 @@ declare class Entity {
      * 用于发射组件相关事件
      */
     static eventBus: EventBus | null;
+    /**
+     * 通知Scene中的QuerySystem实体组件发生变动
+     *
+     * @param entity 发生组件变动的实体
+     */
+    private static notifyQuerySystems;
     /**
      * 实体名称
      */
@@ -4519,11 +4449,11 @@ declare class ECSFluentAPI {
      */
     query(): QueryBuilder;
     /**
-     * 查找实体（简化版）
+     * 查找实体
      * @param componentTypes 组件类型
      * @returns 实体数组
      */
-    find(...componentTypes: ComponentType[]): Entity[];
+    find(...componentTypes: ComponentType[]): readonly Entity[];
     /**
      * 查找第一个匹配的实体
      * @param componentTypes 组件类型
@@ -5656,15 +5586,18 @@ declare class Core {
     /**
      * 获取WorldManager实例
      *
+     * @param config 可选的WorldManager配置，用于覆盖默认配置
      * @returns WorldManager实例，如果未初始化则自动创建
      */
-    static getWorldManager(): WorldManager;
+    static getWorldManager(config?: Partial<IWorldManagerConfig>): WorldManager;
     /**
      * 启用World管理
      *
      * 显式启用World功能，用于多房间/多世界架构
+     *
+     * @param config 可选的WorldManager配置，用于覆盖默认配置
      */
-    static enableWorldManager(): WorldManager;
+    static enableWorldManager(config?: Partial<IWorldManagerConfig>): WorldManager;
     /**
      * 确保默认World存在
      *
@@ -5946,6 +5879,315 @@ declare abstract class IntervalSystem extends EntitySystem {
     protected getIntervalDelta(): number;
 }
 
+/**
+ * Worker处理函数类型
+ * 用户编写的处理逻辑，会被序列化到Worker中执行
+ */
+type WorkerProcessFunction<T extends Record<string, any> = any> = (entities: T[], deltaTime: number, config?: any) => T[] | Promise<T[]>;
+/**
+ * Worker配置接口
+ */
+interface WorkerSystemConfig {
+    /** 是否启用Worker并行处理 */
+    enableWorker?: boolean;
+    /** Worker数量，默认为CPU核心数，自动限制在系统最大值内 */
+    workerCount?: number;
+    /** 每个Worker处理的实体数量，用于控制负载分布 */
+    entitiesPerWorker?: number;
+    /** 系统配置数据，会传递给Worker */
+    systemConfig?: any;
+    /** 是否使用SharedArrayBuffer优化 */
+    useSharedArrayBuffer?: boolean;
+    /** 每个实体在SharedArrayBuffer中占用的Float32数量 */
+    entityDataSize?: number;
+    /** 最大实体数量（用于预分配SharedArrayBuffer） */
+    maxEntities?: number;
+}
+/**
+ * SharedArrayBuffer处理函数类型
+ */
+type SharedArrayBufferProcessFunction = (sharedFloatArray: Float32Array, startIndex: number, endIndex: number, deltaTime: number, systemConfig?: any) => void;
+/**
+ * 支持Worker并行处理的EntitySystem基类
+ *
+ * 支持传统Worker和SharedArrayBuffer两种优化模式：
+ * - 传统模式：数据序列化传输，适用于复杂计算
+ * - SharedArrayBuffer模式：零拷贝数据共享，适用于大量简单计算
+ *
+ * 用户需要实现：
+ * 1. extractEntityData - 定义数据提取逻辑
+ * 2. workerProcess - 编写处理函数（纯函数，可序列化）
+ * 3. applyResult - 定义结果应用逻辑
+ * 4. (可选) SharedArrayBuffer相关方法
+ *
+ * @example
+ * ```typescript
+ * class PhysicsSystem extends WorkerEntitySystem<PhysicsData> {
+ *     constructor() {
+ *         super(Matcher.all(Transform, Velocity), {
+ *             enableWorker: true,
+ *             workerCount: 8, // 指定8个worker，系统会自动限制在系统最大值内
+ *             entitiesPerWorker: 100, // 每个worker处理100个实体
+ *             useSharedArrayBuffer: true,
+ *             entityDataSize: 6, // x, y, vx, vy, radius, mass
+ *             maxEntities: 10000,
+ *             systemConfig: { gravity: 100, friction: 0.95 }
+ *         });
+ *     }
+ *
+ *     protected getDefaultEntityDataSize(): number {
+ *         return 6; // x, y, vx, vy, radius, mass
+ *     }
+ *
+ *     protected extractEntityData(entity: Entity): PhysicsData {
+ *         const transform = entity.getComponent(Transform);
+ *         const velocity = entity.getComponent(Velocity);
+ *         const physics = entity.getComponent(PhysicsComponent);
+ *         return {
+ *             x: transform.x,
+ *             y: transform.y,
+ *             vx: velocity.x,
+ *             vy: velocity.y,
+ *             radius: physics.radius,
+ *             mass: physics.mass
+ *         };
+ *     }
+ *
+ *     protected workerProcess(entities: PhysicsData[], deltaTime: number, config: any): PhysicsData[] {
+ *         return entities.map(entity => {
+ *             // 应用重力
+ *             entity.vy += config.gravity * deltaTime;
+ *
+ *             // 更新位置
+ *             entity.x += entity.vx * deltaTime;
+ *             entity.y += entity.vy * deltaTime;
+ *
+ *             // 应用摩擦力
+ *             entity.vx *= config.friction;
+ *             entity.vy *= config.friction;
+ *
+ *             return entity;
+ *         });
+ *     }
+ *
+ *     protected applyResult(entity: Entity, result: PhysicsData): void {
+ *         const transform = entity.getComponent(Transform);
+ *         const velocity = entity.getComponent(Velocity);
+ *
+ *         transform.x = result.x;
+ *         transform.y = result.y;
+ *         velocity.x = result.vx;
+ *         velocity.y = result.vy;
+ *     }
+ *
+ *     // SharedArrayBuffer优化支持
+ *     protected writeEntityToBuffer(entityData: PhysicsData, offset: number): void {
+ *         if (!this.sharedFloatArray) return;
+ *
+ *         this.sharedFloatArray[offset] = entityData.x;
+ *         this.sharedFloatArray[offset + 1] = entityData.y;
+ *         this.sharedFloatArray[offset + 2] = entityData.vx;
+ *         this.sharedFloatArray[offset + 3] = entityData.vy;
+ *         this.sharedFloatArray[offset + 4] = entityData.radius;
+ *         this.sharedFloatArray[offset + 5] = entityData.mass;
+ *     }
+ *
+ *     protected readEntityFromBuffer(offset: number): PhysicsData | null {
+ *         if (!this.sharedFloatArray) return null;
+ *
+ *         return {
+ *             x: this.sharedFloatArray[offset],
+ *             y: this.sharedFloatArray[offset + 1],
+ *             vx: this.sharedFloatArray[offset + 2],
+ *             vy: this.sharedFloatArray[offset + 3],
+ *             radius: this.sharedFloatArray[offset + 4],
+ *             mass: this.sharedFloatArray[offset + 5]
+ *         };
+ *     }
+ *
+ *     protected getSharedArrayBufferProcessFunction(): SharedArrayBufferProcessFunction {
+ *         return function(sharedFloatArray: Float32Array, startIndex: number, endIndex: number, deltaTime: number, config: any) {
+ *             const entitySize = 6;
+ *             for (let i = startIndex; i < endIndex; i++) {
+ *                 const offset = i * entitySize;
+ *
+ *                 // 读取数据
+ *                 let x = sharedFloatArray[offset];
+ *                 let y = sharedFloatArray[offset + 1];
+ *                 let vx = sharedFloatArray[offset + 2];
+ *                 let vy = sharedFloatArray[offset + 3];
+ *                 const radius = sharedFloatArray[offset + 4];
+ *                 const mass = sharedFloatArray[offset + 5];
+ *
+ *                 // 物理计算
+ *                 vy += config.gravity * deltaTime;
+ *                 x += vx * deltaTime;
+ *                 y += vy * deltaTime;
+ *                 vx *= config.friction;
+ *                 vy *= config.friction;
+ *
+ *                 // 写回数据
+ *                 sharedFloatArray[offset] = x;
+ *                 sharedFloatArray[offset + 1] = y;
+ *                 sharedFloatArray[offset + 2] = vx;
+ *                 sharedFloatArray[offset + 3] = vy;
+ *             }
+ *         };
+ *     }
+ * }
+ *
+ * interface PhysicsData {
+ *     x: number;
+ *     y: number;
+ *     vx: number;
+ *     vy: number;
+ *     radius: number;
+ *     mass: number;
+ * }
+ * ```
+ */
+declare abstract class WorkerEntitySystem<TEntityData = any> extends EntitySystem {
+    protected config: Required<Omit<WorkerSystemConfig, 'systemConfig' | 'entitiesPerWorker'>> & {
+        systemConfig?: any;
+        entitiesPerWorker?: number;
+    };
+    private workerPool;
+    private isProcessing;
+    protected sharedBuffer: SharedArrayBuffer | null;
+    protected sharedFloatArray: Float32Array | null;
+    private platformAdapter;
+    constructor(matcher?: Matcher, config?: WorkerSystemConfig);
+    /**
+     * 检查是否支持Worker
+     */
+    private isWorkerSupported;
+    /**
+     * 检查是否支持SharedArrayBuffer
+     */
+    private isSharedArrayBufferSupported;
+    /**
+     * 获取系统支持的最大Worker数量
+     */
+    private getMaxSystemWorkerCount;
+    /**
+     * 获取实体数据大小 - 子类必须实现
+     * 返回每个实体在SharedArrayBuffer中占用的Float32数量
+     */
+    protected abstract getDefaultEntityDataSize(): number;
+    /**
+     * 初始化SharedArrayBuffer
+     */
+    private initializeSharedArrayBuffer;
+    /**
+     * 初始化Worker池
+     */
+    private initializeWorkerPool;
+    /**
+     * 创建Worker脚本
+     */
+    private createWorkerScript;
+    /**
+     * 重写process方法，支持Worker并行处理
+     */
+    protected process(entities: readonly Entity[]): void;
+    /**
+     * 使用SharedArrayBuffer优化的Worker处理
+     */
+    private processWithSharedArrayBuffer;
+    /**
+     * 使用Worker并行处理
+     */
+    private processWithWorker;
+    /**
+     * 同步处理（fallback）
+     */
+    private processSynchronously;
+    /**
+     * 创建数据批次 - 支持用户指定每个Worker的实体数量
+     */
+    private createBatches;
+    /**
+     * 将实体数据写入SharedArrayBuffer
+     */
+    private writeEntitiesToSharedBuffer;
+    /**
+     * 将单个实体数据写入SharedArrayBuffer - 子类必须实现
+     * @param entityData 实体数据
+     * @param offset 在SharedArrayBuffer中的偏移位置（Float32索引）
+     */
+    protected abstract writeEntityToBuffer(entityData: TEntityData, offset: number): void;
+    /**
+     * 创建SharedArrayBuffer任务 - 支持用户指定每个Worker的实体数量
+     */
+    private createSharedArrayBufferTasks;
+    /**
+     * 从SharedArrayBuffer读取结果并应用
+     */
+    private readResultsFromSharedBuffer;
+    /**
+     * 从SharedArrayBuffer读取单个实体数据 - 子类必须实现
+     * @param offset 在SharedArrayBuffer中的偏移位置（Float32索引）
+     * @returns 实体数据或null
+     */
+    protected abstract readEntityFromBuffer(offset: number): TEntityData | null;
+    /**
+     * 获取SharedArrayBuffer处理函数 - 子类可选实现
+     * 返回一个函数，该函数将被序列化到Worker中执行
+     */
+    protected getSharedArrayBufferProcessFunction?(): SharedArrayBufferProcessFunction;
+    /**
+     * 提取实体数据 - 子类必须实现
+     *
+     * 将Entity转换为可序列化的数据对象
+     */
+    protected abstract extractEntityData(entity: Entity): TEntityData;
+    /**
+     * Worker处理函数 - 子类必须实现
+     *
+     * 这个函数会被序列化并在Worker中执行，因此：
+     * 1. 必须是纯函数，不能访问外部变量
+     * 2. 不能使用闭包或this
+     * 3. 只能使用标准JavaScript API
+     */
+    protected abstract workerProcess(entities: TEntityData[], deltaTime: number, systemConfig?: any): TEntityData[] | Promise<TEntityData[]>;
+    /**
+     * 应用处理结果 - 子类必须实现
+     *
+     * 将Worker处理的结果应用回Entity的组件
+     */
+    protected abstract applyResult(entity: Entity, result: TEntityData): void;
+    /**
+     * 更新Worker配置
+     */
+    updateConfig(newConfig: Partial<WorkerSystemConfig>): void;
+    /**
+     * 重新初始化整个 Worker 系统（包括 SharedArrayBuffer）
+     */
+    private reinitializeWorkerSystem;
+    /**
+     * 重新初始化 Worker 池（保持 SharedArrayBuffer）
+     */
+    private reinitializeWorkerPool;
+    /**
+     * 获取系统性能信息
+     */
+    getWorkerInfo(): {
+        enabled: boolean;
+        workerCount: number;
+        entitiesPerWorker?: number;
+        maxSystemWorkerCount: number;
+        isProcessing: boolean;
+        sharedArrayBufferSupported: boolean;
+        sharedArrayBufferEnabled: boolean;
+        currentMode: 'shared-buffer' | 'worker' | 'sync';
+    };
+    /**
+     * 销毁系统时清理Worker池
+     */
+    protected onDestroy(): void;
+    protected getLoggerName(): string;
+}
+
 /**
  * 64位位集合类，用于高效的位操作
  * 支持最多64个位的设置、清除、查询和逻辑运算
@@ -6525,827 +6767,437 @@ declare function getComponentInstanceTypeName(component: Component): string;
 declare function getSystemInstanceTypeName(system: EntitySystem): string;
 
 /**
- * 实体查询构建器
- *
- * 提供流式API来构建复杂的实体查询条件。支持组件过滤、标签过滤、状态过滤和自定义条件。
- *
- * @example
- * ```typescript
- * const results = entityManager.query()
- *     .withAll(PositionComponent, HealthComponent)
- *     .without(VelocityComponent)
- *     .withTag(1)
- *     .active()
- *     .where(entity => entity.name.startsWith("Player"))
- *     .execute();
- * ```
+ * 组件对象池，用于复用组件实例以减少内存分配
  */
-declare class EntityQueryBuilder {
-    private entityManager;
-    /** 必须包含的组件类型 */
-    private _allComponents;
-    /** 至少包含一个的组件类型 */
-    private _anyComponents;
-    /** 不能包含的组件类型 */
-    private _withoutComponents;
-    /** 必须包含的标签 */
-    private _withTags;
-    /** 不能包含的标签 */
-    private _withoutTags;
-    /** 是否只查询激活状态的实体 */
-    private _activeOnly;
-    /** 是否只查询启用状态的实体 */
-    private _enabledOnly;
-    /** 自定义过滤条件 */
-    private _customPredicates;
-    /**
-     * 创建查询构建器实例
-     * @param entityManager 实体管理器实例
-     */
-    constructor(entityManager: EntityManager);
-    /**
-     * 添加必须包含的组件条件
-     *
-     * 返回的实体必须包含所有指定的组件类型。
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withAll(...componentTypes: ComponentType[]): EntityQueryBuilder;
+declare class ComponentPool<T extends Component> {
+    private pool;
+    private createFn;
+    private resetFn?;
+    private maxSize;
+    constructor(createFn: () => T, resetFn?: (component: T) => void, maxSize?: number);
     /**
-     * 添加至少包含一个的组件条件
-     *
-     * 返回的实体必须至少包含其中一个指定的组件类型。
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 查询构建器实例，支持链式调用
+     * 获取一个组件实例
      */
-    withAny(...componentTypes: ComponentType[]): EntityQueryBuilder;
+    acquire(): T;
     /**
-     * 添加不能包含的组件条件
-     *
-     * 返回的实体不能包含任何指定的组件类型。
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 查询构建器实例，支持链式调用
+     * 释放一个组件实例回池中
      */
-    without(...componentTypes: ComponentType[]): EntityQueryBuilder;
+    release(component: T): void;
     /**
-     * 添加必须包含的标签条件
-     *
-     * 返回的实体必须具有指定的标签。
-     *
-     * @param tag 标签值
-     * @returns 查询构建器实例，支持链式调用
+     * 预填充对象池
      */
-    withTag(tag: number): EntityQueryBuilder;
+    prewarm(count: number): void;
     /**
-     * 添加不能包含的标签条件
-     *
-     * 返回的实体不能具有指定的标签。
-     *
-     * @param tag 标签值
-     * @returns 查询构建器实例，支持链式调用
+     * 清空对象池
      */
-    withoutTag(tag: number): EntityQueryBuilder;
+    clear(): void;
     /**
-     * 添加激活状态过滤条件
-     *
-     * 返回的实体必须处于激活状态（active = true）。
-     *
-     * @returns 查询构建器实例，支持链式调用
+     * 获取池中可用对象数量
      */
-    active(): EntityQueryBuilder;
+    getAvailableCount(): number;
     /**
-     * 添加启用状态过滤条件
-     *
-     * 返回的实体必须处于启用状态（enabled = true）。
-     *
-     * @returns 查询构建器实例，支持链式调用
+     * 获取池的最大容量
      */
-    enabled(): EntityQueryBuilder;
+    getMaxSize(): number;
+}
+/**
+ * 全局组件池管理器
+ */
+declare class ComponentPoolManager {
+    private static instance;
+    private pools;
+    private constructor();
+    static getInstance(): ComponentPoolManager;
     /**
-     * 添加自定义过滤条件
-     *
-     * 允许用户定义复杂的过滤逻辑。
-     *
-     * @param predicate 自定义过滤函数，接收实体作为参数，返回布尔值
-     * @returns 查询构建器实例，支持链式调用
-     *
-     * @example
-     * ```typescript
-     * .where(entity => entity.name.startsWith("Player"))
-     * .where(entity => entity.components.length > 5)
-     * ```
+     * 注册组件池
      */
-    where(predicate: (entity: Entity) => boolean): EntityQueryBuilder;
+    registerPool<T extends Component>(componentName: string, createFn: () => T, resetFn?: (component: T) => void, maxSize?: number): void;
     /**
-     * 执行查询并返回所有匹配的实体
-     *
-     * @returns 符合所有查询条件的实体数组
+     * 获取组件实例
      */
-    execute(): Entity[];
+    acquireComponent<T extends Component>(componentName: string): T | null;
     /**
-     * 执行查询并返回第一个匹配的实体
-     *
-     * @returns 第一个符合查询条件的实体，如果没有找到则返回null
+     * 释放组件实例
      */
-    first(): Entity | null;
+    releaseComponent<T extends Component>(componentName: string, component: T): void;
     /**
-     * 执行查询并返回匹配实体的数量
-     *
-     * @returns 符合查询条件的实体数量
+     * 预热所有池
      */
-    count(): number;
+    prewarmAll(count?: number): void;
     /**
-     * 对所有匹配的实体执行指定操作
-     *
-     * @param action 要执行的操作函数，接收匹配的实体作为参数
+     * 清空所有池
      */
-    forEach(action: (entity: Entity) => void): void;
+    clearAll(): void;
     /**
-     * 检查实体是否匹配所有查询条件
-     *
-     * 按优先级顺序检查各种过滤条件，一旦发现不匹配立即返回false。
-     *
-     * @param entity 要检查的实体
-     * @returns 实体是否匹配所有查询条件
-     */
-    private matchesEntity;
-}
-/**
- * 实体管理器
- *
- * 提供统一的实体管理和查询机制，支持高效的实体操作。
- * 包括实体的创建、销毁、查询和索引管理功能。
- *
- * @example
- * ```typescript
- * const entityManager = new EntityManager();
- *
- * // 创建实体
- * const player = entityManager.createEntity("Player");
- *
- * // 查询实体
- * const playerEntity = entityManager.getEntityByName("Player");
- *
- * // 复杂查询
- * const results = entityManager.query()
- *     .withAll(HealthComponent, PositionComponent)
- *     .active()
- *     .execute();
- * ```
- */
-declare class EntityManager {
-    /** 主要实体存储，使用ID作为键 */
-    private _entities;
-    /** 按名称索引的实体映射 */
-    private _entitiesByName;
-    /** 按标签索引的实体映射 */
-    private _entitiesByTag;
-    /** 实体ID分配器 */
-    private _identifierPool;
-    /** 已销毁实体的ID集合 */
-    private _destroyedEntities;
-    /** 性能优化系统 */
-    private _componentIndexManager;
-    private _archetypeSystem;
-    private _dirtyTrackingSystem;
-    /** 事件总线 */
-    private _eventBus;
-    /**
-     * 创建实体管理器实例
-     *
-     * 初始化内部数据结构和ID分配器。
+     * 重置管理器，移除所有注册的池
      */
-    constructor();
+    reset(): void;
     /**
-     * 获取实体总数
-     *
-     * @returns 当前管理的实体总数量
+     * 获取池统计信息
      */
-    get entityCount(): number;
+    getPoolStats(): Map<string, {
+        available: number;
+        maxSize: number;
+    }>;
     /**
-     * 获取激活状态的实体数量
-     *
-     * 只计算同时满足激活状态且未被销毁的实体。
-     *
-     * @returns 激活状态的实体数量
+     * 获取池利用率信息（用于调试）
      */
-    get activeEntityCount(): number;
+    getPoolUtilization(): Map<string, {
+        used: number;
+        total: number;
+        utilization: number;
+    }>;
     /**
-     * 创建新实体
-     *
-     * 分配唯一ID并将实体添加到管理系统中，同时更新相关索引。
-     *
-     * @param name 实体名称，如果未指定则使用时间戳生成默认名称
-     * @returns 创建的实体实例
-     *
-     * @example
-     * ```typescript
-     * const player = entityManager.createEntity("Player");
-     * const enemy = entityManager.createEntity(); // 使用默认名称
-     * ```
+     * 获取指定组件的池利用率
      */
-    createEntity(name?: string): Entity;
+    getComponentUtilization(componentName: string): number;
+}
+
+/**
+ * 类型工具类
+ * 提供类型相关的实用方法
+ */
+declare class TypeUtils {
     /**
-     * 批量创建实体
-     *
-     * 为了优化大量实体创建的性能，批量处理索引更新和事件发射。
-     * 适用于需要创建大量实体的场景，如子弹、粒子等。
-     *
-     * @param count 要创建的实体数量
-     * @param namePrefix 实体名称前缀，默认为 Entity
-     * @param skipEvents 是否跳过事件发射以提升性能，默认为 false
-     * @returns 创建的实体数组
-     *
-     * @example
-     * const bullets = entityManager.createEntitiesBatch(100, "Bullet", true);
-     * const particles = entityManager.createEntitiesBatch(500, "Particle");
+     * 获取对象的类型
+     * @param obj 对象
+     * @returns 对象的构造函数
      */
-    createEntitiesBatch(count: number, namePrefix?: string, skipEvents?: boolean): Entity[];
+    static getType(obj: any): any;
+}
+
+/**
+ * 数字扩展工具类
+ * 提供数字转换的实用方法
+ */
+declare class NumberExtension {
     /**
-     * 销毁实体
-     *
-     * 支持通过实体对象、名称或ID来销毁实体。
-     * 会清理所有相关索引并回收ID。
-     *
-     * @param entityOrId 要销毁的实体，可以是实体对象、名称字符串或ID数字
-     * @returns 是否成功销毁实体
-     *
-     * @example
-     * ```typescript
-     * // 通过实体对象销毁
-     * entityManager.destroyEntity(player);
-     *
-     * // 通过名称销毁
-     * entityManager.destroyEntity("Enemy_1");
-     *
-     * // 通过ID销毁
-     * entityManager.destroyEntity(123);
-     * ```
+     * 将值转换为数字
+     * @param value 要转换的值
+     * @returns 转换后的数字，如果值为undefined则返回0
      */
-    destroyEntity(entityOrId: Entity | string | number): boolean;
+    static toNumber(value: unknown): number;
+}
+
+/**
+ * 时间管理工具类
+ * 提供游戏时间相关的功能，包括帧时间、总时间、时间缩放等
+ */
+declare class Time {
     /**
-     * 获取所有实体
-     *
-     * 返回当前管理的所有实体的副本数组。
-     *
-     * @returns 所有实体的数组
+     * 上一帧到当前帧的时间间隔（秒）
      */
-    getAllEntities(): Entity[];
+    static deltaTime: number;
     /**
-     * 根据ID获取实体
-     *
-     * 支持字符串和数字类型的ID。
-     *
-     * @param id 实体ID，可以是字符串或数字
-     * @returns 对应的实体，如果不存在则返回null
+     * 未缩放的帧时间间隔（秒）
      */
-    getEntity(id: string | number): Entity | null;
+    static unscaledDeltaTime: number;
     /**
-     * 根据名称获取实体
-     *
-     * 如果存在多个同名实体，返回第一个找到的实体。
-     *
-     * @param name 实体名称
-     * @returns 匹配的实体，如果不存在则返回null
+     * 游戏开始以来的总时间（秒）
      */
-    getEntityByName(name: string): Entity | null;
+    static totalTime: number;
     /**
-     * 根据标签获取实体列表
-     *
-     * 返回所有具有指定标签的实体。
-     *
-     * @param tag 标签值
-     * @returns 具有指定标签的实体数组
+     * 未缩放的总时间（秒）
      */
-    getEntitiesByTag(tag: number): Entity[];
+    static unscaledTotalTime: number;
     /**
-     * 获取包含指定组件的所有实体
-     *
-     * 遍历所有实体，查找包含指定组件类型的实体。
-     *
-     * @param componentType 组件类型
-     * @returns 包含指定组件的实体数组
-     *
-     * @example
-     * ```typescript
-     * const entitiesWithHealth = entityManager.getEntitiesWithComponent(HealthComponent);
-     * ```
+     * 时间缩放比例
      */
-    getEntitiesWithComponent<T extends Component>(componentType: ComponentType<T>): Entity[];
+    static timeScale: number;
     /**
-     * 创建查询构建器
-     *
-     * 返回一个新的查询构建器实例，用于构建复杂的实体查询。
-     *
-     * @returns 新的查询构建器实例
-     *
-     * @example
-     * ```typescript
-     * const results = entityManager.query()
-     *     .withAll(PositionComponent, HealthComponent)
-     *     .without(VelocityComponent)
-     *     .active()
-     *     .execute();
-     * ```
+     * 当前帧数
      */
-    query(): EntityQueryBuilder;
+    static frameCount: number;
     /**
-     * 使用组件索引进行多组件查询
-     *
-     * @param componentTypes 组件类型数组
-     * @param operation 查询操作：'AND' 或 'OR'
-     * @returns 匹配的实体集合
+     * 使用外部引擎提供的deltaTime更新时间信息
+     * @param deltaTime 外部引擎提供的帧时间间隔（秒）
      */
-    queryWithComponentIndex(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    static update(deltaTime: number): void;
     /**
-     * 标记实体组件已修改
-     *
-     * @param entity 修改的实体
-     * @param componentTypes 修改的组件类型
+     * 场景改变时重置时间
      */
-    markEntityDirty(entity: Entity, componentTypes: ComponentType[]): void;
+    static sceneChanged(): void;
     /**
-     * 获取性能优化统计信息
+     * 检查指定的时间间隔是否已经过去
+     * @param interval 时间间隔（秒）
+     * @param lastTime 上次检查的时间
+     * @returns 是否已经过去指定时间
      */
-    getOptimizationStats(): any;
+    static checkEvery(interval: number, lastTime: number): boolean;
+}
+
+/**
+ * 平台适配器接口
+ * 用于适配不同的运行环境（浏览器、微信小游戏、字节跳动小游戏等）
+ */
+interface IPlatformAdapter {
     /**
-     * 获取事件总线实例
-     *
-     * 允许外部代码监听和发射ECS相关事件。
-     *
-     * @returns 事件总线实例
+     * 平台名称
      */
-    get eventBus(): EventBus;
+    readonly name: string;
     /**
-     * 更新名称索引
-     *
-     * 维护按名称查找实体的索引结构。支持添加和移除操作。
-     *
-     * @param entity 要更新索引的实体
-     * @param isAdd true表示添加到索引，false表示从索引中移除
+     * 平台版本信息
      */
-    private updateNameIndex;
+    readonly version?: string;
     /**
-     * 更新标签索引
-     *
-     * 维护按标签查找实体的索引结构。支持添加和移除操作。
-     *
-     * @param entity 要更新索引的实体
-     * @param isAdd true表示添加到索引，false表示从索引中移除
+     * 检查是否支持Worker
      */
-    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 {
+    isWorkerSupported(): boolean;
     /**
-     * 组件稀疏集合
-     *
-     * 核心存储结构，处理所有实体和组件的索引操作。
+     * 检查是否支持SharedArrayBuffer
      */
-    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();
+    isSharedArrayBufferSupported(): boolean;
     /**
-     * 添加实体到索引
+     * 获取硬件并发数（CPU核心数）
      */
-    addEntity(entity: Entity): void;
+    getHardwareConcurrency(): number;
     /**
-     * 从索引中移除实体
+     * 创建Worker
+     * @param script Worker脚本内容
+     * @param options Worker选项
      */
-    removeEntity(entity: Entity): void;
+    createWorker(script: string, options?: WorkerCreationOptions): PlatformWorker;
     /**
-     * 查询包含指定组件的实体
+     * 创建SharedArrayBuffer
+     * @param length 缓冲区大小（字节）
      */
-    query(componentType: ComponentType): Set<Entity>;
+    createSharedArrayBuffer(length: number): SharedArrayBuffer | null;
     /**
-     * 批量查询多个组件
+     * 获取高精度时间戳
      */
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    getHighResTimestamp(): number;
     /**
-     * 获取索引统计信息
+     * 获取平台特定的配置
      */
-    getStats(): IndexStats;
+    getPlatformConfig(): PlatformConfig;
     /**
-     * 清空索引
+     * 异步获取平台配置（包含需要异步获取的信息）
      */
-    clear(): void;
-}
-
-/**
- * 脏标记类型
- */
-declare enum DirtyFlag {
-    /** 组件数据已修改 */
-    COMPONENT_MODIFIED = 1,
-    /** 组件已添加 */
-    COMPONENT_ADDED = 2,
-    /** 组件已移除 */
-    COMPONENT_REMOVED = 4,
-    /** 实体位置已改变 */
-    TRANSFORM_CHANGED = 8,
-    /** 实体状态已改变 */
-    STATE_CHANGED = 16,
-    /** 自定义标记1 */
-    CUSTOM_1 = 256,
-    /** 自定义标记2 */
-    CUSTOM_2 = 512,
-    /** 自定义标记3 */
-    CUSTOM_3 = 1024,
-    /** 所有标记 */
-    ALL = 4294967295
-}
-/**
- * 脏标记数据
- */
-interface DirtyData {
-    /** 实体引用 */
-    entity: Entity;
-    /** 脏标记位 */
-    flags: number;
-    /** 修改的组件类型列表 */
-    modifiedComponents: Set<ComponentType>;
-    /** 标记时间戳 */
-    timestamp: number;
-    /** 帧编号 */
-    frameNumber: number;
+    getPlatformConfigAsync?(): Promise<PlatformConfig>;
 }
 /**
- * 脏标记监听器
- */
-interface DirtyListener {
-    /** 感兴趣的标记类型 */
-    flags: number;
-    /** 回调函数 */
-    callback: (dirtyData: DirtyData) => void;
-    /** 监听器优先级（数字越小优先级越高） */
-    priority?: number;
-}
-/**
- * 脏标记统计信息
- */
-interface DirtyStats {
-    /** 当前脏实体数量 */
-    dirtyEntityCount: number;
-    /** 总标记次数 */
-    totalMarkings: number;
-    /** 总清理次数 */
-    totalCleanups: number;
-    /** 监听器数量 */
-    listenerCount: number;
-    /** 平均每帧脏实体数量 */
-    avgDirtyPerFrame: number;
-    /** 内存使用量估算 */
-    estimatedMemoryUsage: number;
-}
-/**
- * 脏标记追踪系统
- *
- * 提供高效的组件和实体变更追踪，避免不必要的计算和更新。
- * 支持细粒度的脏标记和批量处理机制。
- *
- * @example
- * ```typescript
- * const dirtySystem = new DirtyTrackingSystem();
- *
- * // 标记实体的位置组件已修改
- * dirtySystem.markDirty(entity, DirtyFlag.TRANSFORM_CHANGED, [PositionComponent]);
- *
- * // 监听位置变化
- * dirtySystem.addListener({
- *     flags: DirtyFlag.TRANSFORM_CHANGED,
- *     callback: (data) => {
- *         logger.debug('Entity position changed:', data.entity.name);
- *     }
- * });
- *
- * // 处理所有脏标记
- * dirtySystem.processDirtyEntities();
- * ```
+ * Worker创建选项
  */
-declare class DirtyTrackingSystem {
-    private static readonly _logger;
-    /** 脏实体映射表 */
-    private _dirtyEntities;
-    /** 脏标记监听器 */
-    private _listeners;
-    /** 性能统计 */
-    private _stats;
-    /** 当前帧编号 */
-    private _currentFrame;
-    private _batchSize;
-    private _maxProcessingTime;
-    /** 延迟处理队列 */
-    private _processingQueue;
-    private _isProcessing;
+interface WorkerCreationOptions {
     /**
-     * 标记实体为脏状态
-     *
-     * @param entity 要标记的实体
-     * @param flags 脏标记位
-     * @param modifiedComponents 修改的组件类型列表
+     * Worker类型
      */
-    markDirty(entity: Entity, flags: DirtyFlag, modifiedComponents?: ComponentType[]): void;
+    type?: 'classic' | 'module';
     /**
-     * 检查实体是否有指定的脏标记
-     *
-     * @param entity 要检查的实体
-     * @param flags 要检查的标记位
-     * @returns 是否有指定的脏标记
+     * 凭据模式
      */
-    isDirty(entity: Entity, flags?: DirtyFlag): boolean;
+    credentials?: 'omit' | 'same-origin' | 'include';
     /**
-     * 清除实体的脏标记
-     *
-     * @param entity 要清除的实体
-     * @param flags 要清除的标记位，默认清除所有
+     * Worker名称（用于调试）
      */
-    clearDirty(entity: Entity, flags?: DirtyFlag): void;
-    /**
-     * 获取所有脏实体
-     *
-     * @param flags 过滤标记位，只返回包含指定标记的实体
-     * @returns 脏实体数据数组
-     */
-    getDirtyEntities(flags?: DirtyFlag): DirtyData[];
+    name?: string;
+}
+/**
+ * 平台Worker接口
+ */
+interface PlatformWorker {
     /**
-     * 批量处理脏实体
-     *
-     * 使用时间分片的方式处理脏实体，避免单帧卡顿
+     * 发送消息到Worker
      */
-    processDirtyEntities(): void;
+    postMessage(message: any, transfer?: Transferable[]): void;
     /**
-     * 添加脏标记监听器
-     *
-     * @param listener 监听器配置
+     * 监听Worker消息
      */
-    addListener(listener: DirtyListener): void;
+    onMessage(handler: (event: {
+        data: any;
+    }) => void): void;
     /**
-     * 移除脏标记监听器
-     *
-     * @param callback 要移除的回调函数
+     * 监听Worker错误
      */
-    removeListener(callback: (dirtyData: DirtyData) => void): void;
+    onError(handler: (error: ErrorEvent) => void): void;
     /**
-     * 开始新的帧
+     * 终止Worker
      */
-    beginFrame(): void;
+    terminate(): void;
     /**
-     * 结束当前帧
+     * Worker状态
      */
-    endFrame(): void;
+    readonly state: 'running' | 'terminated';
+}
+/**
+ * 平台配置
+ */
+interface PlatformConfig {
     /**
-     * 获取统计信息
+     * 最大Worker数量限制
      */
-    getStats(): DirtyStats;
+    maxWorkerCount: number;
     /**
-     * 清空所有脏标记和统计信息
+     * 是否支持模块Worker
      */
-    clear(): void;
+    supportsModuleWorker: boolean;
     /**
-     * 配置批量处理参数
-     *
-     * @param batchSize 每次处理的最大实体数量
-     * @param maxProcessingTime 每帧最大处理时间（毫秒）
+     * 是否支持Transferable Objects
      */
-    configureBatchProcessing(batchSize: number, maxProcessingTime: number): void;
+    supportsTransferableObjects: boolean;
     /**
-     * 处理单个脏实体
+     * SharedArrayBuffer的最大大小限制（字节）
      */
-    private processEntity;
+    maxSharedArrayBufferSize?: number;
     /**
-     * 通知监听器
+     * 平台特定的Worker脚本前缀（如果需要）
      */
-    private notifyListeners;
+    workerScriptPrefix?: string;
     /**
-     * 帧结束时的统计更新
+     * 平台特定的限制和特性
      */
-    private onFrameEnd;
+    limitations?: {
+        /**
+         * 是否禁用eval（影响动态脚本创建）
+         */
+        noEval?: boolean;
+        /**
+         * 是否需要特殊的Worker初始化
+         */
+        requiresWorkerInit?: boolean;
+        /**
+         * 内存限制（字节）
+         */
+        memoryLimit?: number;
+        /**
+         * Worker是否不受支持（用于明确标记不支持Worker的平台）
+         */
+        workerNotSupported?: boolean;
+        /**
+         * Worker限制说明列表
+         */
+        workerLimitations?: string[];
+    };
     /**
-     * 估算内存使用量
+     * 平台特定的扩展属性
      */
-    private estimateMemoryUsage;
+    extensions?: Record<string, any>;
 }
-
 /**
- * 组件对象池，用于复用组件实例以减少内存分配
+ * 平台检测结果
  */
-declare class ComponentPool<T extends Component> {
-    private pool;
-    private createFn;
-    private resetFn?;
-    private maxSize;
-    constructor(createFn: () => T, resetFn?: (component: T) => void, maxSize?: number);
+interface PlatformDetectionResult {
     /**
-     * 获取一个组件实例
-     */
-    acquire(): T;
-    /**
-     * 释放一个组件实例回池中
-     */
-    release(component: T): void;
-    /**
-     * 预填充对象池
+     * 平台类型
      */
-    prewarm(count: number): void;
+    platform: 'browser' | 'wechat-minigame' | 'bytedance-minigame' | 'alipay-minigame' | 'baidu-minigame' | 'nodejs' | 'unknown';
     /**
-     * 清空对象池
+     * 是否确定检测结果
      */
-    clear(): void;
+    confident: boolean;
     /**
-     * 获取池中可用对象数量
+     * 检测到的特征
      */
-    getAvailableCount(): number;
+    features: string[];
     /**
-     * 获取池的最大容量
+     * 建议使用的适配器类名
      */
-    getMaxSize(): number;
+    adapterClass?: string;
 }
+
 /**
- * 全局组件池管理器
+ * 平台检测器
+ * 自动检测当前运行环境并返回对应的平台信息
  */
-declare class ComponentPoolManager {
-    private static instance;
-    private pools;
-    private constructor();
-    static getInstance(): ComponentPoolManager;
+declare class PlatformDetector {
     /**
-     * 注册组件池
+     * 检测当前平台
      */
-    registerPool<T extends Component>(componentName: string, createFn: () => T, resetFn?: (component: T) => void, maxSize?: number): void;
-    /**
-     * 获取组件实例
-     */
-    acquireComponent<T extends Component>(componentName: string): T | null;
-    /**
-     * 释放组件实例
-     */
-    releaseComponent<T extends Component>(componentName: string, component: T): void;
-    /**
-     * 预热所有池
-     */
-    prewarmAll(count?: number): void;
+    static detect(): PlatformDetectionResult;
     /**
-     * 清空所有池
+     * 检测是否为微信小游戏环境
      */
-    clearAll(): void;
+    private static isWeChatMiniGame;
     /**
-     * 重置管理器，移除所有注册的池
+     * 检测是否为字节跳动小游戏环境
      */
-    reset(): void;
+    private static isByteDanceMiniGame;
     /**
-     * 获取池统计信息
+     * 检测是否为Node.js环境
      */
-    getPoolStats(): Map<string, {
-        available: number;
-        maxSize: number;
-    }>;
+    private static isNodeJS;
     /**
-     * 获取池利用率信息（用于调试）
+     * 检测是否为支付宝小游戏环境
      */
-    getPoolUtilization(): Map<string, {
-        used: number;
-        total: number;
-        utilization: number;
-    }>;
+    private static isAlipayMiniGame;
     /**
-     * 获取指定组件的池利用率
+     * 检测是否为百度小游戏环境
      */
-    getComponentUtilization(componentName: string): number;
-}
-
-/**
- * 类型工具类
- * 提供类型相关的实用方法
- */
-declare class TypeUtils {
+    private static isBaiduMiniGame;
     /**
-     * 获取对象的类型
-     * @param obj 对象
-     * @returns 对象的构造函数
+     * 检测是否为浏览器环境
      */
-    static getType(obj: any): any;
-}
-
-/**
- * 数字扩展工具类
- * 提供数字转换的实用方法
- */
-declare class NumberExtension {
+    private static isBrowser;
     /**
-     * 将值转换为数字
-     * @param value 要转换的值
-     * @returns 转换后的数字，如果值为undefined则返回0
+     * 获取详细的环境信息（用于调试）
      */
-    static toNumber(value: unknown): number;
+    static getDetailedInfo(): Record<string, any>;
 }
 
 /**
- * 时间管理工具类
- * 提供游戏时间相关的功能，包括帧时间、总时间、时间缩放等
+ * 平台管理器
+ * 用户需要手动注册平台适配器
  */
-declare class Time {
-    /**
-     * 上一帧到当前帧的时间间隔（秒）
-     */
-    static deltaTime: number;
+declare class PlatformManager {
+    private static instance;
+    private adapter;
+    private readonly logger;
+    private constructor();
     /**
-     * 未缩放的帧时间间隔（秒）
+     * 获取单例实例
      */
-    static unscaledDeltaTime: number;
+    static getInstance(): PlatformManager;
     /**
-     * 游戏开始以来的总时间（秒）
+     * 获取当前平台适配器
      */
-    static totalTime: number;
+    getAdapter(): IPlatformAdapter;
     /**
-     * 未缩放的总时间（秒）
+     * 注册平台适配器
      */
-    static unscaledTotalTime: number;
+    registerAdapter(adapter: IPlatformAdapter): void;
     /**
-     * 时间缩放比例
+     * 检查是否已注册适配器
      */
-    static timeScale: number;
+    hasAdapter(): boolean;
     /**
-     * 当前帧数
+     * 获取平台适配器信息（用于调试）
      */
-    static frameCount: number;
+    getAdapterInfo(): any;
     /**
-     * 使用外部引擎提供的deltaTime更新时间信息
-     * @param deltaTime 外部引擎提供的帧时间间隔（秒）
+     * 检查当前平台是否支持特定功能
      */
-    static update(deltaTime: number): void;
+    supportsFeature(feature: 'worker' | 'shared-array-buffer' | 'transferable-objects' | 'module-worker'): boolean;
     /**
-     * 场景改变时重置时间
+     * 获取基础的Worker配置信息（不做自动决策）
+     * 用户应该根据自己的业务需求来配置Worker参数
      */
-    static sceneChanged(): void;
+    getBasicWorkerConfig(): {
+        platformSupportsWorker: boolean;
+        platformSupportsSharedArrayBuffer: boolean;
+        platformMaxWorkerCount: number;
+        platformLimitations: any;
+    };
     /**
-     * 检查指定的时间间隔是否已经过去
-     * @param interval 时间间隔（秒）
-     * @param lastTime 上次检查的时间
-     * @returns 是否已经过去指定时间
+     * 异步获取完整的平台配置信息（包含性能信息）
      */
-    static checkEvery(interval: number, lastTime: number): boolean;
+    getFullPlatformConfig(): Promise<any>;
 }
 
-export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMask64Utils, Bits, COMPONENT_TYPE_NAME, Colors, 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$1 as 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, World, WorldManager, createECSAPI, createLogger, getComponentInstanceTypeName, getComponentTypeName, getSystemInstanceTypeName, getSystemTypeName, resetLoggerColors, setGlobalLogLevel, setLoggerColors };
-export type { Archetype, ArchetypeQueryResult, BitMask64Data, 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, IWorldConfig, IWorldManagerConfig, IndexStats, LoggerColorConfig, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+/**
+ * 平台适配模块导出
+ */
+
+declare function registerPlatformAdapter(adapter: IPlatformAdapter): void;
+declare function getCurrentAdapter(): IPlatformAdapter;
+declare function getBasicWorkerConfig(): {
+    platformSupportsWorker: boolean;
+    platformSupportsSharedArrayBuffer: boolean;
+    platformMaxWorkerCount: number;
+    platformLimitations: any;
+};
+declare function getFullPlatformConfig(): Promise<any>;
+declare function supportsFeature(feature: 'worker' | 'shared-array-buffer' | 'transferable-objects' | 'module-worker'): boolean;
+declare function hasAdapter(): boolean;
+
+export { BitMask64Utils, Bits, COMPONENT_TYPE_NAME, Colors, Component, ComponentDataCollector, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSparseSet, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityProcessorList, EntitySystem, EventBus, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, PlatformDetector, PlatformManager, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeMap, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, WorkerEntitySystem, World, WorldManager, createECSAPI, createLogger, getBasicWorkerConfig, getComponentInstanceTypeName, getComponentTypeName, getCurrentAdapter, getFullPlatformConfig, getSystemInstanceTypeName, getSystemTypeName, hasAdapter, registerPlatformAdapter, resetLoggerColors, setGlobalLogLevel, setLoggerColors, supportsFeature };
+export type { BitMask64Data, ComponentType$1 as ComponentType, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPlatformAdapter, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IWorldConfig, IWorldManagerConfig, LoggerColorConfig, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PlatformConfig, PlatformDetectionResult, PlatformWorker, PoolStats, SharedArrayBufferProcessFunction, WorkerCreationOptions, WorkerProcessFunction, WorkerSystemConfig };