@esengine/ecs-framework 2.1.44 → 2.1.45

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.44
+ * @esengine/ecs-framework v2.1.45
  * TypeScript definitions
  */
 /**
@@ -4571,6 +4571,453 @@ declare class ECSFluentAPI {
  */
 declare function createECSAPI(scene: IScene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem): ECSFluentAPI;
 
+/**
+ * 全局系统接口
+ * 全局系统是在World级别运行的系统，不依赖特定Scene
+ */
+interface IGlobalSystem {
+    /**
+     * 系统名称
+     */
+    readonly name: string;
+    /**
+     * 初始化系统
+     */
+    initialize?(): void;
+    /**
+     * 更新系统
+     */
+    update(deltaTime?: number): void;
+    /**
+     * 重置系统
+     */
+    reset?(): void;
+    /**
+     * 销毁系统
+     */
+    destroy?(): void;
+}
+/**
+ * World配置接口
+ */
+interface IWorldConfig {
+    /**
+     * World名称
+     */
+    name?: string;
+    /**
+     * 是否启用调试模式
+     */
+    debug?: boolean;
+    /**
+     * 最大Scene数量限制
+     */
+    maxScenes?: number;
+    /**
+     * 是否自动清理空Scene
+     */
+    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);
+    /**
+     * 创建并添加Scene到World
+     */
+    createScene<T extends IScene>(sceneId: string, sceneInstance?: T): T;
+    /**
+     * 移除Scene
+     */
+    removeScene(sceneId: string): boolean;
+    /**
+     * 获取Scene
+     */
+    getScene<T extends IScene>(sceneId: string): T | null;
+    /**
+     * 获取所有Scene ID
+     */
+    getSceneIds(): string[];
+    /**
+     * 获取所有Scene
+     */
+    getAllScenes(): IScene[];
+    /**
+     * 设置Scene激活状态
+     */
+    setSceneActive(sceneId: string, active: boolean): void;
+    /**
+     * 检查Scene是否激活
+     */
+    isSceneActive(sceneId: string): boolean;
+    /**
+     * 获取活跃Scene数量
+     */
+    getActiveSceneCount(): number;
+    /**
+     * 添加全局System
+     * 全局System会在所有激活Scene之前更新
+     */
+    addGlobalSystem<T extends IGlobalSystem>(system: T): T;
+    /**
+     * 移除全局System
+     */
+    removeGlobalSystem(system: IGlobalSystem): boolean;
+    /**
+     * 获取全局System
+     */
+    getGlobalSystem<T extends IGlobalSystem>(type: new (...args: any[]) => T): T | null;
+    /**
+     * 启动World
+     */
+    start(): void;
+    /**
+     * 停止World
+     */
+    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;
+}
+
 /**
  * 实体数据收集器
  */
@@ -4934,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;
     /**
      * 全局核心实例
      */
@@ -4954,12 +5413,6 @@ declare class Core {
      * 在调试模式下会启用额外的性能监控和错误检查。
      */
     readonly debug: boolean;
-    /**
-     * 待切换的场景
-     *
-     * 存储下一帧要切换到的场景实例。
-     */
-    _nextScene: IScene | null;
     /**
      * 全局管理器集合
      *
@@ -4990,16 +5443,18 @@ declare class Core {
      * 提供便捷的ECS操作接口。
      */
     _ecsAPI?: ECSFluentAPI;
-    /**
-     * 当前活动场景
-     */
-    _scene?: IScene;
     /**
      * 调试管理器
      *
      * 负责收集和发送调试数据。
      */
     _debugManager?: DebugManager;
+    /**
+     * World管理器
+     *
+     * 管理多个World实例，支持多房间/多世界架构。
+     */
+    _worldManager?: WorldManager;
     /**
      * Core配置
      */
@@ -5021,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实例
      *
@@ -5182,11 +5603,23 @@ declare class Core {
      */
     static get supportsBigInt(): boolean;
     /**
-     * 内部场景设置方法
+     * 获取WorldManager实例
      *
-     * @param scene - 要设置的场景实例
+     * @returns WorldManager实例，如果未初始化则自动创建
+     */
+    static getWorldManager(): WorldManager;
+    /**
+     * 启用World管理
+     *
+     * 显式启用World功能，用于多房间/多世界架构
+     */
+    static enableWorldManager(): WorldManager;
+    /**
+     * 确保默认World存在
+     *
+     * 内部方法，用于懒初始化默认World
      */
-    private setSceneInternal;
+    private ensureDefaultWorld;
     /**
      * 场景切换回调
      *
@@ -6879,5 +7312,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler, BigIntFactory, Bits, COMPONENT_TYPE_NAME, Component, ComponentDataCollector, ComponentIndex, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSparseSet, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeMap, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI, createLogger, getComponentInstanceTypeName, getComponentTypeName, getSystemInstanceTypeName, getSystemTypeName, setGlobalLogLevel };
-export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, IComponentIndex, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IndexStats, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+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 };