@esengine/ecs-framework 2.1.43 → 2.1.45

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.43
+ * @esengine/ecs-framework v2.1.45
  * TypeScript definitions
  */
 /**
@@ -1838,6 +1838,9 @@ declare class SoAStorage<T extends Component> {
     private resize;
     getActiveIndices(): number[];
     getFieldArray(fieldName: string): Float32Array | Float64Array | Int32Array | null;
+    getTypedFieldArray<K extends keyof T>(fieldName: K): Float32Array | Float64Array | Int32Array | null;
+    getEntityIndex(entityId: number): number | undefined;
+    getEntityIdByIndex(index: number): number | undefined;
     size(): number;
     clear(): void;
     compact(): void;
@@ -2021,6 +2024,52 @@ declare class ComponentStorage<T extends Component> {
 declare class ComponentStorageManager {
     private static readonly _logger;
     private storages;
+    /**
+     * 检查组件类型是否启用SoA存储
+     * @param componentType 组件类型
+     * @returns 是否为SoA存储
+     */
+    isSoAStorage<T extends Component>(componentType: ComponentType<T>): boolean;
+    /**
+     * 获取SoA存储器（类型安全）
+     * @param componentType 组件类型
+     * @returns SoA存储器或null
+     */
+    getSoAStorage<T extends Component>(componentType: ComponentType<T>): SoAStorage<T> | null;
+    /**
+     * 直接获取SoA字段数组（类型安全）
+     * @param componentType 组件类型
+     * @param fieldName 字段名
+     * @returns TypedArray或null
+     */
+    getFieldArray<T extends Component>(componentType: ComponentType<T>, fieldName: string): Float32Array | Float64Array | Int32Array | null;
+    /**
+     * 直接获取SoA字段数组（类型安全，带字段名检查）
+     * @param componentType 组件类型
+     * @param fieldName 字段名（类型检查）
+     * @returns TypedArray或null
+     */
+    getTypedFieldArray<T extends Component, K extends keyof T>(componentType: ComponentType<T>, fieldName: K): Float32Array | Float64Array | Int32Array | null;
+    /**
+     * 获取SoA存储的活跃索引
+     * @param componentType 组件类型
+     * @returns 活跃索引数组或空数组
+     */
+    getActiveIndices<T extends Component>(componentType: ComponentType<T>): number[];
+    /**
+     * 获取实体在SoA存储中的索引
+     * @param componentType 组件类型
+     * @param entityId 实体ID
+     * @returns 存储索引或undefined
+     */
+    getEntityIndex<T extends Component>(componentType: ComponentType<T>, entityId: number): number | undefined;
+    /**
+     * 根据索引获取实体ID
+     * @param componentType 组件类型
+     * @param index 存储索引
+     * @returns 实体ID或undefined
+     */
+    getEntityIdByIndex<T extends Component>(componentType: ComponentType<T>, index: number): number | undefined;
     /**
      * 获取或创建组件存储器（默认原始存储）
      * @param componentType 组件类型
@@ -2079,155 +2128,6 @@ declare class ComponentStorageManager {
     clear(): void;
 }
 
-/**
- * 组件索引类型
- */
-declare enum IndexType {
-    /** 哈希索引 - 最快查找 */
-    HASH = "hash",
-    /** 位图索引 - 内存高效 */
-    BITMAP = "bitmap",
-    /** 排序索引 - 支持范围查询 */
-    SORTED = "sorted"
-}
-/**
- * 索引统计信息
- */
-interface IndexStats {
-    /** 索引类型 */
-    type: IndexType;
-    /** 索引大小 */
-    size: number;
-    /** 内存使用量（字节） */
-    memoryUsage: number;
-    /** 查询次数 */
-    queryCount: number;
-    /** 平均查询时间（毫秒） */
-    avgQueryTime: number;
-    /** 最后更新时间 */
-    lastUpdated: number;
-}
-/**
- * 组件索引接口
- */
-interface IComponentIndex {
-    /** 索引类型 */
-    readonly type: IndexType;
-    /** 添加实体到索引 */
-    addEntity(entity: Entity): void;
-    /** 从索引中移除实体 */
-    removeEntity(entity: Entity): void;
-    /** 查询包含指定组件的实体 */
-    query(componentType: ComponentType): Set<Entity>;
-    /** 批量查询多个组件 */
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    /** 清空索引 */
-    clear(): void;
-    /** 获取索引统计信息 */
-    getStats(): IndexStats;
-}
-/**
- * 哈希索引实现
- *
- * 使用Map数据结构，提供O(1)的查找性能。
- * 适合大多数查询场景。
- */
-declare class HashComponentIndex implements IComponentIndex {
-    readonly type = IndexType.HASH;
-    private _componentToEntities;
-    private _entityToComponents;
-    private _queryCount;
-    private _totalQueryTime;
-    private _lastUpdated;
-    private _setPool;
-    private _componentTypeSetPool;
-    addEntity(entity: Entity): void;
-    removeEntity(entity: Entity): void;
-    query(componentType: ComponentType): Set<Entity>;
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    clear(): void;
-    getStats(): IndexStats;
-}
-/**
- * 位图索引实现
- *
- * 使用位操作进行快速集合运算，内存效率高。
- * 适合有限组件类型和大量实体的场景。
- */
-declare class BitmapComponentIndex implements IComponentIndex {
-    readonly type = IndexType.BITMAP;
-    private _componentTypeToBit;
-    private _entityToBitmap;
-    private _bitToEntities;
-    private _nextBit;
-    private _queryCount;
-    private _totalQueryTime;
-    private _lastUpdated;
-    addEntity(entity: Entity): void;
-    removeEntity(entity: Entity): void;
-    query(componentType: ComponentType): Set<Entity>;
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    clear(): void;
-    getStats(): IndexStats;
-}
-/**
- * 智能组件索引管理器
- *
- * 根据使用模式自动选择最优的索引策略。
- * 支持动态切换索引类型以获得最佳性能。
- */
-declare class ComponentIndexManager {
-    private _activeIndex;
-    private _indexHistory;
-    private _autoOptimize;
-    private _optimizationThreshold;
-    constructor(initialType?: IndexType);
-    /**
-     * 添加实体到索引
-     */
-    addEntity(entity: Entity): void;
-    /**
-     * 从索引中移除实体
-     */
-    removeEntity(entity: Entity): void;
-    /**
-     * 查询包含指定组件的实体
-     */
-    query(componentType: ComponentType): Set<Entity>;
-    /**
-     * 批量查询多个组件
-     */
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    /**
-     * 手动切换索引类型
-     */
-    switchIndexType(type: IndexType): void;
-    /**
-     * 启用/禁用自动优化
-     */
-    setAutoOptimize(enabled: boolean): void;
-    /**
-     * 获取当前索引统计信息
-     */
-    getStats(): IndexStats;
-    /**
-     * 获取所有索引类型的历史统计信息
-     */
-    getAllStats(): Map<IndexType, IndexStats>;
-    /**
-     * 清空索引
-     */
-    clear(): void;
-    /**
-     * 创建指定类型的索引
-     */
-    private createIndex;
-    /**
-     * 检查是否需要优化索引
-     */
-    private checkOptimization;
-}
-
 /**
  * 原型标识符
  */
@@ -2638,12 +2538,6 @@ declare class QuerySystem {
             hitRate: string;
         };
     };
-    /**
-     * 切换组件索引类型
-     *
-     * @param indexType 新的索引类型
-     */
-    switchComponentIndexType(indexType: IndexType): void;
     /**
      * 配置脏标记系统
      *
@@ -4678,163 +4572,610 @@ declare class ECSFluentAPI {
 declare function createECSAPI(scene: IScene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem): ECSFluentAPI;
 
 /**
- * 实体数据收集器
+ * 全局系统接口
+ * 全局系统是在World级别运行的系统，不依赖特定Scene
  */
-declare class EntityDataCollector {
-    collectEntityData(): IEntityDebugData;
-    getRawEntityList(): Array<{
-        id: number;
-        name: string;
-        active: boolean;
-        enabled: boolean;
-        activeInHierarchy: boolean;
-        componentCount: number;
-        componentTypes: string[];
-        parentId: number | null;
-        childIds: number[];
-        depth: number;
-        tag: number;
-        updateOrder: number;
-    }>;
-    getEntityDetails(entityId: number): any;
-    private getSceneInfo;
-    collectEntityDataWithMemory(): IEntityDebugData;
-    private collectArchetypeData;
-    private getArchetypeDistributionFast;
-    private getTopEntitiesByComponentsFast;
-    private collectArchetypeDataWithMemory;
-    private extractArchetypeStatistics;
-    private extractArchetypeStatisticsWithMemory;
-    private getArchetypeDistribution;
-    private getArchetypeDistributionWithMemory;
-    private getTopEntitiesByComponents;
-    private getTopEntitiesByComponentsWithMemory;
-    private getEmptyEntityDebugData;
-    private calculateFallbackEntityStats;
-    estimateEntityMemoryUsage(entity: any): number;
-    calculateObjectSize(obj: any, excludeKeys?: string[]): number;
-    private buildEntityHierarchyTree;
+interface IGlobalSystem {
     /**
-     * 构建实体层次结构节点
+     * 系统名称
      */
-    private buildEntityHierarchyNode;
+    readonly name: string;
     /**
-     * 构建实体详情映射
+     * 初始化系统
      */
-    private buildEntityDetailsMap;
+    initialize?(): void;
     /**
-     * 构建实体基础信息
+     * 更新系统
      */
-    private buildFallbackEntityInfo;
+    update(deltaTime?: number): void;
     /**
-     * 提取组件详细信息
+     * 重置系统
      */
-    extractComponentDetails(components: Component[]): Array<{
-        typeName: string;
-        properties: Record<string, any>;
-    }>;
+    reset?(): void;
     /**
-     * 获取组件的完整属性信息（仅在需要时调用）
+     * 销毁系统
      */
-    getComponentProperties(entityId: number, componentIndex: number): Record<string, any>;
+    destroy?(): void;
+}
+/**
+ * World配置接口
+ */
+interface IWorldConfig {
     /**
-     * 格式化属性值
+     * World名称
      */
-    private formatPropertyValue;
+    name?: string;
     /**
-     * 格式化对象第一层
+     * 是否启用调试模式
      */
-    private formatObjectFirstLevel;
+    debug?: boolean;
     /**
-     * 创建懒加载占位符
+     * 最大Scene数量限制
      */
-    private createLazyLoadPlaceholder;
+    maxScenes?: number;
     /**
-     * 获取对象摘要信息
+     * 是否自动清理空Scene
      */
-    private getObjectSummary;
+    autoCleanup?: boolean;
+}
+/**
+ * World类 - ECS世界管理器
+ *
+ * World是Scene的容器，每个World可以管理多个Scene。
+ * 这种设计允许创建独立的游戏世界，如：
+ * - 游戏房间（每个房间一个World）
+ * - 不同的游戏模式
+ * - 独立的模拟环境
+ *
+ * @example
+ * ```typescript
+ * // 创建游戏房间的World
+ * const roomWorld = new World({ name: 'Room_001' });
+ *
+ * // 在World中创建Scene
+ * const gameScene = roomWorld.createScene('game', new Scene());
+ * const uiScene = roomWorld.createScene('ui', new Scene());
+ *
+ * // 更新整个World
+ * roomWorld.update(deltaTime);
+ * ```
+ */
+declare class World {
+    readonly name: string;
+    private readonly _config;
+    private readonly _scenes;
+    private readonly _activeScenes;
+    private readonly _globalSystems;
+    private _isActive;
+    private _createdAt;
+    constructor(config?: IWorldConfig);
     /**
-     * 生成对象ID
+     * 创建并添加Scene到World
      */
-    private generateObjectId;
+    createScene<T extends IScene>(sceneId: string, sceneInstance?: T): T;
     /**
-     * 展开懒加载对象（供调试面板调用）
+     * 移除Scene
      */
-    expandLazyObject(entityId: number, componentIndex: number, propertyPath: string): any;
+    removeScene(sceneId: string): boolean;
     /**
-     * 根据路径获取对象
+     * 获取Scene
      */
-    private getObjectByPath;
-}
-
-/**
- * 系统数据收集器
- */
-declare class SystemDataCollector {
+    getScene<T extends IScene>(sceneId: string): T | null;
     /**
-     * 收集系统数据
+     * 获取所有Scene ID
      */
-    collectSystemData(performanceMonitor: any): ISystemDebugData;
-}
-
-/**
- * 性能数据收集器
- */
-declare class PerformanceDataCollector {
-    private frameTimeHistory;
-    private maxHistoryLength;
-    private lastGCCount;
-    private gcCollections;
-    private lastMemoryCheck;
+    getSceneIds(): string[];
     /**
-     * 收集性能数据
+     * 获取所有Scene
      */
-    collectPerformanceData(performanceMonitor: any): IPerformanceDebugData;
+    getAllScenes(): IScene[];
     /**
-     * 获取ECS框架整体性能数据
+     * 设置Scene激活状态
      */
-    private getECSPerformanceData;
+    setSceneActive(sceneId: string, active: boolean): void;
     /**
-     * 获取系统性能数据
+     * 检查Scene是否激活
      */
-    private getSystemPerformance;
+    isSceneActive(sceneId: string): boolean;
     /**
-     * 获取内存详情
+     * 获取活跃Scene数量
      */
-    private getMemoryDetails;
+    getActiveSceneCount(): number;
     /**
-     * 更新GC计数
+     * 添加全局System
+     * 全局System会在所有激活Scene之前更新
      */
-    private updateGCCount;
-}
-
-/**
- * 组件数据收集器
- */
-declare class ComponentDataCollector {
-    private static componentSizeCache;
+    addGlobalSystem<T extends IGlobalSystem>(system: T): T;
     /**
-     * 收集组件数据（轻量版，不计算实际内存大小）
+     * 移除全局System
      */
-    collectComponentData(): IComponentDebugData;
+    removeGlobalSystem(system: IGlobalSystem): boolean;
     /**
-     * 获取组件类型的估算内存大小（基于预设值，不进行实际计算）
+     * 获取全局System
      */
-    private getEstimatedComponentSize;
-    private calculateQuickObjectSize;
+    getGlobalSystem<T extends IGlobalSystem>(type: new (...args: any[]) => T): T | null;
     /**
-     * 为内存快照功能提供的详细内存计算
-     * 只在用户主动请求内存快照时调用
+     * 启动World
      */
-    calculateDetailedComponentMemory(typeName: string): number;
+    start(): void;
     /**
-     * 估算对象内存大小（仅用于内存快照）
-     * 优化版本：减少递归深度，提高性能
+     * 停止World
      */
-    private estimateObjectSize;
-    static clearCache(): void;
-}
-
+    stop(): void;
+    /**
+     * 更新World中的全局System
+     * 注意：此方法由Core.update()调用，不应直接调用
+     */
+    updateGlobalSystems(): void;
+    /**
+     * 更新World中的所有激活Scene
+     * 注意：此方法由Core.update()调用，不应直接调用
+     */
+    updateScenes(): void;
+    /**
+     * 销毁World
+     */
+    destroy(): void;
+    /**
+     * 获取World状态
+     */
+    getStatus(): {
+        name: string;
+        isActive: boolean;
+        sceneCount: number;
+        activeSceneCount: number;
+        globalSystemCount: number;
+        createdAt: number;
+        config: {
+            /**
+             * World名称
+             */
+            name?: string;
+            /**
+             * 是否启用调试模式
+             */
+            debug?: boolean;
+            /**
+             * 最大Scene数量限制
+             */
+            maxScenes?: number;
+            /**
+             * 是否自动清理空Scene
+             */
+            autoCleanup?: boolean;
+        };
+        scenes: {
+            id: string;
+            isActive: boolean;
+            name: string;
+        }[];
+    };
+    /**
+     * 获取World统计信息
+     */
+    getStats(): {
+        totalEntities: number;
+        totalSystems: number;
+        memoryUsage: number;
+        performance: {
+            averageUpdateTime: number;
+            maxUpdateTime: number;
+        };
+    };
+    /**
+     * 检查是否应该执行自动清理
+     */
+    private shouldAutoCleanup;
+    /**
+     * 执行清理操作
+     */
+    private cleanup;
+    /**
+     * 检查World是否激活
+     */
+    get isActive(): boolean;
+    /**
+     * 获取Scene数量
+     */
+    get sceneCount(): number;
+    /**
+     * 获取创建时间
+     */
+    get createdAt(): number;
+}
+
+/**
+ * WorldManager配置接口
+ */
+interface IWorldManagerConfig {
+    /**
+     * 最大World数量
+     */
+    maxWorlds?: number;
+    /**
+     * 是否自动清理空World
+     */
+    autoCleanup?: boolean;
+    /**
+     * 清理间隔（毫秒）
+     */
+    cleanupInterval?: number;
+    /**
+     * 是否启用调试模式
+     */
+    debug?: boolean;
+}
+/**
+ * World管理器 - 管理所有World实例
+ *
+ * WorldManager是全局单例，负责管理所有World的生命周期。
+ * 每个World都是独立的ECS环境，可以包含多个Scene。
+ *
+ * 设计理念：
+ * - Core负责单Scene的传统ECS管理
+ * - World负责多Scene的管理和协调
+ * - WorldManager负责多World的全局管理
+ *
+ * @example
+ * ```typescript
+ * // 获取全局WorldManager
+ * const worldManager = WorldManager.getInstance();
+ *
+ * // 创建游戏房间World
+ * const roomWorld = worldManager.createWorld('room_001', {
+ *     name: 'GameRoom_001',
+ *     maxScenes: 5
+ * });
+ *
+ * // 在游戏循环中更新所有World
+ * worldManager.updateAll(deltaTime);
+ * ```
+ */
+declare class WorldManager {
+    private static _instance;
+    private readonly _config;
+    private readonly _worlds;
+    private readonly _activeWorlds;
+    private _cleanupTimer;
+    private _isRunning;
+    private constructor();
+    /**
+     * 获取WorldManager单例实例
+     */
+    static getInstance(config?: IWorldManagerConfig): WorldManager;
+    /**
+     * 重置WorldManager实例（主要用于测试）
+     */
+    static reset(): void;
+    /**
+     * 创建新World
+     */
+    createWorld(worldId: string, config?: IWorldConfig): World;
+    /**
+     * 移除World
+     */
+    removeWorld(worldId: string): boolean;
+    /**
+     * 获取World
+     */
+    getWorld(worldId: string): World | null;
+    /**
+     * 获取所有World ID
+     */
+    getWorldIds(): string[];
+    /**
+     * 获取所有World
+     */
+    getAllWorlds(): World[];
+    /**
+     * 设置World激活状态
+     */
+    setWorldActive(worldId: string, active: boolean): void;
+    /**
+     * 检查World是否激活
+     */
+    isWorldActive(worldId: string): boolean;
+    /**
+     * 获取所有激活的World
+     * 注意：此方法供Core.update()使用
+     */
+    getActiveWorlds(): World[];
+    /**
+     * 启动所有World
+     */
+    startAll(): void;
+    /**
+     * 停止所有World
+     */
+    stopAll(): void;
+    /**
+     * 查找满足条件的World
+     */
+    findWorlds(predicate: (world: World) => boolean): World[];
+    /**
+     * 根据名称查找World
+     */
+    findWorldByName(name: string): World | null;
+    /**
+     * 获取WorldManager统计信息
+     */
+    getStats(): {
+        totalWorlds: number;
+        activeWorlds: number;
+        totalScenes: number;
+        totalEntities: number;
+        totalSystems: number;
+        memoryUsage: number;
+        isRunning: boolean;
+        config: {
+            /**
+             * 最大World数量
+             */
+            maxWorlds?: number;
+            /**
+             * 是否自动清理空World
+             */
+            autoCleanup?: boolean;
+            /**
+             * 清理间隔（毫秒）
+             */
+            cleanupInterval?: number;
+            /**
+             * 是否启用调试模式
+             */
+            debug?: boolean;
+        };
+        worlds: any[];
+    };
+    /**
+     * 获取详细状态信息
+     */
+    getDetailedStatus(): {
+        worlds: {
+            id: string;
+            isActive: boolean;
+            status: {
+                name: string;
+                isActive: boolean;
+                sceneCount: number;
+                activeSceneCount: number;
+                globalSystemCount: number;
+                createdAt: number;
+                config: {
+                    name?: string;
+                    debug?: boolean;
+                    maxScenes?: number;
+                    autoCleanup?: boolean;
+                };
+                scenes: {
+                    id: string;
+                    isActive: boolean;
+                    name: string;
+                }[];
+            };
+        }[];
+        totalWorlds: number;
+        activeWorlds: number;
+        totalScenes: number;
+        totalEntities: number;
+        totalSystems: number;
+        memoryUsage: number;
+        isRunning: boolean;
+        config: {
+            /**
+             * 最大World数量
+             */
+            maxWorlds?: number;
+            /**
+             * 是否自动清理空World
+             */
+            autoCleanup?: boolean;
+            /**
+             * 清理间隔（毫秒）
+             */
+            cleanupInterval?: number;
+            /**
+             * 是否启用调试模式
+             */
+            debug?: boolean;
+        };
+    };
+    /**
+     * 清理空World
+     */
+    cleanup(): number;
+    /**
+     * 销毁WorldManager
+     */
+    destroy(): void;
+    /**
+     * 启动清理定时器
+     */
+    private startCleanupTimer;
+    /**
+     * 停止清理定时器
+     */
+    private stopCleanupTimer;
+    /**
+     * 判断World是否应该被清理
+     */
+    private shouldCleanupWorld;
+    /**
+     * 获取World总数
+     */
+    get worldCount(): number;
+    /**
+     * 获取激活World数量
+     */
+    get activeWorldCount(): number;
+    /**
+     * 检查是否正在运行
+     */
+    get isRunning(): boolean;
+    /**
+     * 获取配置
+     */
+    get config(): IWorldManagerConfig;
+}
+
+/**
+ * 实体数据收集器
+ */
+declare class EntityDataCollector {
+    collectEntityData(): IEntityDebugData;
+    getRawEntityList(): Array<{
+        id: number;
+        name: string;
+        active: boolean;
+        enabled: boolean;
+        activeInHierarchy: boolean;
+        componentCount: number;
+        componentTypes: string[];
+        parentId: number | null;
+        childIds: number[];
+        depth: number;
+        tag: number;
+        updateOrder: number;
+    }>;
+    getEntityDetails(entityId: number): any;
+    private getSceneInfo;
+    collectEntityDataWithMemory(): IEntityDebugData;
+    private collectArchetypeData;
+    private getArchetypeDistributionFast;
+    private getTopEntitiesByComponentsFast;
+    private collectArchetypeDataWithMemory;
+    private extractArchetypeStatistics;
+    private extractArchetypeStatisticsWithMemory;
+    private getArchetypeDistribution;
+    private getArchetypeDistributionWithMemory;
+    private getTopEntitiesByComponents;
+    private getTopEntitiesByComponentsWithMemory;
+    private getEmptyEntityDebugData;
+    private calculateFallbackEntityStats;
+    estimateEntityMemoryUsage(entity: any): number;
+    calculateObjectSize(obj: any, excludeKeys?: string[]): number;
+    private buildEntityHierarchyTree;
+    /**
+     * 构建实体层次结构节点
+     */
+    private buildEntityHierarchyNode;
+    /**
+     * 构建实体详情映射
+     */
+    private buildEntityDetailsMap;
+    /**
+     * 构建实体基础信息
+     */
+    private buildFallbackEntityInfo;
+    /**
+     * 提取组件详细信息
+     */
+    extractComponentDetails(components: Component[]): Array<{
+        typeName: string;
+        properties: Record<string, any>;
+    }>;
+    /**
+     * 获取组件的完整属性信息（仅在需要时调用）
+     */
+    getComponentProperties(entityId: number, componentIndex: number): Record<string, any>;
+    /**
+     * 格式化属性值
+     */
+    private formatPropertyValue;
+    /**
+     * 格式化对象第一层
+     */
+    private formatObjectFirstLevel;
+    /**
+     * 创建懒加载占位符
+     */
+    private createLazyLoadPlaceholder;
+    /**
+     * 获取对象摘要信息
+     */
+    private getObjectSummary;
+    /**
+     * 生成对象ID
+     */
+    private generateObjectId;
+    /**
+     * 展开懒加载对象（供调试面板调用）
+     */
+    expandLazyObject(entityId: number, componentIndex: number, propertyPath: string): any;
+    /**
+     * 根据路径获取对象
+     */
+    private getObjectByPath;
+}
+
+/**
+ * 系统数据收集器
+ */
+declare class SystemDataCollector {
+    /**
+     * 收集系统数据
+     */
+    collectSystemData(performanceMonitor: any): ISystemDebugData;
+}
+
+/**
+ * 性能数据收集器
+ */
+declare class PerformanceDataCollector {
+    private frameTimeHistory;
+    private maxHistoryLength;
+    private lastGCCount;
+    private gcCollections;
+    private lastMemoryCheck;
+    /**
+     * 收集性能数据
+     */
+    collectPerformanceData(performanceMonitor: any): IPerformanceDebugData;
+    /**
+     * 获取ECS框架整体性能数据
+     */
+    private getECSPerformanceData;
+    /**
+     * 获取系统性能数据
+     */
+    private getSystemPerformance;
+    /**
+     * 获取内存详情
+     */
+    private getMemoryDetails;
+    /**
+     * 更新GC计数
+     */
+    private updateGCCount;
+}
+
+/**
+ * 组件数据收集器
+ */
+declare class ComponentDataCollector {
+    private static componentSizeCache;
+    /**
+     * 收集组件数据（轻量版，不计算实际内存大小）
+     */
+    collectComponentData(): IComponentDebugData;
+    /**
+     * 获取组件类型的估算内存大小（基于预设值，不进行实际计算）
+     */
+    private getEstimatedComponentSize;
+    private calculateQuickObjectSize;
+    /**
+     * 为内存快照功能提供的详细内存计算
+     * 只在用户主动请求内存快照时调用
+     */
+    calculateDetailedComponentMemory(typeName: string): number;
+    /**
+     * 估算对象内存大小（仅用于内存快照）
+     * 优化版本：减少递归深度，提高性能
+     */
+    private estimateObjectSize;
+    static clearCache(): void;
+}
+
 /**
  * 场景数据收集器
  */
@@ -5040,6 +5381,18 @@ declare class Core {
      * 当设置为true时，游戏循环将暂停执行。
      */
     static paused: boolean;
+    /**
+     * 默认World ID
+     *
+     * 用于单Scene模式的默认World标识
+     */
+    private static readonly DEFAULT_WORLD_ID;
+    /**
+     * 默认Scene ID
+     *
+     * 用于单Scene模式的默认Scene标识
+     */
+    private static readonly DEFAULT_SCENE_ID;
     /**
      * 全局核心实例
      */
@@ -5060,12 +5413,6 @@ declare class Core {
      * 在调试模式下会启用额外的性能监控和错误检查。
      */
     readonly debug: boolean;
-    /**
-     * 待切换的场景
-     *
-     * 存储下一帧要切换到的场景实例。
-     */
-    _nextScene: IScene | null;
     /**
      * 全局管理器集合
      *
@@ -5096,16 +5443,18 @@ declare class Core {
      * 提供便捷的ECS操作接口。
      */
     _ecsAPI?: ECSFluentAPI;
-    /**
-     * 当前活动场景
-     */
-    _scene?: IScene;
     /**
      * 调试管理器
      *
      * 负责收集和发送调试数据。
      */
     _debugManager?: DebugManager;
+    /**
+     * World管理器
+     *
+     * 管理多个World实例，支持多房间/多世界架构。
+     */
+    _worldManager?: WorldManager;
     /**
      * Core配置
      */
@@ -5127,58 +5476,24 @@ declare class Core {
      */
     static get Instance(): Core;
     /**
-     * 获取当前活动的场景
+     * 获取当前活动的场景（属性访问器）
      *
      * @returns 当前场景实例，如果没有则返回null
      */
     static get scene(): IScene | null;
     /**
-     * 设置当前场景（已废弃）
+     * 获取当前活动的场景（方法调用）
      *
-     * @deprecated 请使用 Core.setScene() 方法代替。scene setter 可能导致场景延迟激活的时序问题，
-     * 而 setScene() 提供更好的类型安全性和可预测的激活时序。
-     *
-     * 迁移示例：
-     * ```typescript
-     * // 旧方式（已废弃）
-     * Core.scene = myScene;
-     *
-     * // 新方式（推荐）
-     * Core.setScene(myScene);
-     * ```
-     *
-     * 如果当前没有场景，会立即切换；否则会在下一帧切换。
-     *
-     * @param value - 场景实例
+     * @returns 当前场景实例，如果没有则返回null
      */
-    static set scene(value: IScene | null);
+    static getScene<T extends IScene>(): T | null;
     /**
-     * 类型安全的场景设置方法（推荐）
-     *
-     * 这是设置场景的推荐方法，提供更好的类型安全性和可预测的激活时序。
-     * 相比于 scene setter，此方法能确保场景正确初始化和激活。
-     *
-     * 如果当前没有场景，会立即切换；否则会在下一帧切换。
+     * 设置当前场景
      *
      * @param scene - 要设置的场景实例
      * @returns 设置的场景实例，便于链式调用
-     *
-     * @example
-     * ```typescript
-     * const myScene = new MyScene();
-     * Core.setScene(myScene);
-     *
-     * // 链式调用
-     * const scene = Core.setScene(new MyScene()).addSystem(new MySystem());
-     * ```
      */
     static setScene<T extends IScene>(scene: T): T;
-    /**
-     * 类型安全的场景获取方法
-     *
-     * @returns 当前场景实例
-     */
-    static getScene<T extends IScene>(): T | null;
     /**
      * 创建Core实例
      *
@@ -5288,11 +5603,23 @@ declare class Core {
      */
     static get supportsBigInt(): boolean;
     /**
-     * 内部场景设置方法
+     * 获取WorldManager实例
      *
-     * @param scene - 要设置的场景实例
+     * @returns WorldManager实例，如果未初始化则自动创建
+     */
+    static getWorldManager(): WorldManager;
+    /**
+     * 启用World管理
+     *
+     * 显式启用World功能，用于多房间/多世界架构
      */
-    private setSceneInternal;
+    static enableWorldManager(): WorldManager;
+    /**
+     * 确保默认World存在
+     *
+     * 内部方法，用于懒初始化默认World
+     */
+    private ensureDefaultWorld;
     /**
      * 场景切换回调
      *
@@ -5784,6 +6111,316 @@ declare class ComponentTypeManager {
     get registeredTypeCount(): number;
 }
 
+/**
+ * 稀疏集合实现
+ *
+ * 提供O(1)的插入、删除、查找操作，同时保持数据的紧凑存储。
+ * 使用密集数组存储实际数据，稀疏映射提供快速访问
+ *
+ * @template T 存储的数据类型
+ *
+ * @example
+ * ```typescript
+ * const sparseSet = new SparseSet<Entity>();
+ *
+ * sparseSet.add(entity1);
+ * sparseSet.add(entity2);
+ *
+ * if (sparseSet.has(entity1)) {
+ *     sparseSet.remove(entity1);
+ * }
+ *
+ * sparseSet.forEach((entity, index) => {
+ *     console.log(`Entity at index ${index}: ${entity.name}`);
+ * });
+ * ```
+ */
+declare class SparseSet<T> {
+    /**
+     * 密集存储数组
+     *
+     * 连续存储所有有效数据，确保遍历时的缓存友好性。
+     */
+    private _dense;
+    /**
+     * 稀疏映射表
+     *
+     * 将数据项映射到密集数组中的索引，提供O(1)的查找性能。
+     */
+    private _sparse;
+    /**
+     * 添加元素到集合
+     *
+     * @param item 要添加的元素
+     * @returns 是否成功添加（false表示元素已存在）
+     */
+    add(item: T): boolean;
+    /**
+     * 从集合中移除元素
+     *
+     * 使用swap-and-pop技术保持数组紧凑性：
+     * 1. 将要删除的元素与最后一个元素交换
+     * 2. 删除最后一个元素
+     * 3. 更新映射表
+     *
+     * @param item 要移除的元素
+     * @returns 是否成功移除（false表示元素不存在）
+     */
+    remove(item: T): boolean;
+    /**
+     * 检查元素是否存在于集合中
+     *
+     * @param item 要检查的元素
+     * @returns 元素是否存在
+     */
+    has(item: T): boolean;
+    /**
+     * 获取元素在密集数组中的索引
+     *
+     * @param item 要查询的元素
+     * @returns 索引，如果元素不存在则返回undefined
+     */
+    getIndex(item: T): number | undefined;
+    /**
+     * 根据索引获取元素
+     *
+     * @param index 索引
+     * @returns 元素，如果索引无效则返回undefined
+     */
+    getByIndex(index: number): T | undefined;
+    /**
+     * 获取集合大小
+     */
+    get size(): number;
+    /**
+     * 检查集合是否为空
+     */
+    get isEmpty(): boolean;
+    /**
+     * 遍历集合中的所有元素
+     *
+     * 保证遍历顺序与添加顺序一致（除非中间有删除操作）。
+     * 遍历性能优秀，因为数据在内存中连续存储。
+     *
+     * @param callback 遍历回调函数
+     */
+    forEach(callback: (item: T, index: number) => void): void;
+    /**
+     * 映射集合中的所有元素
+     *
+     * @param callback 映射回调函数
+     * @returns 映射后的新数组
+     */
+    map<U>(callback: (item: T, index: number) => U): U[];
+    /**
+     * 过滤集合中的元素
+     *
+     * @param predicate 过滤条件
+     * @returns 满足条件的元素数组
+     */
+    filter(predicate: (item: T, index: number) => boolean): T[];
+    /**
+     * 查找第一个满足条件的元素
+     *
+     * @param predicate 查找条件
+     * @returns 找到的元素，如果没有则返回undefined
+     */
+    find(predicate: (item: T, index: number) => boolean): T | undefined;
+    /**
+     * 检查是否存在满足条件的元素
+     *
+     * @param predicate 检查条件
+     * @returns 是否存在满足条件的元素
+     */
+    some(predicate: (item: T, index: number) => boolean): boolean;
+    /**
+     * 检查是否所有元素都满足条件
+     *
+     * @param predicate 检查条件
+     * @returns 是否所有元素都满足条件
+     */
+    every(predicate: (item: T, index: number) => boolean): boolean;
+    /**
+     * 获取密集数组的只读副本
+     *
+     * 返回数组的浅拷贝，确保外部无法直接修改内部数据。
+     */
+    getDenseArray(): readonly T[];
+    /**
+     * 获取密集数组的直接引用（内部使用）
+     *
+     * 警告：直接修改返回的数组会破坏数据结构的完整性。
+     * 仅在性能关键场景下使用，并确保不会修改数组内容。
+     */
+    getDenseArrayUnsafe(): readonly T[];
+    /**
+     * 清空集合
+     */
+    clear(): void;
+    /**
+     * 转换为数组
+     */
+    toArray(): T[];
+    /**
+     * 转换为Set
+     */
+    toSet(): Set<T>;
+    /**
+     * 获取内存使用统计信息
+     */
+    getMemoryStats(): {
+        denseArraySize: number;
+        sparseMapSize: number;
+        totalMemory: number;
+    };
+    /**
+     * 验证数据结构的完整性
+     *
+     * 调试用方法，检查内部数据结构是否一致。
+     */
+    validate(): boolean;
+}
+
+/**
+ * 组件稀疏集合实现
+ *
+ * 结合通用稀疏集合和组件位掩码
+ *
+ * 存储结构：
+ * - 稀疏集合存储实体
+ * - 位掩码数组存储组件信息
+ * - 组件类型映射表
+ */
+declare class ComponentSparseSet {
+    /**
+     * 实体稀疏集合
+     *
+     * 存储所有拥有组件的实体，提供O(1)的实体操作。
+     */
+    private _entities;
+    /**
+     * 组件位掩码数组
+     *
+     * 与实体稀疏集合的密集数组对应，存储每个实体的组件位掩码。
+     * 数组索引与稀疏集合的密集数组索引一一对应。
+     */
+    private _componentMasks;
+    /**
+     * 组件类型到实体集合的映射
+     *
+     * 维护每个组件类型对应的实体集合，用于快速的单组件查询。
+     */
+    private _componentToEntities;
+    /**
+     * 实体集合对象池
+     *
+     * 使用core库的Pool系统来管理PoolableEntitySet对象的复用。
+     */
+    private static _entitySetPool;
+    constructor();
+    /**
+     * 添加实体到组件索引
+     *
+     * 分析实体的组件组成，生成位掩码，并更新所有相关索引。
+     *
+     * @param entity 要添加的实体
+     */
+    addEntity(entity: Entity): void;
+    /**
+     * 从组件索引中移除实体
+     *
+     * 清理实体相关的所有索引数据，保持数据结构的紧凑性。
+     *
+     * @param entity 要移除的实体
+     */
+    removeEntity(entity: Entity): void;
+    /**
+     * 查询包含指定组件的所有实体
+     *
+     * @param componentType 组件类型
+     * @returns 包含该组件的实体集合
+     */
+    queryByComponent(componentType: ComponentType): Set<Entity>;
+    /**
+     * 多组件查询（AND操作）
+     *
+     * 查找同时包含所有指定组件的实体。
+     *
+     * @param componentTypes 组件类型数组
+     * @returns 满足条件的实体集合
+     */
+    queryMultipleAnd(componentTypes: ComponentType[]): Set<Entity>;
+    /**
+     * 多组件查询（OR操作）
+     *
+     * 查找包含任意一个指定组件的实体。
+     *
+     * @param componentTypes 组件类型数组
+     * @returns 满足条件的实体集合
+     */
+    queryMultipleOr(componentTypes: ComponentType[]): Set<Entity>;
+    /**
+     * 检查实体是否包含指定组件
+     *
+     * @param entity 实体
+     * @param componentType 组件类型
+     * @returns 是否包含该组件
+     */
+    hasComponent(entity: Entity, componentType: ComponentType): boolean;
+    /**
+     * 获取实体的组件位掩码
+     *
+     * @param entity 实体
+     * @returns 组件位掩码，如果实体不存在则返回undefined
+     */
+    getEntityMask(entity: Entity): IBigIntLike | undefined;
+    /**
+     * 获取所有实体
+     *
+     * @returns 所有实体的数组
+     */
+    getAllEntities(): Entity[];
+    /**
+     * 获取实体数量
+     */
+    get size(): number;
+    /**
+     * 检查是否为空
+     */
+    get isEmpty(): boolean;
+    /**
+     * 遍历所有实体
+     *
+     * @param callback 遍历回调函数
+     */
+    forEach(callback: (entity: Entity, mask: IBigIntLike, index: number) => void): void;
+    /**
+     * 清空所有数据
+     */
+    clear(): void;
+    /**
+     * 获取内存使用统计
+     */
+    getMemoryStats(): {
+        entitiesMemory: number;
+        masksMemory: number;
+        mappingsMemory: number;
+        totalMemory: number;
+    };
+    /**
+     * 验证数据结构完整性
+     */
+    validate(): boolean;
+    /**
+     * 获取实体的组件类型集合
+     */
+    private getEntityComponentTypes;
+    /**
+     * 更新组件类型到实体的映射
+     */
+    private updateComponentMappings;
+}
+
 /**
  * 存储组件类型名称的Symbol键
  */
@@ -6227,6 +6864,99 @@ declare class EntityManager {
     private updateTagIndex;
 }
 
+/**
+ * 索引统计信息
+ */
+interface IndexStats {
+    /** 索引大小 */
+    size: number;
+    /** 内存使用量（字节） */
+    memoryUsage: number;
+    /** 查询次数 */
+    queryCount: number;
+    /** 平均查询时间（毫秒） */
+    avgQueryTime: number;
+    /** 最后更新时间 */
+    lastUpdated: number;
+}
+/**
+ * 组件索引接口
+ */
+interface IComponentIndex {
+    /** 添加实体到索引 */
+    addEntity(entity: Entity): void;
+    /** 从索引中移除实体 */
+    removeEntity(entity: Entity): void;
+    /** 查询包含指定组件的实体 */
+    query(componentType: ComponentType): Set<Entity>;
+    /** 批量查询多个组件 */
+    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    /** 清空索引 */
+    clear(): void;
+    /** 获取索引统计信息 */
+    getStats(): IndexStats;
+}
+/**
+ * 通用组件索引实现
+ *
+ * 基于Sparse Set算法：
+ * - O(1)的实体添加、删除、查找
+ * - 高效的位运算查询
+ * - 内存紧凑的存储结构
+ * - 缓存友好的遍历性能
+ */
+declare class ComponentIndex implements IComponentIndex {
+    /**
+     * 组件稀疏集合
+     *
+     * 核心存储结构，处理所有实体和组件的索引操作。
+     */
+    private _sparseSet;
+    private _queryCount;
+    private _totalQueryTime;
+    private _lastUpdated;
+    constructor();
+    addEntity(entity: Entity): void;
+    removeEntity(entity: Entity): void;
+    query(componentType: ComponentType): Set<Entity>;
+    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    clear(): void;
+    getStats(): IndexStats;
+}
+/**
+ * 组件索引管理器
+ *
+ * 使用统一的组件索引实现，自动优化查询性能。
+ */
+declare class ComponentIndexManager {
+    private _index;
+    constructor();
+    /**
+     * 添加实体到索引
+     */
+    addEntity(entity: Entity): void;
+    /**
+     * 从索引中移除实体
+     */
+    removeEntity(entity: Entity): void;
+    /**
+     * 查询包含指定组件的实体
+     */
+    query(componentType: ComponentType): Set<Entity>;
+    /**
+     * 批量查询多个组件
+     */
+    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    /**
+     * 获取索引统计信息
+     */
+    getStats(): IndexStats;
+    /**
+     * 清空索引
+     */
+    clear(): void;
+}
+
 /**
  * 脏标记类型
  */
@@ -6582,5 +7312,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler, BigIntFactory, BitmapComponentIndex, Bits, COMPONENT_TYPE_NAME, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, HighPrecision, IdentifierPool, IndexType, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeMap, SoAStorage, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI, createLogger, getComponentInstanceTypeName, getComponentTypeName, getSystemInstanceTypeName, getSystemTypeName, setGlobalLogLevel };
-export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+export { ArchetypeSystem, AsyncEventHandler, BigIntFactory, Bits, COMPONENT_TYPE_NAME, Component, ComponentDataCollector, ComponentIndex, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSparseSet, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeMap, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, World, WorldManager, createECSAPI, createLogger, getComponentInstanceTypeName, getComponentTypeName, getSystemInstanceTypeName, getSystemTypeName, setGlobalLogLevel };
+export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, IComponentIndex, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IWorldConfig, IWorldManagerConfig, IndexStats, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };