@esengine/ecs-framework 2.2.0 → 2.2.2

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.0
+ * @esengine/ecs-framework v2.2.2
  * TypeScript definitions
  */
 /**
@@ -4466,17 +4466,17 @@ declare class SceneSerializer {
      *
      * @param scene 要序列化的场景
      * @param options 序列化选项
-     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     * @returns 序列化后的数据（JSON字符串或二进制Uint8Array）
      */
-    static serialize(scene: IScene, options?: SceneSerializationOptions): string | Buffer;
+    static serialize(scene: IScene, options?: SceneSerializationOptions): string | Uint8Array;
     /**
      * 反序列化场景
      *
      * @param scene 目标场景
-     * @param saveData 序列化的数据（JSON字符串或二进制Buffer）
+     * @param saveData 序列化的数据（JSON字符串或二进制Uint8Array）
      * @param options 反序列化选项
      */
-    static deserialize(scene: IScene, saveData: string | Buffer, options?: SceneDeserializationOptions): void;
+    static deserialize(scene: IScene, saveData: string | Uint8Array, options?: SceneDeserializationOptions): void;
     /**
      * 序列化场景自定义数据
      *
@@ -4729,7 +4729,7 @@ declare class IncrementalSerializer {
      *
      * @param incremental 增量快照
      * @param options 序列化选项
-     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     * @returns 序列化后的数据（JSON字符串或二进制Uint8Array）
      *
      * @example
      * ```typescript
@@ -4751,11 +4751,11 @@ declare class IncrementalSerializer {
     static serializeIncremental(incremental: IncrementalSnapshot, options?: {
         format?: IncrementalSerializationFormat;
         pretty?: boolean;
-    }): string | Buffer;
+    }): string | Uint8Array;
     /**
      * 反序列化增量快照
      *
-     * @param data 序列化的数据（JSON字符串或二进制Buffer）
+     * @param data 序列化的数据（JSON字符串或二进制Uint8Array）
      * @returns 增量快照
      *
      * @example
@@ -4767,7 +4767,7 @@ declare class IncrementalSerializer {
      * const snapshot = IncrementalSerializer.deserializeIncremental(buffer);
      * ```
      */
-    static deserializeIncremental(data: string | Buffer): IncrementalSnapshot;
+    static deserializeIncremental(data: string | Uint8Array): IncrementalSnapshot;
     /**
      * 计算增量快照的大小（字节）
      *
@@ -5195,10 +5195,10 @@ declare class Scene implements IScene {
     /**
      * 序列化场景
      *
-     * 将场景及其所有实体、组件序列化为JSON字符串或二进制Buffer
+     * 将场景及其所有实体、组件序列化为JSON字符串或二进制Uint8Array
      *
      * @param options 序列化选项
-     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     * @returns 序列化后的数据（JSON字符串或二进制Uint8Array）
      *
      * @example
      * ```typescript
@@ -5214,13 +5214,13 @@ declare class Scene implements IScene {
      * });
      * ```
      */
-    serialize(options?: SceneSerializationOptions): string | Buffer;
+    serialize(options?: SceneSerializationOptions): string | Uint8Array;
     /**
      * 反序列化场景
      *
      * 从序列化数据恢复场景状态
      *
-     * @param saveData 序列化的数据（JSON字符串或二进制Buffer）
+     * @param saveData 序列化的数据（JSON字符串或二进制Uint8Array）
      * @param options 反序列化选项
      *
      * @example
@@ -5236,7 +5236,7 @@ declare class Scene implements IScene {
      * });
      * ```
      */
-    deserialize(saveData: string | Buffer, options?: SceneDeserializationOptions): void;
+    deserialize(saveData: string | Uint8Array, options?: SceneDeserializationOptions): void;
     /** 增量序列化的基础快照 */
     private _incrementalBaseSnapshot?;
     /**
@@ -5288,7 +5288,7 @@ declare class Scene implements IScene {
     /**
      * 应用增量变更到场景
      *
-     * @param incremental 增量快照数据（IncrementalSnapshot对象、JSON字符串或二进制Buffer）
+     * @param incremental 增量快照数据（IncrementalSnapshot对象、JSON字符串或二进制Uint8Array）
      * @param componentRegistry 组件类型注册表（可选，默认使用全局注册表）
      *
      * @example
@@ -5300,12 +5300,12 @@ declare class Scene implements IScene {
      * const jsonData = IncrementalSerializer.serializeIncremental(snapshot, { format: 'json' });
      * scene.applyIncremental(jsonData);
      *
-     * // 从二进制Buffer应用
+     * // 从二进制Uint8Array应用
      * const binaryData = IncrementalSerializer.serializeIncremental(snapshot, { format: 'binary' });
      * scene.applyIncremental(binaryData);
      * ```
      */
-    applyIncremental(incremental: IncrementalSnapshot | string | Buffer, componentRegistry?: Map<string, any>): void;
+    applyIncremental(incremental: IncrementalSnapshot | string | Uint8Array, componentRegistry?: Map<string, any>): void;
     /**
      * 更新增量快照基准
      *
@@ -7417,168 +7417,6 @@ 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 {
-    /**
-     * 当前活跃场景
-     */
-    private _currentScene;
-    /**
-     * 待切换的下一个场景（延迟切换用）
-     */
-    private _nextScene;
-    /**
-     * ECS流式API
-     */
-    private _ecsAPI;
-    /**
-     * 日志器
-     */
-    private _logger;
-    /**
-     * 设置当前场景（立即切换）
-     *
-     * 会自动处理旧场景的结束和新场景的初始化。
-     *
-     * @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
@@ -7677,6 +7515,10 @@ declare class World {
      * 获取所有Scene
      */
     getAllScenes(): IScene[];
+    /**
+     * 移除所有Scene
+     */
+    removeAllScenes(): void;
     /**
      * 设置Scene激活状态
      */
@@ -7812,6 +7654,12 @@ interface IWorldManagerConfig {
      * 是否启用调试模式
      */
     debug?: boolean;
+    /**
+     * 是否创建默认World(默认true)
+     *
+     * 当通过Core使用时应该为true,直接使用WorldManager时可设为false
+     */
+    createDefaultWorld?: boolean;
 }
 /**
  * World管理器 - 管理所有World实例
@@ -7841,24 +7689,38 @@ interface IWorldManagerConfig {
  *
  * // 游戏循环
  * function gameLoop(deltaTime: number) {
- *     Core.update(deltaTime);
- *     worldManager.updateAll();  // 更新所有活跃World
+ *     Core.update(deltaTime);  // 自动更新所有@Updatable服务(包括WorldManager)
  * }
  * ```
  */
-declare class WorldManager {
+declare class WorldManager implements IService, IUpdatable {
+    /**
+     * 默认World的ID
+     */
+    static readonly DEFAULT_WORLD_ID = "__default__";
     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;
     /**
@@ -7884,18 +7746,12 @@ declare class WorldManager {
     /**
      * 更新所有活跃的World
      *
-     * 应该在每帧的游戏循环中调用。
+     * 此方法由ServiceContainer自动调用(@Updatable装饰器)
      * 会自动更新所有活跃World的全局系统和场景。
      *
-     * @example
-     * ```typescript
-     * function gameLoop(deltaTime: number) {
-     *     Core.update(deltaTime);      // 更新全局服务
-     *     worldManager.updateAll();    // 更新所有World
-     * }
-     * ```
+     * @param deltaTime 帧时间间隔(未使用,保留用于接口兼容)
      */
-    updateAll(): void;
+    update(deltaTime?: number): void;
     /**
      * 获取所有激活的World
      */
@@ -7944,6 +7800,12 @@ declare class WorldManager {
              * 是否启用调试模式
              */
             debug?: boolean;
+            /**
+             * 是否创建默认World(默认true)
+             *
+             * 当通过Core使用时应该为true,直接使用WorldManager时可设为false
+             */
+            createDefaultWorld?: boolean;
         };
         worlds: any[];
     };
@@ -7998,6 +7860,12 @@ declare class WorldManager {
              * 是否启用调试模式
              */
             debug?: boolean;
+            /**
+             * 是否创建默认World(默认true)
+             *
+             * 当通过Core使用时应该为true,直接使用WorldManager时可设为false
+             */
+            createDefaultWorld?: boolean;
         };
     };
     /**
@@ -8008,6 +7876,11 @@ declare class WorldManager {
      * 销毁WorldManager
      */
     destroy(): void;
+    /**
+     * 实现 IService 接口的 dispose 方法
+     * 调用 destroy 方法进行清理
+     */
+    dispose(): void;
     /**
      * 启动清理定时器
      */
@@ -8038,6 +7911,188 @@ declare class WorldManager {
     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;
+}
+
 /**
  * 组件对象池，用于复用组件实例以减少内存分配
  */
@@ -9334,6 +9389,12 @@ declare class Core {
      * 管理当前场景的生命周期。
      */
     private _sceneManager;
+    /**
+     * World管理器
+     *
+     * 管理多个独立的World实例（可选）。
+     */
+    private _worldManager;
     /**
      * 插件管理器
      *
@@ -9374,6 +9435,24 @@ declare class Core {
      * ```
      */
     static get services(): ServiceContainer;
+    /**
+     * 获取World管理器
+     *
+     * 用于管理多个独立的World实例（高级用户）。
+     *
+     * @returns WorldManager实例
+     * @throws 如果Core实例未创建
+     *
+     * @example
+     * ```typescript
+     * // 创建多个游戏房间
+     * const wm = Core.worldManager;
+     * const room1 = wm.createWorld('room_001');
+     * room1.createScene('game', new GameScene());
+     * room1.start();
+     * ```
+     */
+    static get worldManager(): WorldManager;
     /**
      * 创建Core实例
      *