@esengine/ecs-framework 2.2.12 → 2.2.13

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.12
+ * @esengine/ecs-framework v2.2.13
  * TypeScript definitions
  */
 /**
@@ -1286,6 +1286,9 @@ declare class LoggerManager {
     /**
      * 设置日志器工厂方法
      * @param factory 日志器工厂方法
+     *
+     * 注意: 应该在导入 ECS 模块之前调用此方法。
+     * 设置后, 每次调用 getLogger() 都会通过 factory 创建新的 logger 实例, 由用户侧管理
      */
     setLoggerFactory(factory: (name?: string) => ILogger): void;
 }
@@ -5037,7 +5040,7 @@ declare class Scene implements IScene {
      *
      * 从 ServiceContainer 获取，如果未注册则创建默认实例（向后兼容）
      */
-    private get performanceMonitor();
+    get performanceMonitor(): PerformanceMonitor;
     /**
      * 初始化场景
      *
@@ -5066,6 +5069,16 @@ declare class Scene implements IScene {
      * 结束场景，清除实体、实体处理器等
      *
      * 这个方法会结束场景。它将移除所有实体，结束实体处理器等，并调用unload方法。
+     *
+     * 执行顺序：
+     * 1. 调用 unload() - 用户可以在此访问实体和系统进行清理
+     * 2. 清理所有实体
+     * 3. 清空服务容器，触发所有系统的 onDestroy()
+     *
+     * 注意：
+     * - onRemoved 回调不会在 Scene.end() 时触发，因为这是批量销毁场景
+     * - 用户清理：在 Scene.unload() 中处理（可访问实体和系统）
+     * - 系统清理：在 System.onDestroy() 中处理（实体已被清理）
      */
     end(): void;
     /**
@@ -5539,6 +5552,7 @@ declare abstract class EntitySystem implements ISystemBase, IService {
     private _matcher;
     private _eventListeners;
     private _scene;
+    private _destroyed;
     protected logger: ReturnType<typeof createLogger>;
     /**
      * 实体ID映射缓存
@@ -5614,6 +5628,10 @@ declare abstract class EntitySystem implements ISystemBase, IService {
      * 重置系统状态
      *
      * 当系统从场景中移除时调用，重置初始化状态以便重新添加时能正确初始化。
+     *
+     * 注意：此方法由 Scene.removeEntityProcessor 调用，在 unregister（触发dispose）之后调用。
+     * dispose 已经调用了 onDestroy 并设置了 _destroyed 标志，所以这里不需要重置该标志。
+     * 重置 _destroyed 会违反服务容器的语义（dispose 后不应重用）。
      */
     reset(): void;
     /**
@@ -5765,6 +5783,7 @@ declare abstract class EntitySystem implements ISystemBase, IService {
      *
      * 默认行为：
      * - 移除所有事件监听器
+     * - 调用 onDestroy 回调（仅首次）
      * - 清空所有缓存
      * - 重置初始化状态
      *
@@ -7937,6 +7956,13 @@ interface IWorldConfig {
  * World类 - ECS世界管理器
  *
  * World是Scene的容器，每个World可以管理多个Scene。
+ * World拥有独立的服务容器，用于管理World级别的全局服务。
+ *
+ * 服务容器层级：
+ * - Core.services: 应用程序全局服务
+ * - World.services: World级别服务（每个World独立）
+ * - Scene.services: Scene级别服务（每个Scene独立）
+ *
  * 这种设计允许创建独立的游戏世界，如：
  * - 游戏房间（每个房间一个World）
  * - 不同的游戏模式
@@ -7947,10 +7973,16 @@ interface IWorldConfig {
  * // 创建游戏房间的World
  * const roomWorld = new World({ name: 'Room_001' });
  *
+ * // 注册World级别的服务
+ * roomWorld.services.registerSingleton(RoomManager);
+ *
  * // 在World中创建Scene
  * const gameScene = roomWorld.createScene('game', new Scene());
  * const uiScene = roomWorld.createScene('ui', new Scene());
  *
+ * // 在Scene中使用World级别的服务
+ * const roomManager = roomWorld.services.resolve(RoomManager);
+ *
  * // 更新整个World
  * roomWorld.update(deltaTime);
  * ```
@@ -7961,9 +7993,15 @@ declare class World {
     private readonly _scenes;
     private readonly _activeScenes;
     private readonly _globalSystems;
+    private readonly _services;
     private _isActive;
     private _createdAt;
     constructor(config?: IWorldConfig);
+    /**
+     * World级别的服务容器
+     * 用于管理World范围内的全局服务
+     */
+    get services(): ServiceContainer;
     /**
      * 创建并添加Scene到World
      */
@@ -8116,9 +8154,9 @@ interface IWorldManagerConfig {
      */
     autoCleanup?: boolean;
     /**
-     * 清理间隔（毫秒）
+     * 清理间隔（帧数）
      */
-    cleanupInterval?: number;
+    cleanupFrameInterval?: number;
     /**
      * 是否启用调试模式
      */
@@ -8160,9 +8198,8 @@ interface IWorldManagerConfig {
 declare class WorldManager implements IService {
     private readonly _config;
     private readonly _worlds;
-    private readonly _activeWorlds;
-    private _cleanupTimer;
     private _isRunning;
+    private _framesSinceCleanup;
     constructor(config?: IWorldManagerConfig);
     /**
      * 创建新World
@@ -8239,22 +8276,10 @@ declare class WorldManager implements IService {
         memoryUsage: number;
         isRunning: boolean;
         config: {
-            /**
-             * 最大World数量
-             */
-            maxWorlds?: number;
-            /**
-             * 是否自动清理空World
-             */
-            autoCleanup?: boolean;
-            /**
-             * 清理间隔（毫秒）
-             */
-            cleanupInterval?: number;
-            /**
-             * 是否启用调试模式
-             */
-            debug?: boolean;
+            maxWorlds: number;
+            autoCleanup: boolean;
+            cleanupFrameInterval: number;
+            debug: boolean;
         };
         worlds: any[];
     };
@@ -8293,22 +8318,10 @@ declare class WorldManager implements IService {
         memoryUsage: number;
         isRunning: boolean;
         config: {
-            /**
-             * 最大World数量
-             */
-            maxWorlds?: number;
-            /**
-             * 是否自动清理空World
-             */
-            autoCleanup?: boolean;
-            /**
-             * 清理间隔（毫秒）
-             */
-            cleanupInterval?: number;
-            /**
-             * 是否启用调试模式
-             */
-            debug?: boolean;
+            maxWorlds: number;
+            autoCleanup: boolean;
+            cleanupFrameInterval: number;
+            debug: boolean;
         };
     };
     /**
@@ -8324,16 +8337,12 @@ declare class WorldManager implements IService {
      * 调用 destroy 方法进行清理
      */
     dispose(): void;
-    /**
-     * 启动清理定时器
-     */
-    private startCleanupTimer;
-    /**
-     * 停止清理定时器
-     */
-    private stopCleanupTimer;
     /**
      * 判断World是否应该被清理
+     * 清理策略：
+     * 1. World未激活
+     * 2. 没有Scene或所有Scene都是空的
+     * 3. 创建时间超过10分钟
      */
     private shouldCleanupWorld;
     /**