@esengine/ecs-framework 2.2.10 → 2.2.12

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.10
+ * @esengine/ecs-framework v2.2.12
  * 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;
     /**
      * 组件唯一标识符
      *
@@ -1588,222 +1588,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 +1925,7 @@ interface IService {
  * 服务类型
  *
  * 支持任意构造函数签名，以便与依赖注入装饰器配合使用
+ * 使用 any[] 以允许任意参数类型的构造函数
  */
 type ServiceType<T extends IService> = new (...args: any[]) => T;
 /**
@@ -2236,7 +2033,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 +2222,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 +2242,7 @@ declare class PerformanceMonitor implements IService {
      * @param systemName 系统名称
      * @returns 开始时间戳
      */
-    startMonitoring(systemName: string): number;
+    startMonitoring(_systemName: string): number;
     /**
      * 结束监控并记录性能数据
      * @param systemName 系统名称
@@ -2723,7 +2505,7 @@ declare class EntityProcessorList {
      */
     private sortProcessors;
     /** 获取处理器列表 */
-    get processors(): EntitySystem<[]>[];
+    get processors(): EntitySystem[];
     /** 获取处理器数量 */
     get count(): number;
 }
@@ -3448,21 +3230,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 +3328,6 @@ declare class QuerySystem {
      * ```
      */
     queryAll(...componentTypes: ComponentType[]): QueryResult;
-    /**
-     * 多组件查询算法
-     *
-     * 针对多组件查询场景的高效算法实现。
-     * 通过选择最小的组件集合作为起点，减少需要检查的实体数量。
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 匹配的实体列表
-     */
-    private queryMultipleComponents;
     /**
      * 查询包含任意指定组件的实体
      *
@@ -3901,11 +3669,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 +3684,8 @@ interface EventListenerConfig {
     priority?: number;
     /** 是否异步执行 */
     async?: boolean;
-    /** 执行上下文 */
-    context?: any;
+    /** 事件处理函数的 this 绑定对象 */
+    thisArg?: object;
 }
 /**
  * 事件统计信息
@@ -3964,11 +3732,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 +3926,6 @@ declare class ReferenceTracker {
      * Entity ID -> 引用该Entity的所有组件记录
      */
     private _references;
-    /**
-     * 当前Scene的引用
-     */
-    private _scene;
     /**
      * 注册Entity引用
      *
@@ -4207,12 +3971,6 @@ declare class ReferenceTracker {
      * 遍历所有记录，移除已被GC回收的Component引用。
      */
     cleanup(): void;
-    /**
-     * 设置Scene引用
-     *
-     * @param scene Scene实例
-     */
-    setScene(scene: IScene): void;
     /**
      * 注册Entity到Scene的映射
      *
@@ -4454,6 +4212,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 +4242,7 @@ interface SerializedComponent {
     /**
      * 组件数据
      */
-    data: Record<string, any>;
+    data: Record<string, SerializableValue>;
 }
 /**
  * 组件序列化器类
@@ -4975,8 +4748,8 @@ interface IncrementalSerializationOptions {
     compressSnapshot?: boolean;
     /**
      * 序列化格式
-     * - 'json': JSON格式（可读性好，方便调试）
-     * - 'binary': MessagePack二进制格式（体积小，性能高）
+     * - 'json': JSON格式
+     * - 'binary': 二进制格式
      * 默认 'json'
      */
     format?: IncrementalSerializationFormat;
@@ -5175,14 +4948,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 +5007,12 @@ declare class Scene implements IScene {
      * ```
      */
     getSystem<T extends EntitySystem>(systemType: ServiceType<T>): T | null;
+    /**
+     * 标记系统顺序为脏
+     *
+     * 当系统列表或顺序发生变化时调用，使缓存失效
+     */
+    markSystemsOrderDirty(): void;
     /**
      * 获取场景的服务容器
      *
@@ -5257,6 +5072,16 @@ declare class Scene implements IScene {
      * 更新场景
      */
     update(): void;
+    /**
+     * 处理系统执行错误
+     *
+     * 记录错误信息并跟踪错误次数。当系统错误次数超过阈值时自动禁用该系统。
+     *
+     * @param system 出错的系统
+     * @param phase 错误发生的阶段（update 或 lateUpdate）
+     * @param error 错误对象
+     */
+    private _handleSystemError;
     /**
      * 将实体添加到此场景，并返回它
      * @param name 实体名称
@@ -5305,12 +5130,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 +5157,7 @@ declare class Scene implements IScene {
      * }
      * ```
      */
-    queryAll(...componentTypes: any[]): {
+    queryAll(...componentTypes: ComponentType[]): {
         entities: readonly Entity[];
     };
     /**
@@ -5337,7 +5166,7 @@ declare class Scene implements IScene {
      * @param componentTypes - 组件类型数组
      * @returns 查询结果
      */
-    queryAny(...componentTypes: any[]): {
+    queryAny(...componentTypes: ComponentType[]): {
         entities: readonly Entity[];
     };
     /**
@@ -5346,7 +5175,7 @@ declare class Scene implements IScene {
      * @param componentTypes - 组件类型数组
      * @returns 查询结果
      */
-    queryNone(...componentTypes: any[]): {
+    queryNone(...componentTypes: ComponentType[]): {
         entities: readonly Entity[];
     };
     /**
@@ -5438,7 +5267,7 @@ declare class Scene implements IScene {
      * 添加系统到场景（addEntityProcessor的别名）
      * @param system 系统
      */
-    addSystem(system: EntitySystem): EntitySystem<[]>;
+    addSystem(system: EntitySystem): EntitySystem;
     /**
      * 从场景中删除EntitySystem处理器
      * @param processor 要删除的处理器
@@ -5474,7 +5303,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 +5329,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 +5449,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 +5530,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;
@@ -5706,7 +5545,6 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      */
     private _entityIdMap;
     private _entityIdMapVersion;
-    private _entityIdMapSize;
     /**
      * 统一的实体缓存管理器
      */
@@ -5784,6 +5622,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 +5691,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 +5748,7 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      *
      * @param entity 被添加的实体
      */
-    protected onAdded(entity: Entity): void;
+    protected onAdded(_entity: Entity): void;
     /**
      * 当实体从系统中移除时调用
      *
@@ -5910,7 +5756,7 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
      *
      * @param entity 被移除的实体
      */
-    protected onRemoved(entity: Entity): void;
+    protected onRemoved(_entity: Entity): void;
     /**
      * 释放系统资源
      *
@@ -5934,15 +5780,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 +6280,6 @@ declare class Entity {
      * 实体比较器实例
      */
     static entityComparer: EntityComparer;
-    /**
-     * 全局事件总线实例
-     * 用于发射组件相关事件
-     */
-    static eventBus: EventBus | null;
-    /**
-     * 通知Scene中的QuerySystem实体组件发生变动
-     *
-     * @param entity 发生组件变动的实体
-     */
-    private static notifyQuerySystems;
     /**
      * 实体名称
      */
@@ -6459,7 +6295,7 @@ declare class Entity {
     /**
      * 销毁状态标志
      */
-    _isDestroyed: boolean;
+    private _isDestroyed;
     /**
      * 父实体引用
      */
@@ -6504,6 +6340,15 @@ declare class Entity {
      * @returns 如果实体已被销毁则返回true
      */
     get isDestroyed(): boolean;
+    /**
+     * 设置销毁状态（内部使用）
+     *
+     * 此方法供Scene和批量操作使用，以提高性能。
+     * 不应在普通业务逻辑中调用，应使用destroy()方法。
+     *
+     * @internal
+     */
+    setDestroyedState(destroyed: boolean): void;
     /**
      * 获取组件数组（懒加载）
      * @returns 只读的组件数组
@@ -6607,7 +6452,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 +6460,10 @@ declare class Entity {
      * @returns 添加的组件实例
      */
     private addComponentInternal;
+    /**
+     * 通知Scene中的QuerySystem实体组件发生变动
+     */
+    private notifyQuerySystems;
     /**
      * 添加组件到实体
      *
@@ -6676,7 +6525,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 +6842,7 @@ declare abstract class ProcessingSystem extends EntitySystem {
      * 处理实体，每帧调用processSystem方法进行处理
      * @param entities 实体数组，未被使用
      */
-    protected process(entities: Entity[]): void;
+    protected process(_entities: Entity[]): void;
     /**
      * 处理实体的具体方法，由子类实现
      */
@@ -7011,7 +6860,7 @@ declare abstract class PassiveSystem extends EntitySystem {
      * 不进行任何处理
      * @param entities 实体数组，未被使用
      */
-    protected process(entities: Entity[]): void;
+    protected process(_entities: Entity[]): void;
 }
 
 /**
@@ -8505,6 +8354,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 +8572,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 +8616,14 @@ declare class ComponentPool<T extends Component> {
         utilizationRate: number;
     };
 }
+/**
+ * 组件使用追踪
+ */
+interface ComponentUsageTracker {
+    createCount: number;
+    releaseCount: number;
+    lastAccessTime: number;
+}
 /**
  * 全局组件池管理器
  */
@@ -8609,7 +8674,11 @@ declare class ComponentPoolManager {
     /**
      * 获取全局统计信息
      */
-    getGlobalStats(): any[];
+    getGlobalStats(): Array<{
+        componentName: string;
+        poolStats: ReturnType<ComponentPool<Component>['getStats']>;
+        usage: ComponentUsageTracker | undefined;
+    }>;
     /**
      * 获取池统计信息
      */
@@ -8818,7 +8887,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 +8908,7 @@ declare class VersionMigrationManager {
      * );
      * ```
      */
-    static registerSceneMigration(fromVersion: number, toVersion: number, migration: SceneMigrationFunction): void;
+    static registerSceneMigration(fromVersion: number, _toVersion: number, migration: SceneMigrationFunction): void;
     /**
      * 迁移组件数据
      *
@@ -9264,9 +9333,7 @@ declare class EntityDataCollector {
     private collectArchetypeDataWithMemory;
     private extractArchetypeStatistics;
     private extractArchetypeStatisticsWithMemory;
-    private getArchetypeDistribution;
     private getArchetypeDistributionWithMemory;
-    private getTopEntitiesByComponents;
     private getTopEntitiesByComponentsWithMemory;
     private getEmptyEntityDebugData;
     private calculateFallbackEntityStats;
@@ -9351,7 +9418,6 @@ declare class SystemDataCollector {
 declare class PerformanceDataCollector {
     private frameTimeHistory;
     private maxHistoryLength;
-    private lastGCCount;
     private gcCollections;
     private lastMemoryCheck;
     /**
@@ -9430,7 +9496,6 @@ declare class WebSocketManager {
     private isConnected;
     private reconnectAttempts;
     private maxReconnectAttempts;
-    private reconnectInterval;
     private url;
     private autoReconnect;
     private reconnectTimer?;
@@ -9463,10 +9528,6 @@ declare class WebSocketManager {
      * 设置最大重连次数
      */
     setMaxReconnectAttempts(attempts: number): void;
-    /**
-     * 设置重连间隔
-     */
-    setReconnectInterval(interval: number): void;
     /**
      * 计划重连
      */
@@ -9544,7 +9605,7 @@ declare class DebugManager implements IService, IUpdatable {
      * 更新配置
      */
     updateConfig(config: IECSDebugConfig): void;
-    update(deltaTime?: number): void;
+    update(_deltaTime?: number): void;
     /**
      * 场景变更回调
      */
@@ -10321,7 +10382,7 @@ declare class DebugPlugin implements IPlugin, IService {
     /**
      * 安装插件
      */
-    install(core: Core, services: ServiceContainer): Promise<void>;
+    install(_core: Core, services: ServiceContainer): Promise<void>;
     /**
      * 卸载插件
      */
@@ -10385,6 +10446,10 @@ declare class DebugPlugin implements IPlugin, IService {
  * 提供 @Injectable、@Inject 和 @Updatable 装饰器，用于标记可注入的类和依赖注入点
  */
 
+/**
+ * 依赖注入元数据存储
+ */
+type Constructor = abstract new (...args: unknown[]) => unknown;
 /**
  * 可注入元数据接口
  */
@@ -10396,12 +10461,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 +10542,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 +10562,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;
 /**
  * 注册可注入的服务到容器
  *
@@ -10883,6 +10948,29 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
+/**
+ * 二进制序列化器
+ * 将对象转换为UTF8字节数组
+ */
+declare class BinarySerializer {
+    /**
+     * 将字符串编码为UTF8字节数组
+     */
+    private static stringToUtf8;
+    /**
+     * 将UTF8字节数组解码为字符串
+     */
+    private static utf8ToString;
+    /**
+     * 将对象编码为二进制数据
+     */
+    static encode(value: any): Uint8Array;
+    /**
+     * 将二进制数据解码为对象
+     */
+    static decode(bytes: Uint8Array): any;
+}
+
 /**
  * 平台适配器接口
  * 用于适配不同的运行环境（浏览器、微信小游戏、字节跳动小游戏等）
@@ -11156,5 +11244,5 @@ declare function getFullPlatformConfig(): Promise<any>;
 declare function supportsFeature(feature: 'worker' | 'shared-array-buffer' | 'transferable-objects' | 'module-worker'): boolean;
 declare function hasAdapter(): boolean;
 
-export { AutoTyped, BitMask64Utils, Bits, COMPONENT_TYPE_NAME, ChangeOperation, Colors, Component, ComponentDataCollector, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSerializer, ComponentSparseSet, ComponentStorage, ConsoleLogger, Core, DebugConfigService, DebugManager, DebugPlugin, DeepCopy, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, ENTITY_REF_METADATA, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityProcessorList, EntityRef, EntitySerializer, EntitySystem, EventBus, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, IgnoreSerialization, IncrementalSerializer, Inject, Injectable, Int16, Int32, Int8, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, MigrationBuilder, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, PlatformDetector, PlatformManager, PluginManager, PluginState, Pool, PoolManager, ProcessingSystem, QuerySystem, ReactiveQuery, ReactiveQueryChangeType, ReferenceTracker, SERIALIZABLE_METADATA, SERIALIZE_FIELD, SERIALIZE_OPTIONS, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SceneManager, SceneSerializer, Serializable, Serialize, SerializeArray, SerializeAsMap, SerializeAsSet, SerializeMap, SerializeSet, ServiceContainer, ServiceLifetime, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeInference, TypeSafeEventSystem, TypeUtils, TypedEntityBuilder, TypedQueryBuilder, TypedQueryResult, Uint16, Uint32, Uint8, Uint8Clamped, Updatable, VersionMigrationManager, WebSocketManager, WorkerEntitySystem, World, WorldManager, addAndConfigure, buildEntity, createECSAPI, createInstance, createLogger, createQuery, getBasicWorkerConfig, getComponentInstanceTypeName, getComponentTypeName, getComponents, getCurrentAdapter, getEntityRefMetadata, getFullPlatformConfig, getOrAddComponent, getSceneByEntityId, getSerializationMetadata, getSystemInstanceTypeName, getSystemMetadata, getSystemTypeName, getUpdatableMetadata, hasAdapter, hasAnyComponent, hasComponents, hasEntityRef, isComponentArray, isComponentType, isSerializable, isUpdatable, queryFor, queryForAll, registerInjectable, registerPlatformAdapter, requireComponent, resetLoggerColors, setGlobalLogLevel, setLoggerColors, setLoggerFactory, supportsFeature, tryGetComponent, updateComponent };
+export { AutoTyped, BinarySerializer, BitMask64Utils, Bits, COMPONENT_TYPE_NAME, ChangeOperation, Colors, Component, ComponentDataCollector, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSerializer, ComponentSparseSet, ComponentStorage, ConsoleLogger, Core, DebugConfigService, DebugManager, DebugPlugin, DeepCopy, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, ENTITY_REF_METADATA, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityProcessorList, EntityRef, EntitySerializer, EntitySystem, EventBus, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, IgnoreSerialization, IncrementalSerializer, Inject, Injectable, Int16, Int32, Int8, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, MigrationBuilder, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, PlatformDetector, PlatformManager, PluginManager, PluginState, Pool, PoolManager, ProcessingSystem, QuerySystem, ReactiveQuery, ReactiveQueryChangeType, ReferenceTracker, SERIALIZABLE_METADATA, SERIALIZE_FIELD, SERIALIZE_OPTIONS, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SceneManager, SceneSerializer, Serializable, Serialize, SerializeArray, SerializeAsMap, SerializeAsSet, SerializeMap, SerializeSet, ServiceContainer, ServiceLifetime, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeInference, TypeSafeEventSystem, TypeUtils, TypedEntityBuilder, TypedQueryBuilder, TypedQueryResult, Uint16, Uint32, Uint8, Uint8Clamped, Updatable, VersionMigrationManager, WebSocketManager, WorkerEntitySystem, World, WorldManager, addAndConfigure, buildEntity, createECSAPI, createInstance, createLogger, createQuery, getBasicWorkerConfig, getComponentInstanceTypeName, getComponentTypeName, getComponents, getCurrentAdapter, getEntityRefMetadata, getFullPlatformConfig, getOrAddComponent, getSceneByEntityId, getSerializationMetadata, getSystemInstanceTypeName, getSystemMetadata, getSystemTypeName, getUpdatableMetadata, hasAdapter, hasAnyComponent, hasComponents, hasEntityRef, isComponentArray, isComponentType, isSerializable, isUpdatable, queryFor, queryForAll, registerInjectable, registerPlatformAdapter, requireComponent, resetLoggerColors, setGlobalLogLevel, setLoggerColors, setLoggerFactory, supportsFeature, tryGetComponent, updateComponent };
 export type { AnyComponentConstructor, BitMask64Data, ComponentChange, ComponentConstructor, ComponentDebugInfo, ComponentInstance, ComponentMigrationFunction, ComponentType$1 as ComponentType, ComponentTypeMap, ComponentTypeName, ComponentTypeNames, DataOnly, DeepPartial, DeepReadonly, DeserializationStrategy, ECSDebugStats, EntityChange, EntityDebugInfo, EntityRefMetadata, EntityRefRecord, EntityWithComponents, EventListenerConfig, EventStats, ExtractComponents, FieldSerializeOptions, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPlatformAdapter, IPlugin, IPluginMetadata, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, IService, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IUpdatable, IWorldConfig, IWorldManagerConfig, IncrementalSerializationFormat, IncrementalSerializationOptions, IncrementalSnapshot, InjectableMetadata, LoggerColorConfig, LoggerConfig, MigrationFunction, PartialComponent, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PlatformConfig, PlatformDetectionResult, PlatformWorker, PoolStats, QueryResult$1 as QueryResult, ReactiveQueryChange, ReactiveQueryConfig, ReactiveQueryListener, ReadonlyComponent, SceneDataChange, SceneDebugInfo, SceneDeserializationOptions, SceneMigrationFunction, SceneSerializationOptions, SerializableComponent, SerializableFields, SerializableOptions, SerializationFormat, SerializationMetadata, SerializedComponent, SerializedEntity, SerializedScene, ServiceType, SharedArrayBufferProcessFunction, SupportedTypedArray, SystemDebugInfo, SystemEntityType, SystemLifecycleHooks, SystemMetadata, TypeSafeBuilder, TypedEventHandler, TypedQueryCondition, UpdatableMetadata, ValidComponent, ValidComponentArray, WorkerCreationOptions, WorkerProcessFunction, WorkerSystemConfig };