@esengine/ecs-framework 2.4.2 → 2.4.3

package/{index.d.ts → dist/index.d.ts}

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.4.2
+ * @esengine/ecs-framework v2.4.3
  * TypeScript definitions
  */
 /**
@@ -11544,7 +11544,7 @@ declare class SceneManager implements IService {
  * @zh 全局系统是在World级别运行的系统，不依赖特定Scene
  * @en Global systems run at World level and don't depend on specific Scene
  */
-type IGlobalSystem = {
+interface IGlobalSystem {
     /**
      * @zh 系统名称
      * @en System name
@@ -11570,12 +11570,12 @@ type IGlobalSystem = {
      * @en Destroy system
      */
     destroy?(): void;
-};
+}
 /**
  * @zh World配置接口
  * @en World configuration interface
  */
-type IWorldConfig = {
+interface IWorldConfig {
     /**
      * @zh World名称
      * @en World name
@@ -11599,11 +11599,10 @@ type IWorldConfig = {
     /**
      * @zh 自动清理阈值（毫秒），空Scene超过此时间后将被自动清理
      * @en Auto cleanup threshold (ms), empty scenes exceeding this time will be auto-cleaned
-     *
      * @default 300000 (5 minutes)
      */
     cleanupThresholdMs?: number;
-};
+}
 /**
  * @zh World类 - ECS世界管理器
  * @en World class - ECS world manager
@@ -11622,32 +11621,14 @@ type IWorldConfig = {
  * - World.services: World-level services (independent per World)
  * - Scene.services: Scene-level services (independent per Scene)
  *
- * @zh 这种设计允许创建独立的游戏世界，如：
- * - 游戏房间（每个房间一个World）
- * - 不同的游戏模式
- * - 独立的模拟环境
- * @en This design allows creating independent game worlds like:
- * - Game rooms (one World per room)
- * - Different game modes
- * - Independent simulation environments
- *
  * @example
  * ```typescript
- * // @zh 创建游戏房间的World | @en Create World for game room
  * const roomWorld = new World({ name: 'Room_001' });
- *
- * // @zh 注册World级别的服务 | @en Register World-level service
  * roomWorld.services.registerSingleton(RoomManager);
  *
- * // @zh 在World中创建Scene | @en Create Scene in World
- * const gameScene = roomWorld.createScene('game', new Scene());
- * const uiScene = roomWorld.createScene('ui', new Scene());
- *
- * // @zh 在Scene中使用World级别的服务 | @en Use World-level service in Scene
- * const roomManager = roomWorld.services.resolve(RoomManager);
- *
- * // @zh 更新整个World | @en Update entire World
- * roomWorld.update(deltaTime);
+ * const gameScene = roomWorld.createScene('game');
+ * roomWorld.setSceneActive('game', true);
+ * roomWorld.start();
  * ```
  */
 declare class World {
@@ -11657,14 +11638,29 @@ declare class World {
     private readonly _activeScenes;
     private readonly _globalSystems;
     private readonly _services;
+    private readonly _createdAt;
     private _isActive;
-    private _createdAt;
     constructor(config?: IWorldConfig);
     /**
-     * @zh World级别的服务容器，用于管理World范围内的全局服务
-     * @en World-level service container for managing World-scoped global services
+     * @zh World级别的服务容器
+     * @en World-level service container
      */
     get services(): ServiceContainer;
+    /**
+     * @zh 检查World是否激活
+     * @en Check if World is active
+     */
+    get isActive(): boolean;
+    /**
+     * @zh 获取Scene数量
+     * @en Get scene count
+     */
+    get sceneCount(): number;
+    /**
+     * @zh 获取创建时间
+     * @en Get creation time
+     */
+    get createdAt(): number;
     /**
      * @zh 创建并添加Scene到World
      * @en Create and add Scene to World
@@ -11672,6 +11668,7 @@ declare class World {
      * @param sceneName - @zh Scene名称 @en Scene name
      * @param sceneInstance - @zh Scene实例（可选）@en Scene instance (optional)
      * @returns @zh 创建的Scene实例 @en Created Scene instance
+     * @throws @zh 名称为空、重复或超出限制时抛出错误 @en Throws if name is empty, duplicate, or limit exceeded
      */
     createScene<T extends IScene>(sceneName: string, sceneInstance?: T): T;
     /**
@@ -11682,6 +11679,11 @@ declare class World {
      * @returns @zh 是否成功移除 @en Whether removal was successful
      */
     removeScene(sceneName: string): boolean;
+    /**
+     * @zh 移除所有Scene
+     * @en Remove all Scenes
+     */
+    removeAllScenes(): void;
     /**
      * @zh 获取Scene
      * @en Get Scene
@@ -11691,70 +11693,87 @@ declare class World {
      */
     getScene<T extends IScene>(sceneName: string): T | null;
     /**
-     * 获取所有Scene ID
+     * @zh 获取所有Scene ID
+     * @en Get all Scene IDs
      */
     getSceneIds(): string[];
     /**
-     * 获取所有Scene
+     * @zh 获取所有Scene
+     * @en Get all Scenes
      */
     getAllScenes(): IScene[];
     /**
-     * 移除所有Scene
-     */
-    removeAllScenes(): void;
-    /**
-     * 设置Scene激活状态
+     * @zh 设置Scene激活状态
+     * @en Set Scene active state
+     *
+     * @param sceneName - @zh Scene名称 @en Scene name
+     * @param active - @zh 是否激活 @en Whether to activate
      */
     setSceneActive(sceneName: string, active: boolean): void;
     /**
-     * 检查Scene是否激活
+     * @zh 检查Scene是否激活
+     * @en Check if Scene is active
      */
     isSceneActive(sceneName: string): boolean;
     /**
-     * 获取活跃Scene数量
+     * @zh 获取活跃Scene数量
+     * @en Get active Scene count
      */
     getActiveSceneCount(): number;
     /**
-     * 添加全局System
-     * 全局System会在所有激活Scene之前更新
+     * @zh 添加全局System
+     * @en Add global System
+     *
+     * @param system - @zh 全局System实例 @en Global System instance
+     * @returns @zh 添加的System实例 @en Added System instance
      */
     addGlobalSystem<T extends IGlobalSystem>(system: T): T;
     /**
-     * 移除全局System
+     * @zh 移除全局System
+     * @en Remove global System
+     *
+     * @param system - @zh 要移除的System @en System to remove
+     * @returns @zh 是否成功移除 @en Whether removal was successful
      */
     removeGlobalSystem(system: IGlobalSystem): boolean;
     /**
-     * 获取全局System
+     * @zh 获取全局System
+     * @en Get global System
+     *
+     * @param type - @zh System类型 @en System type
+     * @returns @zh System实例或null @en System instance or null
      */
-    getGlobalSystem<T extends IGlobalSystem>(type: new (...args: any[]) => T): T | null;
+    getGlobalSystem<T extends IGlobalSystem>(type: new (...args: unknown[]) => T): T | null;
     /**
-     * 启动World
+     * @zh 启动World
+     * @en Start World
      */
     start(): void;
     /**
-     * 停止World
+     * @zh 停止World
+     * @en Stop World
      */
     stop(): void;
+    /**
+     * @zh 销毁World
+     * @en Destroy World
+     */
+    destroy(): void;
     /**
      * @zh 更新World中的全局System
      * @en Update global systems in World
-     *
-     * @internal Called by Core.update()
+     * @internal
      */
     updateGlobalSystems(): void;
     /**
      * @zh 更新World中的所有激活Scene
      * @en Update all active scenes in World
-     *
-     * @internal Called by Core.update()
+     * @internal
      */
     updateScenes(): void;
     /**
-     * 销毁World
-     */
-    destroy(): void;
-    /**
-     * 获取World状态
+     * @zh 获取World状态
+     * @en Get World status
      */
     getStatus(): {
         name: string;
@@ -11764,42 +11783,21 @@ declare class World {
         globalSystemCount: number;
         createdAt: number;
         config: {
-            /**
-             * @zh World名称
-             * @en World name
-             */
-            name?: string;
-            /**
-             * @zh 是否启用调试模式
-             * @en Enable debug mode
-             */
-            debug?: boolean;
-            /**
-             * @zh 最大Scene数量限制
-             * @en Maximum number of scenes
-             */
-            maxScenes?: number;
-            /**
-             * @zh 是否自动清理空Scene
-             * @en Auto cleanup empty scenes
-             */
-            autoCleanup?: boolean;
-            /**
-             * @zh 自动清理阈值（毫秒），空Scene超过此时间后将被自动清理
-             * @en Auto cleanup threshold (ms), empty scenes exceeding this time will be auto-cleaned
-             *
-             * @default 300000 (5 minutes)
-             */
-            cleanupThresholdMs?: number;
+            name: string;
+            debug: boolean;
+            maxScenes: number;
+            autoCleanup: boolean;
+            cleanupThresholdMs: number;
         };
         scenes: {
             id: string;
-            isActive: boolean;
             name: string;
+            isActive: boolean;
         }[];
     };
     /**
-     * 获取World统计信息
+     * @zh 获取World统计信息
+     * @en Get World statistics
      */
     getStats(): {
         totalEntities: number;
@@ -11810,82 +11808,72 @@ declare class World {
             maxUpdateTime: number;
         };
     };
+    /**
+     * @zh 验证Scene名称
+     * @en Validate Scene name
+     */
+    private validateSceneName;
     /**
      * @zh 检查Scene是否可以被自动清理
      * @en Check if a scene is eligible for auto cleanup
      */
-    private _isSceneCleanupCandidate;
+    private isCleanupCandidate;
     /**
      * @zh 执行自动清理操作
      * @en Execute auto cleanup operation
      */
     private cleanup;
-    /**
-     * 检查World是否激活
-     */
-    get isActive(): boolean;
-    /**
-     * 获取Scene数量
-     */
-    get sceneCount(): number;
-    /**
-     * 获取创建时间
-     */
-    get createdAt(): number;
 }
 
 /**
- * WorldManager配置接口
+ * @zh WorldManager配置接口
+ * @en WorldManager configuration interface
  */
-type IWorldManagerConfig = {
+interface IWorldManagerConfig {
     /**
-     * 最大World数量
+     * @zh 最大World数量
+     * @en Maximum number of worlds
      */
     maxWorlds?: number;
     /**
-     * 是否自动清理空World
+     * @zh 是否自动清理空World
+     * @en Auto cleanup empty worlds
      */
     autoCleanup?: boolean;
     /**
-     * 清理间隔（帧数）
+     * @zh 清理间隔（帧数）
+     * @en Cleanup interval in frames
      */
     cleanupFrameInterval?: number;
     /**
-     * 是否启用调试模式
+     * @zh 是否启用调试模式
+     * @en Enable debug mode
      */
     debug?: boolean;
-};
+}
 /**
- * World管理器 - 管理所有World实例
+ * @zh World管理器 - 管理所有World实例
+ * @en World Manager - Manages all World instances
  *
- * WorldManager负责管理多个独立的World实例。
+ * @zh WorldManager负责管理多个独立的World实例。
  * 每个World都是独立的ECS环境，可以包含多个Scene。
+ * @en WorldManager is responsible for managing multiple independent World instances.
+ * Each World is an isolated ECS environment that can contain multiple Scenes.
  *
- * 适用场景：
+ * @zh 适用场景：
  * - MMO游戏的多房间管理
  * - 服务器端的多游戏实例
  * - 需要完全隔离的多个游戏环境
+ * @en Use cases:
+ * - Multi-room management for MMO games
+ * - Multiple game instances on server-side
+ * - Completely isolated game environments
  *
  * @example
  * ```typescript
- * // 创建WorldManager实例
- * const worldManager = new WorldManager({
- *     maxWorlds: 100,
- *     autoCleanup: true
- * });
- *
- * // 创建游戏房间World
- * const room1 = worldManager.createWorld('room_001', {
- *     name: 'GameRoom_001',
- *     maxScenes: 5
- * });
- * room1.setActive(true);
- *
- * // 游戏循环
- * function gameLoop(deltaTime: number) {
- *     Core.update(deltaTime);
- *     worldManager.updateAll();  // 更新所有活跃World
- * }
+ * const worldManager = new WorldManager({ maxWorlds: 100 });
+ * const room = worldManager.createWorld('room_001');
+ * worldManager.setWorldActive('room_001', true);
  * ```
  */
 declare class WorldManager implements IService {
@@ -11895,70 +11883,124 @@ declare class WorldManager implements IService {
     private _framesSinceCleanup;
     constructor(config?: IWorldManagerConfig);
     /**
-     * 创建新World
+     * @zh 获取World总数
+     * @en Get total world count
+     */
+    get worldCount(): number;
+    /**
+     * @zh 获取激活World数量
+     * @en Get active world count
+     */
+    get activeWorldCount(): number;
+    /**
+     * @zh 检查是否正在运行
+     * @en Check if running
+     */
+    get isRunning(): boolean;
+    /**
+     * @zh 获取配置
+     * @en Get configuration
+     */
+    get config(): IWorldManagerConfig;
+    /**
+     * @zh 创建新World
+     * @en Create new World
+     *
+     * @param worldName - @zh World名称 @en World name
+     * @param config - @zh World配置 @en World configuration
+     * @returns @zh 创建的World实例 @en Created World instance
+     * @throws @zh 名称为空、重复或超出限制时抛出错误 @en Throws if name is empty, duplicate, or limit exceeded
      */
     createWorld(worldName: string, config?: IWorldConfig): World;
     /**
-     * 移除World
+     * @zh 移除World
+     * @en Remove World
+     *
+     * @param worldName - @zh World名称 @en World name
+     * @returns @zh 是否成功移除 @en Whether removal was successful
      */
     removeWorld(worldName: string): boolean;
     /**
-     * 获取World
+     * @zh 获取World
+     * @en Get World
+     *
+     * @param worldName - @zh World名称 @en World name
+     * @returns @zh World实例或null @en World instance or null
      */
     getWorld(worldName: string): World | null;
     /**
-     * 获取所有World ID
+     * @zh 获取所有World ID
+     * @en Get all World IDs
      */
     getWorldIds(): string[];
     /**
-     * 获取所有World
+     * @zh 获取所有World
+     * @en Get all Worlds
      */
     getAllWorlds(): World[];
     /**
-     * 设置World激活状态
+     * @zh 设置World激活状态
+     * @en Set World active state
+     *
+     * @param worldName - @zh World名称 @en World name
+     * @param active - @zh 是否激活 @en Whether to activate
      */
     setWorldActive(worldName: string, active: boolean): void;
     /**
-     * 检查World是否激活
+     * @zh 检查World是否激活
+     * @en Check if World is active
      */
     isWorldActive(worldName: string): boolean;
     /**
-     * 更新所有活跃的World
-     *
-     * 应该在每帧的游戏循环中调用。
-     * 会自动更新所有活跃World的全局系统和场景。
+     * @zh 获取所有激活的World
+     * @en Get all active Worlds
+     */
+    getActiveWorlds(): World[];
+    /**
+     * @zh 查找满足条件的World
+     * @en Find Worlds matching predicate
      *
-     * @example
-     * ```typescript
-     * function gameLoop(deltaTime: number) {
-     *     Core.update(deltaTime);      // 更新全局服务
-     *     worldManager.updateAll();    // 更新所有World
-     * }
-     * ```
+     * @param predicate - @zh 过滤条件 @en Filter predicate
      */
-    updateAll(): void;
+    findWorlds(predicate: (world: World) => boolean): World[];
     /**
-     * 获取所有激活的World
+     * @zh 根据名称查找World
+     * @en Find World by name
+     *
+     * @param name - @zh World名称 @en World name
      */
-    getActiveWorlds(): World[];
+    findWorldByName(name: string): World | null;
     /**
-     * 启动所有World
+     * @zh 启动所有World
+     * @en Start all Worlds
      */
     startAll(): void;
     /**
-     * 停止所有World
+     * @zh 停止所有World
+     * @en Stop all Worlds
      */
     stopAll(): void;
     /**
-     * 查找满足条件的World
+     * @zh 销毁WorldManager
+     * @en Destroy WorldManager
      */
-    findWorlds(predicate: (world: World) => boolean): World[];
+    destroy(): void;
     /**
-     * 根据名称查找World
+     * @zh 实现 IService 接口的 dispose 方法
+     * @en Implement IService dispose method
      */
-    findWorldByName(name: string): World | null;
+    dispose(): void;
+    /**
+     * @zh 更新所有活跃的World
+     * @en Update all active Worlds
+     *
+     * @zh 应该在每帧的游戏循环中调用
+     * @en Should be called in each frame of game loop
+     */
+    updateAll(): void;
     /**
-     * 获取WorldManager统计信息
+     * @zh 获取WorldManager统计信息
+     * @en Get WorldManager statistics
      */
     getStats(): {
         totalWorlds: number;
@@ -11974,35 +12016,24 @@ declare class WorldManager implements IService {
             cleanupFrameInterval: number;
             debug: boolean;
         };
-        worlds: any[];
+        worlds: {
+            id: string;
+            name: string;
+            isActive: boolean;
+            sceneCount: number;
+            totalEntities: number;
+            totalSystems: number;
+        }[];
     };
     /**
-     * 获取详细状态信息
+     * @zh 获取详细状态信息
+     * @en Get detailed status information
      */
     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;
-                    cleanupThresholdMs?: number;
-                };
-                scenes: {
-                    id: string;
-                    isActive: boolean;
-                    name: string;
-                }[];
-            };
+            status: ReturnType<World["getStatus"]>;
         }[];
         totalWorlds: number;
         activeWorlds: number;
@@ -12019,42 +12050,30 @@ declare class WorldManager implements IService {
         };
     };
     /**
-     * 清理空World
+     * @zh 清理空World
+     * @en Cleanup empty Worlds
+     *
+     * @returns @zh 清理的World数量 @en Number of cleaned up Worlds
      */
     cleanup(): number;
     /**
-     * 销毁WorldManager
-     */
-    destroy(): void;
-    /**
-     * 实现 IService 接口的 dispose 方法
-     * 调用 destroy 方法进行清理
-     */
-    dispose(): void;
-    /**
-     * 判断World是否应该被清理
-     * 清理策略：
-     * 1. World未激活
-     * 2. 没有Scene或所有Scene都是空的
-     * 3. 创建时间超过10分钟
-     */
-    private shouldCleanupWorld;
-    /**
-     * 获取World总数
-     */
-    get worldCount(): number;
-    /**
-     * 获取激活World数量
+     * @zh 验证World名称
+     * @en Validate World name
      */
-    get activeWorldCount(): number;
+    private validateWorldName;
     /**
-     * 检查是否正在运行
+     * @zh 处理自动清理
+     * @en Process auto cleanup
      */
-    get isRunning(): boolean;
+    private processAutoCleanup;
     /**
-     * 获取配置
+     * @zh 判断World是否应该被清理
+     * @en Check if World should be cleaned up
+     *
+     * @zh 清理策略：未激活 + (无Scene或全空Scene) + 创建超过10分钟
+     * @en Cleanup policy: inactive + (no scenes or all empty) + created over 10 minutes ago
      */
-    get config(): IWorldManagerConfig;
+    private isCleanupCandidate;
 }
 
 /**