@esengine/ecs-framework 2.2.11 → 2.2.13

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.11
+ * @esengine/ecs-framework v2.2.13
  * TypeScript definitions
  */
 /**
@@ -355,8 +355,8 @@ interface IEventListenerConfig {
     priority?: number;
     /** 是否异步执行 */
     async?: boolean;
-    /** 执行上下文 */
-    context?: unknown;
+    /** 事件处理函数的 this 绑定对象 */
+    thisArg?: object;
 }
 /**
  * 事件统计信息接口
@@ -734,7 +734,7 @@ declare abstract class Component implements IComponent {
      *
      * 用于为每个组件分配唯一的ID。
      */
-    static _idGenerator: number;
+    private static idGenerator;
     /**
      * 组件唯一标识符
      *
@@ -1286,6 +1286,9 @@ declare class LoggerManager {
     /**
      * 设置日志器工厂方法
      * @param factory 日志器工厂方法
+     *
+     * 注意: 应该在导入 ECS 模块之前调用此方法。
+     * 设置后, 每次调用 getLogger() 都会通过 factory 创建新的 logger 实例, 由用户侧管理
      */
     setLoggerFactory(factory: (name?: string) => ILogger): void;
 }
@@ -1588,222 +1591,18 @@ declare class ComponentStorageManager {
     /**
      * 获取所有存储器的统计信息
      */
-    getAllStats(): Map<string, any>;
+    getAllStats(): Map<string, {
+        totalSlots: number;
+        usedSlots: number;
+        freeSlots: number;
+        fragmentation: number;
+    }>;
     /**
      * 清空所有存储器
      */
     clear(): void;
 }
 
-/**
- * 增强的事件总线实现
- * 基于TypeSafeEventSystem，提供类型安全的事件发布订阅机制
- */
-declare class EventBus implements IEventBus {
-    private static readonly _logger;
-    private eventSystem;
-    private eventIdCounter;
-    private isDebugMode;
-    constructor(debugMode?: boolean);
-    /**
-     * 发射事件
-     * @param eventType 事件类型
-     * @param data 事件数据
-     * @param enhance 是否增强事件数据（添加timestamp、eventId等），默认false提升性能
-     */
-    emit<T>(eventType: string, data: T, enhance?: boolean): void;
-    /**
-     * 异步发射事件
-     * @param eventType 事件类型
-     * @param data 事件数据
-     * @param enhance 是否增强事件数据（添加timestamp、eventId等），默认false提升性能
-     */
-    emitAsync<T>(eventType: string, data: T, enhance?: boolean): Promise<void>;
-    /**
-     * 监听事件
-     * @param eventType 事件类型
-     * @param handler 事件处理器
-     * @param config 监听器配置
-     * @returns 监听器ID
-     */
-    on<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
-    /**
-     * 监听事件（一次性）
-     * @param eventType 事件类型
-     * @param handler 事件处理器
-     * @param config 监听器配置
-     * @returns 监听器ID
-     */
-    once<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
-    /**
-     * 异步监听事件
-     * @param eventType 事件类型
-     * @param handler 异步事件处理器
-     * @param config 监听器配置
-     * @returns 监听器ID
-     */
-    onAsync<T>(eventType: string, handler: (data: T) => Promise<void>, config?: IEventListenerConfig): string;
-    /**
-     * 移除事件监听器
-     * @param eventType 事件类型
-     * @param listenerId 监听器ID
-     */
-    off(eventType: string, listenerId: string): boolean;
-    /**
-     * 移除指定事件类型的所有监听器
-     * @param eventType 事件类型
-     */
-    offAll(eventType: string): void;
-    /**
-     * 检查是否有指定事件的监听器
-     * @param eventType 事件类型
-     */
-    hasListeners(eventType: string): boolean;
-    /**
-     * 获取事件统计信息
-     * @param eventType 事件类型（可选）
-     */
-    getStats(eventType?: string): IEventStats | Map<string, IEventStats>;
-    /**
-     * 清空所有监听器
-     */
-    clear(): void;
-    /**
-     * 启用或禁用事件系统
-     * @param enabled 是否启用
-     */
-    setEnabled(enabled: boolean): void;
-    /**
-     * 设置调试模式
-     * @param debug 是否启用调试
-     */
-    setDebugMode(debug: boolean): void;
-    /**
-     * 设置最大监听器数量
-     * @param max 最大数量
-     */
-    setMaxListeners(max: number): void;
-    /**
-     * 获取监听器数量
-     * @param eventType 事件类型
-     */
-    getListenerCount(eventType: string): number;
-    /**
-     * 设置事件批处理配置
-     * @param eventType 事件类型
-     * @param batchSize 批处理大小
-     * @param delay 延迟时间（毫秒）
-     */
-    setBatchConfig(eventType: string, batchSize: number, delay: number): void;
-    /**
-     * 刷新指定事件的批处理队列
-     * @param eventType 事件类型
-     */
-    flushBatch(eventType: string): void;
-    /**
-     * 重置事件统计
-     * @param eventType 事件类型（可选）
-     */
-    resetStats(eventType?: string): void;
-    /**
-     * 发射实体创建事件
-     * @param entityData 实体事件数据
-     */
-    emitEntityCreated(entityData: IEntityEventData): void;
-    /**
-     * 发射实体销毁事件
-     * @param entityData 实体事件数据
-     */
-    emitEntityDestroyed(entityData: IEntityEventData): void;
-    /**
-     * 发射组件添加事件
-     * @param componentData 组件事件数据
-     */
-    emitComponentAdded(componentData: IComponentEventData): void;
-    /**
-     * 发射组件移除事件
-     * @param componentData 组件事件数据
-     */
-    emitComponentRemoved(componentData: IComponentEventData): void;
-    /**
-     * 发射系统添加事件
-     * @param systemData 系统事件数据
-     */
-    emitSystemAdded(systemData: ISystemEventData): void;
-    /**
-     * 发射系统移除事件
-     * @param systemData 系统事件数据
-     */
-    emitSystemRemoved(systemData: ISystemEventData): void;
-    /**
-     * 发射场景变化事件
-     * @param sceneData 场景事件数据
-     */
-    emitSceneChanged(sceneData: ISceneEventData): void;
-    /**
-     * 发射性能警告事件
-     * @param performanceData 性能事件数据
-     */
-    emitPerformanceWarning(performanceData: IPerformanceEventData): void;
-    /**
-     * 监听实体创建事件
-     * @param handler 事件处理器
-     * @param config 监听器配置
-     */
-    onEntityCreated(handler: (data: IEntityEventData) => void, config?: IEventListenerConfig): string;
-    /**
-     * 监听组件添加事件
-     * @param handler 事件处理器
-     * @param config 监听器配置
-     */
-    onComponentAdded(handler: (data: IComponentEventData) => void, config?: IEventListenerConfig): string;
-    /**
-     * 监听系统错误事件
-     * @param handler 事件处理器
-     * @param config 监听器配置
-     */
-    onSystemError(handler: (data: ISystemEventData) => void, config?: IEventListenerConfig): string;
-    /**
-     * 监听性能警告事件
-     * @param handler 事件处理器
-     * @param config 监听器配置
-     */
-    onPerformanceWarning(handler: (data: IPerformanceEventData) => void, config?: IEventListenerConfig): string;
-    /**
-     * 验证事件类型（仅在debug模式下执行，提升性能）
-     * @param eventType 事件类型
-     */
-    private validateEventType;
-    /**
-     * 增强事件数据
-     * @param eventType 事件类型
-     * @param data 原始数据
-     */
-    private enhanceEventData;
-    /**
-     * 转换EventStats为IEventStats
-     * @param stats EventStats实例
-     */
-    private convertEventStats;
-}
-/**
- * 全局事件总线实例
- * 提供全局访问的事件总线
- */
-declare class GlobalEventBus {
-    private static instance;
-    /**
-     * 获取全局事件总线实例
-     * @param debugMode 是否启用调试模式
-     */
-    static getInstance(debugMode?: boolean): EventBus;
-    /**
-     * 重置全局事件总线实例
-     * @param debugMode 是否启用调试模式
-     */
-    static reset(debugMode?: boolean): EventBus;
-}
-
 /**
  * 高性能实体列表管理器
  * 管理场景中的所有实体，支持快速查找和批量操作
@@ -2129,6 +1928,7 @@ interface IService {
  * 服务类型
  *
  * 支持任意构造函数签名，以便与依赖注入装饰器配合使用
+ * 使用 any[] 以允许任意参数类型的构造函数
  */
 type ServiceType<T extends IService> = new (...args: any[]) => T;
 /**
@@ -2236,7 +2036,7 @@ declare class ServiceContainer {
      * container.registerInstance(Config, config);
      * ```
      */
-    registerInstance<T extends IService>(type: new (...args: any[]) => T, instance: T): void;
+    registerInstance<T extends IService>(type: ServiceType<T>, instance: T): void;
     /**
      * 解析服务
      *
@@ -2425,23 +2225,8 @@ interface PerformanceThresholds {
 declare class PerformanceMonitor implements IService {
     private _systemData;
     private _systemStats;
-    private _warnings;
     private _isEnabled;
     private _maxRecentSamples;
-    private _maxWarnings;
-    private _thresholds;
-    private _fpsHistory;
-    private _lastFrameTime;
-    private _frameCount;
-    private _fpsUpdateInterval;
-    private _lastFpsUpdate;
-    private _currentFps;
-    private _memoryCheckInterval;
-    private _lastMemoryCheck;
-    private _memoryHistory;
-    private _gcCount;
-    private _lastGcCheck;
-    private _gcCheckInterval;
     constructor();
     /**
      * 启用性能监控
@@ -2460,7 +2245,7 @@ declare class PerformanceMonitor implements IService {
      * @param systemName 系统名称
      * @returns 开始时间戳
      */
-    startMonitoring(systemName: string): number;
+    startMonitoring(_systemName: string): number;
     /**
      * 结束监控并记录性能数据
      * @param systemName 系统名称
@@ -2723,7 +2508,7 @@ declare class EntityProcessorList {
      */
     private sortProcessors;
     /** 获取处理器列表 */
-    get processors(): EntitySystem<[]>[];
+    get processors(): EntitySystem[];
     /** 获取处理器数量 */
     get count(): number;
 }
@@ -3448,21 +3233,17 @@ declare class ReactiveQuery {
  * ```
  */
 declare class QuerySystem {
-    private _logger;
-    private entities;
-    private entityIndex;
+    private readonly _logger;
+    private _entities;
+    private _entityIndex;
     private _version;
-    private queryCache;
-    private cacheMaxSize;
-    private cacheTimeout;
-    private componentMaskCache;
-    private archetypeSystem;
-    private queryStats;
-    private resultArrayPool;
-    private poolMaxSize;
+    private _queryCache;
+    private _cacheMaxSize;
+    private _cacheTimeout;
+    private _componentMaskCache;
+    private _archetypeSystem;
+    private _queryStats;
     constructor();
-    private acquireResultArray;
-    private releaseResultArray;
     /**
      * 设置实体列表并重建索引
      *
@@ -3550,16 +3331,6 @@ declare class QuerySystem {
      * ```
      */
     queryAll(...componentTypes: ComponentType[]): QueryResult;
-    /**
-     * 多组件查询算法
-     *
-     * 针对多组件查询场景的高效算法实现。
-     * 通过选择最小的组件集合作为起点，减少需要检查的实体数量。
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 匹配的实体列表
-     */
-    private queryMultipleComponents;
     /**
      * 查询包含任意指定组件的实体
      *
@@ -3901,11 +3672,11 @@ declare class QueryBuilder {
 /**
  * 事件处理器函数类型
  */
-type EventHandler<T = any> = (event: T) => void;
+type EventHandler<T> = (event: T) => void;
 /**
  * 异步事件处理器函数类型
  */
-type AsyncEventHandler<T = any> = (event: T) => Promise<void>;
+type AsyncEventHandler<T> = (event: T) => Promise<void>;
 /**
  * 事件监听器配置
  */
@@ -3916,8 +3687,8 @@ interface EventListenerConfig {
     priority?: number;
     /** 是否异步执行 */
     async?: boolean;
-    /** 执行上下文 */
-    context?: any;
+    /** 事件处理函数的 this 绑定对象 */
+    thisArg?: object;
 }
 /**
  * 事件统计信息
@@ -3964,11 +3735,11 @@ declare class TypeSafeEventSystem {
     /**
      * 添加事件监听器
      * @param eventType 事件类型
-     * @param handler 事件处理器
+     * @param handler 事件处理器（同步或异步，根据 config.async 决定）
      * @param config 监听器配置
      * @returns 监听器ID（用于移除）
      */
-    on<T>(eventType: string, handler: EventHandler<T>, config?: EventListenerConfig): string;
+    on<T>(eventType: string, handler: EventHandler<T> | AsyncEventHandler<T>, config?: EventListenerConfig): string;
     /**
      * 添加一次性事件监听器
      * @param eventType 事件类型
@@ -4158,10 +3929,6 @@ declare class ReferenceTracker {
      * Entity ID -> 引用该Entity的所有组件记录
      */
     private _references;
-    /**
-     * 当前Scene的引用
-     */
-    private _scene;
     /**
      * 注册Entity引用
      *
@@ -4207,12 +3974,6 @@ declare class ReferenceTracker {
      * 遍历所有记录，移除已被GC回收的Component引用。
      */
     cleanup(): void;
-    /**
-     * 设置Scene引用
-     *
-     * @param scene Scene实例
-     */
-    setScene(scene: IScene): void;
     /**
      * 注册Entity到Scene的映射
      *
@@ -4454,6 +4215,21 @@ declare function queryForAll<T extends readonly ComponentConstructor[]>(...types
  * 负责组件的序列化和反序列化操作
  */
 
+/**
+ * 可序列化的值类型
+ */
+type SerializableValue = string | number | boolean | null | undefined | SerializableValue[] | {
+    [key: string]: SerializableValue;
+} | {
+    __type: 'Date';
+    value: string;
+} | {
+    __type: 'Map';
+    value: Array<[SerializableValue, SerializableValue]>;
+} | {
+    __type: 'Set';
+    value: SerializableValue[];
+};
 /**
  * 序列化后的组件数据
  */
@@ -4469,7 +4245,7 @@ interface SerializedComponent {
     /**
      * 组件数据
      */
-    data: Record<string, any>;
+    data: Record<string, SerializableValue>;
 }
 /**
  * 组件序列化器类
@@ -5175,14 +4951,50 @@ declare class Scene implements IScene {
      * 场景是否已开始运行
      */
     private _didSceneBegin;
+    /**
+     * 系统列表缓存
+     */
+    private _cachedSystems;
+    /**
+     * 系统顺序脏标记
+     *
+     * 当系统增删或 updateOrder 改变时标记为 true，下次访问 systems 时重新构建缓存
+     */
+    private _systemsOrderDirty;
+    /**
+     * 系统错误计数器
+     *
+     * 跟踪每个系统的错误次数，用于自动禁用频繁出错的系统
+     */
+    private _systemErrorCount;
+    /**
+     * 最大允许错误次数
+     *
+     * 系统错误次数超过此阈值后将被自动禁用
+     */
+    private _maxErrorCount;
     /**
      * 获取场景中所有已注册的EntitySystem
      *
-     * 按updateOrder排序。
+     * 按updateOrder排序。使用缓存机制，仅在系统变化时重新排序。
      *
      * @returns 系统列表
      */
     get systems(): EntitySystem[];
+    /**
+     * 重新构建系统缓存
+     *
+     * 从服务容器中提取所有EntitySystem并排序
+     */
+    private _rebuildSystemsCache;
+    /**
+     * 从服务列表中过滤出EntitySystem实例
+     */
+    private _filterEntitySystems;
+    /**
+     * 按updateOrder排序系统
+     */
+    private _sortSystemsByUpdateOrder;
     /**
      * 通过类型获取System实例
      *
@@ -5198,6 +5010,12 @@ declare class Scene implements IScene {
      * ```
      */
     getSystem<T extends EntitySystem>(systemType: ServiceType<T>): T | null;
+    /**
+     * 标记系统顺序为脏
+     *
+     * 当系统列表或顺序发生变化时调用，使缓存失效
+     */
+    markSystemsOrderDirty(): void;
     /**
      * 获取场景的服务容器
      *
@@ -5222,7 +5040,7 @@ declare class Scene implements IScene {
      *
      * 从 ServiceContainer 获取，如果未注册则创建默认实例（向后兼容）
      */
-    private get performanceMonitor();
+    get performanceMonitor(): PerformanceMonitor;
     /**
      * 初始化场景
      *
@@ -5251,12 +5069,32 @@ declare class Scene implements IScene {
      * 结束场景，清除实体、实体处理器等
      *
      * 这个方法会结束场景。它将移除所有实体，结束实体处理器等，并调用unload方法。
+     *
+     * 执行顺序：
+     * 1. 调用 unload() - 用户可以在此访问实体和系统进行清理
+     * 2. 清理所有实体
+     * 3. 清空服务容器，触发所有系统的 onDestroy()
+     *
+     * 注意：
+     * - onRemoved 回调不会在 Scene.end() 时触发，因为这是批量销毁场景
+     * - 用户清理：在 Scene.unload() 中处理（可访问实体和系统）
+     * - 系统清理：在 System.onDestroy() 中处理（实体已被清理）
      */
     end(): void;
     /**
      * 更新场景
      */
     update(): void;
+    /**
+     * 处理系统执行错误
+     *
+     * 记录错误信息并跟踪错误次数。当系统错误次数超过阈值时自动禁用该系统。
+     *
+     * @param system 出错的系统
+     * @param phase 错误发生的阶段（update 或 lateUpdate）
+     * @param error 错误对象
+     */
+    private _handleSystemError;
     /**
      * 将实体添加到此场景，并返回它
      * @param name 实体名称
@@ -5305,12 +5143,16 @@ declare class Scene implements IScene {
     findEntitiesByTag(tag: number): Entity[];
     /**
      * 根据名称查找实体（别名方法）
+     *
      * @param name 实体名称
+     * @deprecated 请使用 findEntity() 代替此方法
      */
     getEntityByName(name: string): Entity | null;
     /**
      * 根据标签查找实体（别名方法）
+     *
      * @param tag 实体标签
+     * @deprecated 请使用 findEntitiesByTag() 代替此方法
      */
     getEntitiesByTag(tag: number): Entity[];
     /**
@@ -5328,7 +5170,7 @@ declare class Scene implements IScene {
      * }
      * ```
      */
-    queryAll(...componentTypes: any[]): {
+    queryAll(...componentTypes: ComponentType[]): {
         entities: readonly Entity[];
     };
     /**
@@ -5337,7 +5179,7 @@ declare class Scene implements IScene {
      * @param componentTypes - 组件类型数组
      * @returns 查询结果
      */
-    queryAny(...componentTypes: any[]): {
+    queryAny(...componentTypes: ComponentType[]): {
         entities: readonly Entity[];
     };
     /**
@@ -5346,7 +5188,7 @@ declare class Scene implements IScene {
      * @param componentTypes - 组件类型数组
      * @returns 查询结果
      */
-    queryNone(...componentTypes: any[]): {
+    queryNone(...componentTypes: ComponentType[]): {
         entities: readonly Entity[];
     };
     /**
@@ -5438,7 +5280,7 @@ declare class Scene implements IScene {
      * 添加系统到场景（addEntityProcessor的别名）
      * @param system 系统
      */
-    addSystem(system: EntitySystem): EntitySystem<[]>;
+    addSystem(system: EntitySystem): EntitySystem;
     /**
      * 从场景中删除EntitySystem处理器
      * @param processor 要删除的处理器
@@ -5474,7 +5316,12 @@ declare class Scene implements IScene {
     getStats(): {
         entityCount: number;
         processorCount: number;
-        componentStorageStats: Map<string, any>;
+        componentStorageStats: Map<string, {
+            totalSlots: number;
+            usedSlots: number;
+            freeSlots: number;
+            fragmentation: number;
+        }>;
     };
     /**
      * 获取场景的调试信息
@@ -5495,7 +5342,12 @@ declare class Scene implements IScene {
             updateOrder: number;
             entityCount: number;
         }>;
-        componentStats: Map<string, any>;
+        componentStats: Map<string, {
+            totalSlots: number;
+            usedSlots: number;
+            freeSlots: number;
+            fragmentation: number;
+        }>;
     };
     /**
      * 序列化场景
@@ -5610,7 +5462,7 @@ declare class Scene implements IScene {
      * scene.applyIncremental(binaryData);
      * ```
      */
-    applyIncremental(incremental: IncrementalSnapshot | string | Uint8Array, componentRegistry?: Map<string, any>): void;
+    applyIncremental(incremental: IncrementalSnapshot | string | Uint8Array, componentRegistry?: Map<string, ComponentType>): void;
     /**
      * 更新增量快照基准
      *
@@ -5691,7 +5543,7 @@ declare class Scene implements IScene {
  * }
  * ```
  */
-declare abstract class EntitySystem<TComponents extends readonly ComponentConstructor[] = []> implements ISystemBase, IService {
+declare abstract class EntitySystem implements ISystemBase, IService {
     private _updateOrder;
     private _enabled;
     private _performanceMonitor;
@@ -5700,13 +5552,13 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
     private _matcher;
     private _eventListeners;
     private _scene;
+    private _destroyed;
     protected logger: ReturnType<typeof createLogger>;
     /**
      * 实体ID映射缓存
      */
     private _entityIdMap;
     private _entityIdMapVersion;
-    private _entityIdMapSize;
     /**
      * 统一的实体缓存管理器
      */
@@ -5776,6 +5628,10 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      * 重置系统状态
      *
      * 当系统从场景中移除时调用，重置初始化状态以便重新添加时能正确初始化。
+     *
+     * 注意：此方法由 Scene.removeEntityProcessor 调用，在 unregister（触发dispose）之后调用。
+     * dispose 已经调用了 onDestroy 并设置了 _destroyed 标志，所以这里不需要重置该标志。
+     * 重置 _destroyed 会违反服务容器的语义（dispose 后不应重用）。
      */
     reset(): void;
     /**
@@ -5784,6 +5640,14 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
     private queryEntities;
     /**
      * 检查是否为单一条件查询
+     *
+     * 使用位运算优化多条件检测。将每种查询条件映射到不同的位：
+     * - all: 第0位 (1)
+     * - any: 第1位 (2)
+     * - none: 第2位 (4)
+     * - tag: 第3位 (8)
+     * - name: 第4位 (16)
+     * - component: 第5位 (32)
      */
     private isSingleCondition;
     /**
@@ -5845,7 +5709,7 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      *
      * @param entities 要处理的实体列表
      */
-    protected process(entities: readonly Entity[]): void;
+    protected process(_entities: readonly Entity[]): void;
     /**
      * 后期处理实体列表
      *
@@ -5902,7 +5766,7 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      *
      * @param entity 被添加的实体
      */
-    protected onAdded(entity: Entity): void;
+    protected onAdded(_entity: Entity): void;
     /**
      * 当实体从系统中移除时调用
      *
@@ -5910,7 +5774,7 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      *
      * @param entity 被移除的实体
      */
-    protected onRemoved(entity: Entity): void;
+    protected onRemoved(_entity: Entity): void;
     /**
      * 释放系统资源
      *
@@ -5919,6 +5783,7 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      *
      * 默认行为：
      * - 移除所有事件监听器
+     * - 调用 onDestroy 回调（仅首次）
      * - 清空所有缓存
      * - 重置初始化状态
      *
@@ -5934,15 +5799,16 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      * @param eventType 事件类型
      * @param handler 事件处理函数
      * @param config 监听器配置
+     * @returns 监听器引用ID，可用于手动移除监听器
      */
-    protected addEventListener<T = any>(eventType: string, handler: EventHandler<T>, config?: EventListenerConfig): void;
+    protected addEventListener<T>(eventType: string, handler: EventHandler<T>, config?: EventListenerConfig): string | null;
     /**
      * 移除特定的事件监听器
      *
      * @param eventType 事件类型
-     * @param handler 事件处理函数
+     * @param listenerRef 监听器引用ID（由 addEventListener 返回）
      */
-    protected removeEventListener<T = any>(eventType: string, handler: EventHandler<T>): void;
+    protected removeEventListener(eventType: string, listenerRef: string): void;
     /**
      * 清理手动添加的事件监听器
      */
@@ -6433,17 +6299,6 @@ declare class Entity {
      * 实体比较器实例
      */
     static entityComparer: EntityComparer;
-    /**
-     * 全局事件总线实例
-     * 用于发射组件相关事件
-     */
-    static eventBus: EventBus | null;
-    /**
-     * 通知Scene中的QuerySystem实体组件发生变动
-     *
-     * @param entity 发生组件变动的实体
-     */
-    private static notifyQuerySystems;
     /**
      * 实体名称
      */
@@ -6459,7 +6314,7 @@ declare class Entity {
     /**
      * 销毁状态标志
      */
-    _isDestroyed: boolean;
+    private _isDestroyed;
     /**
      * 父实体引用
      */
@@ -6504,6 +6359,15 @@ declare class Entity {
      * @returns 如果实体已被销毁则返回true
      */
     get isDestroyed(): boolean;
+    /**
+     * 设置销毁状态（内部使用）
+     *
+     * 此方法供Scene和批量操作使用，以提高性能。
+     * 不应在普通业务逻辑中调用，应使用destroy()方法。
+     *
+     * @internal
+     */
+    setDestroyedState(destroyed: boolean): void;
     /**
      * 获取组件数组（懒加载）
      * @returns 只读的组件数组
@@ -6607,7 +6471,7 @@ declare class Entity {
      * const health = entity.createComponent(Health, 100);
      * ```
      */
-    createComponent<T extends Component>(componentType: ComponentType<T>, ...args: any[]): T;
+    createComponent<T extends Component>(componentType: ComponentType<T>, ...args: ConstructorParameters<ComponentType<T>>): T;
     /**
      * 内部添加组件方法（不进行重复检查，用于初始化）
      *
@@ -6615,6 +6479,10 @@ declare class Entity {
      * @returns 添加的组件实例
      */
     private addComponentInternal;
+    /**
+     * 通知Scene中的QuerySystem实体组件发生变动
+     */
+    private notifyQuerySystems;
     /**
      * 添加组件到实体
      *
@@ -6676,7 +6544,7 @@ declare class Entity {
      * position.x = 100;
      * ```
      */
-    getOrCreateComponent<T extends Component>(type: ComponentType<T>, ...args: any[]): T;
+    getOrCreateComponent<T extends Component>(type: ComponentType<T>, ...args: ConstructorParameters<ComponentType<T>>): T;
     /**
      * 移除指定的组件
      *
@@ -6993,7 +6861,7 @@ declare abstract class ProcessingSystem extends EntitySystem {
      * 处理实体，每帧调用processSystem方法进行处理
      * @param entities 实体数组，未被使用
      */
-    protected process(entities: Entity[]): void;
+    protected process(_entities: Entity[]): void;
     /**
      * 处理实体的具体方法，由子类实现
      */
@@ -7011,7 +6879,7 @@ declare abstract class PassiveSystem extends EntitySystem {
      * 不进行任何处理
      * @param entities 实体数组，未被使用
      */
-    protected process(entities: Entity[]): void;
+    protected process(_entities: Entity[]): void;
 }
 
 /**
@@ -8088,6 +7956,13 @@ interface IWorldConfig {
  * World类 - ECS世界管理器
  *
  * World是Scene的容器，每个World可以管理多个Scene。
+ * World拥有独立的服务容器，用于管理World级别的全局服务。
+ *
+ * 服务容器层级：
+ * - Core.services: 应用程序全局服务
+ * - World.services: World级别服务（每个World独立）
+ * - Scene.services: Scene级别服务（每个Scene独立）
+ *
  * 这种设计允许创建独立的游戏世界，如：
  * - 游戏房间（每个房间一个World）
  * - 不同的游戏模式
@@ -8098,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);
  * ```
@@ -8112,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
      */
@@ -8267,9 +8154,9 @@ interface IWorldManagerConfig {
      */
     autoCleanup?: boolean;
     /**
-     * 清理间隔（毫秒）
+     * 清理间隔（帧数）
      */
-    cleanupInterval?: number;
+    cleanupFrameInterval?: number;
     /**
      * 是否启用调试模式
      */
@@ -8311,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
@@ -8390,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[];
     };
@@ -8444,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;
         };
     };
     /**
@@ -8475,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;
     /**
@@ -8505,6 +8363,215 @@ declare class WorldManager implements IService {
     get config(): IWorldManagerConfig;
 }
 
+/**
+ * 增强的事件总线实现
+ * 基于TypeSafeEventSystem，提供类型安全的事件发布订阅机制
+ */
+declare class EventBus implements IEventBus {
+    private static readonly _logger;
+    private eventSystem;
+    private eventIdCounter;
+    private isDebugMode;
+    constructor(debugMode?: boolean);
+    /**
+     * 发射事件
+     * @param eventType 事件类型
+     * @param data 事件数据
+     * @param enhance 是否增强事件数据（添加timestamp、eventId等），默认false提升性能
+     */
+    emit<T>(eventType: string, data: T, enhance?: boolean): void;
+    /**
+     * 异步发射事件
+     * @param eventType 事件类型
+     * @param data 事件数据
+     * @param enhance 是否增强事件数据（添加timestamp、eventId等），默认false提升性能
+     */
+    emitAsync<T>(eventType: string, data: T, enhance?: boolean): Promise<void>;
+    /**
+     * 监听事件
+     * @param eventType 事件类型
+     * @param handler 事件处理器
+     * @param config 监听器配置
+     * @returns 监听器ID
+     */
+    on<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
+    /**
+     * 监听事件（一次性）
+     * @param eventType 事件类型
+     * @param handler 事件处理器
+     * @param config 监听器配置
+     * @returns 监听器ID
+     */
+    once<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
+    /**
+     * 异步监听事件
+     * @param eventType 事件类型
+     * @param handler 异步事件处理器
+     * @param config 监听器配置
+     * @returns 监听器ID
+     */
+    onAsync<T>(eventType: string, handler: (data: T) => Promise<void>, config?: IEventListenerConfig): string;
+    /**
+     * 移除事件监听器
+     * @param eventType 事件类型
+     * @param listenerId 监听器ID
+     */
+    off(eventType: string, listenerId: string): boolean;
+    /**
+     * 移除指定事件类型的所有监听器
+     * @param eventType 事件类型
+     */
+    offAll(eventType: string): void;
+    /**
+     * 检查是否有指定事件的监听器
+     * @param eventType 事件类型
+     */
+    hasListeners(eventType: string): boolean;
+    /**
+     * 获取事件统计信息
+     * @param eventType 事件类型（可选）
+     */
+    getStats(eventType?: string): IEventStats | Map<string, IEventStats>;
+    /**
+     * 清空所有监听器
+     */
+    clear(): void;
+    /**
+     * 启用或禁用事件系统
+     * @param enabled 是否启用
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * 设置调试模式
+     * @param debug 是否启用调试
+     */
+    setDebugMode(debug: boolean): void;
+    /**
+     * 设置最大监听器数量
+     * @param max 最大数量
+     */
+    setMaxListeners(max: number): void;
+    /**
+     * 获取监听器数量
+     * @param eventType 事件类型
+     */
+    getListenerCount(eventType: string): number;
+    /**
+     * 设置事件批处理配置
+     * @param eventType 事件类型
+     * @param batchSize 批处理大小
+     * @param delay 延迟时间（毫秒）
+     */
+    setBatchConfig(eventType: string, batchSize: number, delay: number): void;
+    /**
+     * 刷新指定事件的批处理队列
+     * @param eventType 事件类型
+     */
+    flushBatch(eventType: string): void;
+    /**
+     * 重置事件统计
+     * @param eventType 事件类型（可选）
+     */
+    resetStats(eventType?: string): void;
+    /**
+     * 发射实体创建事件
+     * @param entityData 实体事件数据
+     */
+    emitEntityCreated(entityData: IEntityEventData): void;
+    /**
+     * 发射实体销毁事件
+     * @param entityData 实体事件数据
+     */
+    emitEntityDestroyed(entityData: IEntityEventData): void;
+    /**
+     * 发射组件添加事件
+     * @param componentData 组件事件数据
+     */
+    emitComponentAdded(componentData: IComponentEventData): void;
+    /**
+     * 发射组件移除事件
+     * @param componentData 组件事件数据
+     */
+    emitComponentRemoved(componentData: IComponentEventData): void;
+    /**
+     * 发射系统添加事件
+     * @param systemData 系统事件数据
+     */
+    emitSystemAdded(systemData: ISystemEventData): void;
+    /**
+     * 发射系统移除事件
+     * @param systemData 系统事件数据
+     */
+    emitSystemRemoved(systemData: ISystemEventData): void;
+    /**
+     * 发射场景变化事件
+     * @param sceneData 场景事件数据
+     */
+    emitSceneChanged(sceneData: ISceneEventData): void;
+    /**
+     * 发射性能警告事件
+     * @param performanceData 性能事件数据
+     */
+    emitPerformanceWarning(performanceData: IPerformanceEventData): void;
+    /**
+     * 监听实体创建事件
+     * @param handler 事件处理器
+     * @param config 监听器配置
+     */
+    onEntityCreated(handler: (data: IEntityEventData) => void, config?: IEventListenerConfig): string;
+    /**
+     * 监听组件添加事件
+     * @param handler 事件处理器
+     * @param config 监听器配置
+     */
+    onComponentAdded(handler: (data: IComponentEventData) => void, config?: IEventListenerConfig): string;
+    /**
+     * 监听系统错误事件
+     * @param handler 事件处理器
+     * @param config 监听器配置
+     */
+    onSystemError(handler: (data: ISystemEventData) => void, config?: IEventListenerConfig): string;
+    /**
+     * 监听性能警告事件
+     * @param handler 事件处理器
+     * @param config 监听器配置
+     */
+    onPerformanceWarning(handler: (data: IPerformanceEventData) => void, config?: IEventListenerConfig): string;
+    /**
+     * 验证事件类型（仅在debug模式下执行，提升性能）
+     * @param eventType 事件类型
+     */
+    private validateEventType;
+    /**
+     * 增强事件数据
+     * @param eventType 事件类型
+     * @param data 原始数据
+     */
+    private enhanceEventData;
+    /**
+     * 转换EventStats为IEventStats
+     * @param stats EventStats实例
+     */
+    private convertEventStats;
+}
+/**
+ * 全局事件总线实例
+ * 提供全局访问的事件总线
+ */
+declare class GlobalEventBus {
+    private static instance;
+    /**
+     * 获取全局事件总线实例
+     * @param debugMode 是否启用调试模式
+     */
+    static getInstance(debugMode?: boolean): EventBus;
+    /**
+     * 重置全局事件总线实例
+     * @param debugMode 是否启用调试模式
+     */
+    static reset(debugMode?: boolean): EventBus;
+}
+
 /**
  * 组件对象池，用于复用组件实例以减少内存分配
  */
@@ -8514,9 +8581,8 @@ declare class ComponentPool<T extends Component> {
     private resetFn?;
     private maxSize;
     private minSize;
-    private growthFactor;
     private stats;
-    constructor(createFn: () => T, resetFn?: (component: T) => void, maxSize?: number, minSize?: number, growthFactor?: number);
+    constructor(createFn: () => T, resetFn?: (component: T) => void, maxSize?: number, minSize?: number);
     /**
      * 获取一个组件实例
      */
@@ -8559,6 +8625,14 @@ declare class ComponentPool<T extends Component> {
         utilizationRate: number;
     };
 }
+/**
+ * 组件使用追踪
+ */
+interface ComponentUsageTracker {
+    createCount: number;
+    releaseCount: number;
+    lastAccessTime: number;
+}
 /**
  * 全局组件池管理器
  */
@@ -8609,7 +8683,11 @@ declare class ComponentPoolManager {
     /**
      * 获取全局统计信息
      */
-    getGlobalStats(): any[];
+    getGlobalStats(): Array<{
+        componentName: string;
+        poolStats: ReturnType<ComponentPool<Component>['getStats']>;
+        usage: ComponentUsageTracker | undefined;
+    }>;
     /**
      * 获取池统计信息
      */
@@ -8818,7 +8896,7 @@ declare class VersionMigrationManager {
      * );
      * ```
      */
-    static registerComponentMigration(componentType: string, fromVersion: number, toVersion: number, migration: ComponentMigrationFunction): void;
+    static registerComponentMigration(componentType: string, fromVersion: number, _toVersion: number, migration: ComponentMigrationFunction): void;
     /**
      * 注册场景迁移函数
      *
@@ -8839,7 +8917,7 @@ declare class VersionMigrationManager {
      * );
      * ```
      */
-    static registerSceneMigration(fromVersion: number, toVersion: number, migration: SceneMigrationFunction): void;
+    static registerSceneMigration(fromVersion: number, _toVersion: number, migration: SceneMigrationFunction): void;
     /**
      * 迁移组件数据
      *
@@ -9264,9 +9342,7 @@ declare class EntityDataCollector {
     private collectArchetypeDataWithMemory;
     private extractArchetypeStatistics;
     private extractArchetypeStatisticsWithMemory;
-    private getArchetypeDistribution;
     private getArchetypeDistributionWithMemory;
-    private getTopEntitiesByComponents;
     private getTopEntitiesByComponentsWithMemory;
     private getEmptyEntityDebugData;
     private calculateFallbackEntityStats;
@@ -9351,7 +9427,6 @@ declare class SystemDataCollector {
 declare class PerformanceDataCollector {
     private frameTimeHistory;
     private maxHistoryLength;
-    private lastGCCount;
     private gcCollections;
     private lastMemoryCheck;
     /**
@@ -9430,7 +9505,6 @@ declare class WebSocketManager {
     private isConnected;
     private reconnectAttempts;
     private maxReconnectAttempts;
-    private reconnectInterval;
     private url;
     private autoReconnect;
     private reconnectTimer?;
@@ -9463,10 +9537,6 @@ declare class WebSocketManager {
      * 设置最大重连次数
      */
     setMaxReconnectAttempts(attempts: number): void;
-    /**
-     * 设置重连间隔
-     */
-    setReconnectInterval(interval: number): void;
     /**
      * 计划重连
      */
@@ -9544,7 +9614,7 @@ declare class DebugManager implements IService, IUpdatable {
      * 更新配置
      */
     updateConfig(config: IECSDebugConfig): void;
-    update(deltaTime?: number): void;
+    update(_deltaTime?: number): void;
     /**
      * 场景变更回调
      */
@@ -10321,7 +10391,7 @@ declare class DebugPlugin implements IPlugin, IService {
     /**
      * 安装插件
      */
-    install(core: Core, services: ServiceContainer): Promise<void>;
+    install(_core: Core, services: ServiceContainer): Promise<void>;
     /**
      * 卸载插件
      */
@@ -10385,6 +10455,10 @@ declare class DebugPlugin implements IPlugin, IService {
  * 提供 @Injectable、@Inject 和 @Updatable 装饰器，用于标记可注入的类和依赖注入点
  */
 
+/**
+ * 依赖注入元数据存储
+ */
+type Constructor = abstract new (...args: unknown[]) => unknown;
 /**
  * 可注入元数据接口
  */
@@ -10396,12 +10470,12 @@ interface InjectableMetadata {
     /**
      * 依赖列表
      */
-    dependencies: Array<ServiceType<any> | string | symbol>;
+    dependencies: Array<ServiceType<IService> | string | symbol>;
     /**
      * 属性注入映射
      * key: 属性名, value: 服务类型
      */
-    properties?: Map<string | symbol, ServiceType<any>>;
+    properties?: Map<string | symbol, ServiceType<IService>>;
 }
 /**
  * 可更新元数据接口
@@ -10477,7 +10551,7 @@ declare function Updatable(priority?: number): ClassDecorator;
  *
  * @param serviceType 服务类型标识符
  */
-declare function Inject(serviceType: ServiceType<any> | string | symbol): ParameterDecorator;
+declare function Inject(serviceType: ServiceType<IService> | string | symbol): ParameterDecorator;
 /**
  * 创建实例并自动注入依赖
  *
@@ -10497,14 +10571,14 @@ declare function createInstance<T>(constructor: new (...args: any[]) => T, conta
  * @param target 目标类
  * @returns 是否可更新
  */
-declare function isUpdatable(target: any): boolean;
+declare function isUpdatable(target: Constructor): boolean;
 /**
  * 获取类的可更新元数据
  *
  * @param target 目标类
  * @returns 可更新元数据
  */
-declare function getUpdatableMetadata(target: any): UpdatableMetadata | undefined;
+declare function getUpdatableMetadata(target: Constructor): UpdatableMetadata | undefined;
 /**
  * 注册可注入的服务到容器
  *
@@ -10885,15 +10959,23 @@ declare class Time {
 
 /**
  * 二进制序列化器
- * 使用zlib压缩JSON数据
+ * 将对象转换为UTF8字节数组
  */
 declare class BinarySerializer {
     /**
-     * 将对象编码为压缩的二进制数据
+     * 将字符串编码为UTF8字节数组
+     */
+    private static stringToUtf8;
+    /**
+     * 将UTF8字节数组解码为字符串
+     */
+    private static utf8ToString;
+    /**
+     * 将对象编码为二进制数据
      */
     static encode(value: any): Uint8Array;
     /**
-     * 将压缩的二进制数据解码为对象
+     * 将二进制数据解码为对象
      */
     static decode(bytes: Uint8Array): any;
 }