@esengine/ecs-framework 2.2.2 → 2.2.3

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.2
+ * @esengine/ecs-framework v2.2.3
  * TypeScript definitions
  */
 /**
@@ -7417,6 +7417,184 @@ declare class ECSFluentAPI {
  */
 declare function createECSAPI(scene: IScene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem): ECSFluentAPI;
 
+/**
+ * 单场景管理器
+ *
+ * 适用场景：
+ * - 单人游戏
+ * - 简单场景切换
+ * - 不需要多World隔离的项目
+ *
+ * 特点：
+ * - 轻量级，零额外开销
+ * - 简单直观的API
+ * - 支持延迟场景切换
+ * - 自动管理ECS API
+ *
+ * @example
+ * ```typescript
+ * // 初始化Core
+ * Core.create({ debug: true });
+ *
+ * // 创建场景管理器
+ * const sceneManager = new SceneManager();
+ *
+ * // 设置场景
+ * class GameScene extends Scene {
+ *     initialize() {
+ *         const player = this.createEntity('Player');
+ *         player.addComponent(new Transform(100, 100));
+ *     }
+ * }
+ *
+ * sceneManager.setScene(new GameScene());
+ *
+ * // 游戏循环
+ * function gameLoop(deltaTime: number) {
+ *     Core.update(deltaTime);      // 更新全局服务
+ *     sceneManager.update();       // 更新场景
+ * }
+ *
+ * // 延迟切换场景（下一帧生效）
+ * sceneManager.loadScene(new MenuScene());
+ * ```
+ */
+declare class SceneManager implements IService {
+    /**
+     * 内部默认World
+     */
+    private _defaultWorld;
+    /**
+     * 待切换的下一个场景（延迟切换用）
+     */
+    private _nextScene;
+    /**
+     * ECS流式API
+     */
+    private _ecsAPI;
+    /**
+     * 日志器
+     */
+    private _logger;
+    /**
+     * 场景切换回调函数
+     */
+    private _onSceneChangedCallback?;
+    /**
+     * 默认场景ID
+     */
+    private static readonly DEFAULT_SCENE_ID;
+    constructor();
+    /**
+     * 设置场景切换回调
+     *
+     * @param callback 场景切换时的回调函数
+     * @internal
+     */
+    setSceneChangedCallback(callback: () => void): void;
+    /**
+     * 设置当前场景（立即切换）
+     *
+     * 会自动处理旧场景的结束和新场景的初始化。
+     *
+     * @param scene - 要设置的场景实例
+     * @returns 返回设置的场景实例，便于链式调用
+     *
+     * @example
+     * ```typescript
+     * const gameScene = sceneManager.setScene(new GameScene());
+     * console.log(gameScene.name); // 可以立即使用返回的场景
+     * ```
+     */
+    setScene<T extends IScene>(scene: T): T;
+    /**
+     * 延迟加载场景（下一帧切换）
+     *
+     * 场景不会立即切换，而是在下一次调用 update() 时切换。
+     * 这对于避免在当前帧的中途切换场景很有用。
+     *
+     * @param scene - 要加载的场景实例
+     *
+     * @example
+     * ```typescript
+     * // 在某个System中触发场景切换
+     * class GameOverSystem extends EntitySystem {
+     *     process(entities: readonly Entity[]) {
+     *         if (playerHealth <= 0) {
+     *             sceneManager.loadScene(new GameOverScene());
+     *             // 当前帧继续执行，场景将在下一帧切换
+     *         }
+     *     }
+     * }
+     * ```
+     */
+    loadScene<T extends IScene>(scene: T): void;
+    /**
+     * 获取当前活跃的场景
+     *
+     * @returns 当前场景实例，如果没有场景则返回null
+     */
+    get currentScene(): IScene | null;
+    /**
+     * 获取ECS流式API
+     *
+     * 提供便捷的实体查询、事件发射等功能。
+     *
+     * @returns ECS API实例，如果当前没有场景则返回null
+     *
+     * @example
+     * ```typescript
+     * const api = sceneManager.api;
+     * if (api) {
+     *     // 查询所有敌人
+     *     const enemies = api.find(Enemy, Transform);
+     *
+     *     // 发射事件
+     *     api.emit('game:start', { level: 1 });
+     * }
+     * ```
+     */
+    get api(): ECSFluentAPI | null;
+    /**
+     * 更新场景
+     *
+     * 应该在每帧的游戏循环中调用。
+     * 会自动处理延迟场景切换。
+     *
+     * @example
+     * ```typescript
+     * function gameLoop(deltaTime: number) {
+     *     Core.update(deltaTime);
+     *     sceneManager.update();  // 每帧调用
+     * }
+     * ```
+     */
+    update(): void;
+    /**
+     * 销毁场景管理器
+     *
+     * 会自动结束当前场景并清理所有资源。
+     * 通常在应用程序关闭时调用。
+     */
+    destroy(): void;
+    /**
+     * 检查是否有活跃场景
+     *
+     * @returns 如果有活跃场景返回true，否则返回false
+     */
+    get hasScene(): boolean;
+    /**
+     * 检查是否有待切换的场景
+     *
+     * @returns 如果有待切换场景返回true，否则返回false
+     */
+    get hasPendingScene(): boolean;
+    /**
+     * 释放资源（IService接口）
+     */
+    dispose(): void;
+}
+
 /**
  * 全局系统接口
  * 全局系统是在World级别运行的系统，不依赖特定Scene
@@ -7654,12 +7832,6 @@ interface IWorldManagerConfig {
      * 是否启用调试模式
      */
     debug?: boolean;
-    /**
-     * 是否创建默认World(默认true)
-     *
-     * 当通过Core使用时应该为true,直接使用WorldManager时可设为false
-     */
-    createDefaultWorld?: boolean;
 }
 /**
  * World管理器 - 管理所有World实例
@@ -7689,38 +7861,24 @@ interface IWorldManagerConfig {
  *
  * // 游戏循环
  * function gameLoop(deltaTime: number) {
- *     Core.update(deltaTime);  // 自动更新所有@Updatable服务(包括WorldManager)
+ *     Core.update(deltaTime);
+ *     worldManager.updateAll();  // 更新所有活跃World
  * }
  * ```
  */
-declare class WorldManager implements IService, IUpdatable {
-    /**
-     * 默认World的ID
-     */
-    static readonly DEFAULT_WORLD_ID = "__default__";
+declare class WorldManager implements IService {
     private readonly _config;
     private readonly _worlds;
     private readonly _activeWorlds;
     private _cleanupTimer;
     private _isRunning;
     constructor(config?: IWorldManagerConfig);
-    /**
-     * 获取默认World
-     *
-     * 默认World由WorldManager自动创建，供SceneManager使用。
-     * 此方法主要供SceneManager内部使用。
-     *
-     * @returns 默认World实例
-     */
-    getDefaultWorld(): World;
     /**
      * 创建新World
      */
     createWorld(worldId: string, config?: IWorldConfig): World;
     /**
      * 移除World
-     *
-     * 注意:默认World不能被删除
      */
     removeWorld(worldId: string): boolean;
     /**
@@ -7746,12 +7904,18 @@ declare class WorldManager implements IService, IUpdatable {
     /**
      * 更新所有活跃的World
      *
-     * 此方法由ServiceContainer自动调用(@Updatable装饰器)
+     * 应该在每帧的游戏循环中调用。
      * 会自动更新所有活跃World的全局系统和场景。
      *
-     * @param deltaTime 帧时间间隔(未使用,保留用于接口兼容)
+     * @example
+     * ```typescript
+     * function gameLoop(deltaTime: number) {
+     *     Core.update(deltaTime);      // 更新全局服务
+     *     worldManager.updateAll();    // 更新所有World
+     * }
+     * ```
      */
-    update(deltaTime?: number): void;
+    updateAll(): void;
     /**
      * 获取所有激活的World
      */
@@ -7800,12 +7964,6 @@ declare class WorldManager implements IService, IUpdatable {
              * 是否启用调试模式
              */
             debug?: boolean;
-            /**
-             * 是否创建默认World(默认true)
-             *
-             * 当通过Core使用时应该为true,直接使用WorldManager时可设为false
-             */
-            createDefaultWorld?: boolean;
         };
         worlds: any[];
     };
@@ -7860,12 +8018,6 @@ declare class WorldManager implements IService, IUpdatable {
              * 是否启用调试模式
              */
             debug?: boolean;
-            /**
-             * 是否创建默认World(默认true)
-             *
-             * 当通过Core使用时应该为true,直接使用WorldManager时可设为false
-             */
-            createDefaultWorld?: boolean;
         };
     };
     /**
@@ -7911,188 +8063,6 @@ declare class WorldManager implements IService, IUpdatable {
     get config(): IWorldManagerConfig;
 }
 
-/**
- * 单场景管理器
- *
- * 适用场景：
- * - 单人游戏
- * - 简单场景切换
- * - 不需要多World隔离的项目
- *
- * 特点：
- * - 轻量级，零额外开销
- * - 简单直观的API
- * - 支持延迟场景切换
- * - 自动管理ECS API
- * - 通过依赖注入获取WorldManager的默认World
- *
- * @example
- * ```typescript
- * // 初始化Core
- * Core.create({ debug: true });
- *
- * // 设置场景
- * class GameScene extends Scene {
- *     initialize() {
- *         const player = this.createEntity('Player');
- *         player.addComponent(new Transform(100, 100));
- *     }
- * }
- *
- * Core.setScene(new GameScene());
- *
- * // 游戏循环
- * function gameLoop(deltaTime: number) {
- *     Core.update(deltaTime);  // 自动更新所有服务(包括SceneManager)
- * }
- *
- * // 延迟切换场景（下一帧生效）
- * Core.loadScene(new MenuScene());
- * ```
- */
-declare class SceneManager implements IService, IUpdatable {
-    /**
-     * 内部默认World(从WorldManager获取)
-     */
-    private _defaultWorld;
-    /**
-     * 待切换的下一个场景（延迟切换用）
-     */
-    private _nextScene;
-    /**
-     * ECS流式API
-     */
-    private _ecsAPI;
-    /**
-     * 日志器
-     */
-    private _logger;
-    /**
-     * 场景切换回调函数
-     */
-    private _onSceneChangedCallback?;
-    /**
-     * 默认场景ID
-     */
-    private static readonly DEFAULT_SCENE_ID;
-    /**
-     * 构造函数
-     *
-     * WorldManager通过依赖注入自动传入
-     *
-     * @param worldManager WorldManager实例,用于获取默认World
-     */
-    constructor(worldManager: WorldManager);
-    /**
-     * 设置场景切换回调
-     *
-     * @param callback 场景切换时的回调函数
-     * @internal
-     */
-    setSceneChangedCallback(callback: () => void): void;
-    /**
-     * 设置当前场景（立即切换）
-     *
-     * 会自动处理旧场景的结束和新场景的初始化。
-     *
-     * @param scene - 要设置的场景实例
-     * @returns 返回设置的场景实例，便于链式调用
-     *
-     * @example
-     * ```typescript
-     * const gameScene = sceneManager.setScene(new GameScene());
-     * console.log(gameScene.name); // 可以立即使用返回的场景
-     * ```
-     */
-    setScene<T extends IScene>(scene: T): T;
-    /**
-     * 延迟加载场景（下一帧切换）
-     *
-     * 场景不会立即切换，而是在下一次调用 update() 时切换。
-     * 这对于避免在当前帧的中途切换场景很有用。
-     *
-     * @param scene - 要加载的场景实例
-     *
-     * @example
-     * ```typescript
-     * // 在某个System中触发场景切换
-     * class GameOverSystem extends EntitySystem {
-     *     process(entities: readonly Entity[]) {
-     *         if (playerHealth <= 0) {
-     *             sceneManager.loadScene(new GameOverScene());
-     *             // 当前帧继续执行，场景将在下一帧切换
-     *         }
-     *     }
-     * }
-     * ```
-     */
-    loadScene<T extends IScene>(scene: T): void;
-    /**
-     * 获取当前活跃的场景
-     *
-     * @returns 当前场景实例，如果没有场景则返回null
-     */
-    get currentScene(): IScene | null;
-    /**
-     * 获取ECS流式API
-     *
-     * 提供便捷的实体查询、事件发射等功能。
-     *
-     * @returns ECS API实例，如果当前没有场景则返回null
-     *
-     * @example
-     * ```typescript
-     * const api = sceneManager.api;
-     * if (api) {
-     *     // 查询所有敌人
-     *     const enemies = api.find(Enemy, Transform);
-     *
-     *     // 发射事件
-     *     api.emit('game:start', { level: 1 });
-     * }
-     * ```
-     */
-    get api(): ECSFluentAPI | null;
-    /**
-     * 更新场景
-     *
-     * 应该在每帧的游戏循环中调用。
-     * 会自动处理延迟场景切换。
-     *
-     * @example
-     * ```typescript
-     * function gameLoop(deltaTime: number) {
-     *     Core.update(deltaTime);
-     *     sceneManager.update();  // 每帧调用
-     * }
-     * ```
-     */
-    update(): void;
-    /**
-     * 销毁场景管理器
-     *
-     * 会自动结束当前场景并清理所有资源。
-     * 通常在应用程序关闭时调用。
-     */
-    destroy(): void;
-    /**
-     * 检查是否有活跃场景
-     *
-     * @returns 如果有活跃场景返回true，否则返回false
-     */
-    get hasScene(): boolean;
-    /**
-     * 检查是否有待切换的场景
-     *
-     * @returns 如果有待切换场景返回true，否则返回false
-     */
-    get hasPendingScene(): boolean;
-    /**
-     * 释放资源（IService接口）
-     */
-    dispose(): void;
-}
-
 /**
  * 组件对象池，用于复用组件实例以减少内存分配
  */