@esengine/ecs-framework 2.1.22 → 2.1.24

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.22
+ * @esengine/ecs-framework v2.1.24
  * TypeScript definitions
  */
 /**
@@ -769,8 +769,10 @@ interface IECSDebugConfig {
     websocketUrl: string;
     /** 是否自动重连 */
     autoReconnect?: boolean;
-    /** 数据更新间隔（毫秒） */
+    /** 数据更新间隔（毫秒）- 已弃用，使用debugFrameRate替代 */
     updateInterval?: number;
+    /** 调试数据发送帧率 (60fps, 30fps, 15fps) */
+    debugFrameRate?: 60 | 30 | 15;
     /** 数据通道配置 */
     channels: {
         entities: boolean;
@@ -850,6 +852,44 @@ interface IEntityDebugData {
         componentCount: number;
         components: string[];
     }>;
+    /** 实体层次结构（根实体） */
+    entityHierarchy?: Array<{
+        id: number;
+        name: string;
+        active: boolean;
+        enabled: boolean;
+        activeInHierarchy: boolean;
+        componentCount: number;
+        componentTypes: string[];
+        parentId: number | null;
+        children: any[];
+        depth: number;
+        tag: number;
+        updateOrder: number;
+    }>;
+    /** 实体详细信息映射 */
+    entityDetailsMap?: Record<number, {
+        id: number;
+        name: string;
+        active: boolean;
+        enabled: boolean;
+        activeInHierarchy: boolean;
+        destroyed: boolean;
+        tag: number;
+        updateOrder: number;
+        componentMask: string;
+        parentId: number | null;
+        parentName: string | null;
+        childCount: number;
+        childIds: number[];
+        depth: number;
+        components: Array<{
+            typeName: string;
+            properties: Record<string, any>;
+        }>;
+        componentCount: number;
+        componentTypes: string[];
+    }>;
 }
 /**
  * 系统调试数据接口
@@ -3957,94 +3997,118 @@ declare class EntityBatchOperator {
 declare function createECSAPI(scene: Scene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem): ECSFluentAPI;
 
 /**
- * ECS调试报告器 - WebSocket模式
- *
- * 负责收集ECS框架的运行时调试数据并通过WebSocket发送到调试服务器
+ * 实体数据收集器
  */
-declare class DebugReporter {
-    private config;
-    private core;
-    private timer?;
-    private ws?;
-    private lastFrameTime;
-    private frameCount;
-    private lastFpsTime;
-    private fps;
-    private sceneStartTime;
-    private isConnected;
-    private reconnectAttempts;
-    private maxReconnectAttempts;
-    private frameTimeHistory;
-    private maxHistoryLength;
-    /**
-     * 构造函数
-     * @param core Core实例
-     * @param config 调试配置
-     */
-    constructor(core: Core, config: IECSDebugConfig);
-    /**
-     * 启动调试报告器
-     */
-    private start;
+declare class EntityDataCollector {
+    collectEntityData(): IEntityDebugData;
+    getRawEntityList(): Array<{
+        id: number;
+        name: string;
+        active: boolean;
+        enabled: boolean;
+        activeInHierarchy: boolean;
+        componentCount: number;
+        componentTypes: string[];
+        parentId: number | null;
+        childIds: number[];
+        depth: number;
+        tag: number;
+        updateOrder: number;
+    }>;
+    getEntityDetails(entityId: number): any;
+    private getSceneInfo;
+    collectEntityDataWithMemory(): IEntityDebugData;
+    private collectArchetypeData;
+    private getArchetypeDistributionFast;
+    private getTopEntitiesByComponentsFast;
+    private collectArchetypeDataWithMemory;
+    private extractArchetypeStatistics;
+    private extractArchetypeStatisticsWithMemory;
+    private getArchetypeDistribution;
+    private getArchetypeDistributionWithMemory;
+    private getTopEntitiesByComponents;
+    private getTopEntitiesByComponentsWithMemory;
+    private getEmptyEntityDebugData;
+    private calculateFallbackEntityStats;
+    estimateEntityMemoryUsage(entity: any): number;
+    calculateObjectSize(obj: any, excludeKeys?: string[]): number;
+    private buildEntityHierarchyTree;
     /**
-     * 停止调试报告器
+     * 构建实体层次结构节点
      */
-    stop(): void;
+    private buildEntityHierarchyNode;
     /**
-     * 更新配置
-     * @param newConfig 新配置
+     * 构建实体详情映射
      */
-    updateConfig(newConfig: IECSDebugConfig): void;
+    private buildEntityDetailsMap;
     /**
-     * 连接WebSocket
+     * 构建实体基础信息
      */
-    private connectWebSocket;
+    private buildFallbackEntityInfo;
     /**
-     * 启动数据流
+     * 提取组件详细信息
      */
-    private startDataStream;
+    extractComponentDetails(components: Component[]): Array<{
+        typeName: string;
+        properties: Record<string, any>;
+    }>;
     /**
-     * 发送消息
+     * 获取组件的完整属性信息（仅在需要时调用）
      */
-    private send;
+    getComponentProperties(entityId: number, componentIndex: number): Record<string, any>;
     /**
-     * 处理接收到的消息
-     * @param message 消息内容
+     * 格式化属性值
      */
-    private handleMessage;
+    private formatPropertyValue;
     /**
-     * 收集调试数据
-     * @returns 调试数据对象
+     * 格式化对象第一层
      */
-    private collectDebugData;
+    private formatObjectFirstLevel;
     /**
-     * 更新FPS计算
+     * 创建懒加载占位符
      */
-    private updateFPS;
+    private createLazyLoadPlaceholder;
     /**
-     * 获取框架版本
+     * 获取对象摘要信息
      */
-    private getFrameworkVersion;
+    private getObjectSummary;
     /**
-     * 获取当前场景名称
+     * 生成对象ID
      */
-    private getCurrentSceneName;
+    private generateObjectId;
     /**
-     * 收集实体数据
+     * 展开懒加载对象（供调试面板调用）
      */
-    private collectEntityData;
+    expandLazyObject(entityId: number, componentIndex: number, propertyPath: string): any;
     /**
-     * 获取实体详情
+     * 根据路径获取对象
      */
-    private getEntityDetails;
+    private getObjectByPath;
+}
+
+/**
+ * 系统数据收集器
+ */
+declare class SystemDataCollector {
     /**
      * 收集系统数据
      */
-    private collectSystemData;
+    collectSystemData(performanceMonitor: any): ISystemDebugData;
+}
+
+/**
+ * 性能数据收集器
+ */
+declare class PerformanceDataCollector {
+    private frameTimeHistory;
+    private maxHistoryLength;
+    private lastGCCount;
+    private gcCollections;
+    private lastMemoryCheck;
     /**
      * 收集性能数据
      */
-    private collectPerformanceData;
+    collectPerformanceData(performanceMonitor: any): IPerformanceDebugData;
     /**
      * 获取ECS框架整体性能数据
      */
@@ -4058,46 +4122,212 @@ declare class DebugReporter {
      */
     private getMemoryDetails;
     /**
-     * 收集组件数据
+     * 更新GC计数
+     */
+    private updateGCCount;
+}
+
+/**
+ * 组件数据收集器
+ */
+declare class ComponentDataCollector {
+    private static componentSizeCache;
+    /**
+     * 收集组件数据（轻量版，不计算实际内存大小）
+     */
+    collectComponentData(): IComponentDebugData;
+    /**
+     * 获取组件类型的估算内存大小（基于预设值，不进行实际计算）
      */
-    private collectComponentData;
+    private getEstimatedComponentSize;
+    private calculateQuickObjectSize;
     /**
-     * 计算组件实际内存大小
+     * 为内存快照功能提供的详细内存计算
+     * 只在用户主动请求内存快照时调用
      */
-    private calculateComponentMemorySize;
+    calculateDetailedComponentMemory(typeName: string): number;
     /**
-     * 估算对象内存大小（字节）
+     * 估算对象内存大小（仅用于内存快照）
+     * 优化版本：减少递归深度，提高性能
      */
     private estimateObjectSize;
+    static clearCache(): void;
+}
+
+/**
+ * 场景数据收集器
+ */
+declare class SceneDataCollector {
+    private sceneStartTime;
     /**
      * 收集场景数据
      */
-    private collectSceneData;
+    collectSceneData(): ISceneDebugData;
     /**
-     * 手动触发数据收集
-     * @returns 当前调试数据
+     * 设置场景开始时间
      */
-    getDebugData(): IECSDebugData;
+    setSceneStartTime(time: number): void;
+}
+
+/**
+ * WebSocket连接管理器
+ */
+declare class WebSocketManager {
+    private ws?;
+    private isConnected;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectInterval;
+    private url;
+    private autoReconnect;
+    private reconnectTimer?;
+    private onOpen?;
+    private onClose?;
+    private onError?;
+    private messageHandler?;
+    constructor(url: string, autoReconnect?: boolean);
     /**
-     * 重置场景时间
+     * 设置消息处理回调
      */
-    onSceneChanged(): void;
+    setMessageHandler(handler: (message: any) => void): void;
+    /**
+     * 连接WebSocket
+     */
+    connect(): Promise<void>;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 发送数据
+     */
+    send(data: any): void;
     /**
      * 获取连接状态
      */
-    get connected(): boolean;
+    getConnectionStatus(): boolean;
     /**
-     * 手动重连
+     * 设置最大重连次数
      */
-    reconnect(): void;
+    setMaxReconnectAttempts(attempts: number): void;
     /**
-     * 获取Archetype分布
+     * 设置重连间隔
      */
-    private getArchetypeDistribution;
+    setReconnectInterval(interval: number): void;
     /**
-     * 获取组件数量最多的实体
+     * 计划重连
      */
-    private getTopEntitiesByComponents;
+    private scheduleReconnect;
+    /**
+     * 处理接收到的消息
+     */
+    private handleMessage;
+    private handleOpen;
+    private handleClose;
+    private handleError;
+    private handleConnectionFailure;
+}
+
+/**
+ * 调试管理器
+ *
+ * 整合所有调试数据收集器，负责收集和发送调试数据
+ */
+declare class DebugManager {
+    private config;
+    private webSocketManager;
+    private entityCollector;
+    private systemCollector;
+    private performanceCollector;
+    private componentCollector;
+    private sceneCollector;
+    private frameCounter;
+    private lastSendTime;
+    private sendInterval;
+    private isRunning;
+    constructor(core: Core, config: IECSDebugConfig);
+    /**
+     * 启动调试管理器
+     */
+    start(): void;
+    /**
+     * 停止调试管理器
+     */
+    stop(): void;
+    /**
+     * 更新配置
+     */
+    updateConfig(config: IECSDebugConfig): void;
+    /**
+     * 帧更新回调
+     */
+    onFrameUpdate(deltaTime: number): void;
+    /**
+     * 场景变更回调
+     */
+    onSceneChanged(): void;
+    /**
+     * 处理来自调试面板的消息
+     */
+    private handleMessage;
+    /**
+     * 处理展开懒加载对象请求
+     */
+    private handleExpandLazyObjectRequest;
+    /**
+     * 处理获取组件属性请求
+     */
+    private handleGetComponentPropertiesRequest;
+    /**
+     * 处理获取原始实体列表请求
+     */
+    private handleGetRawEntityListRequest;
+    /**
+     * 处理获取实体详情请求
+     */
+    private handleGetEntityDetailsRequest;
+    /**
+     * 处理内存快照请求
+     */
+    private handleMemorySnapshotRequest;
+    /**
+     * 捕获内存快照
+     */
+    private captureMemorySnapshot;
+    /**
+     * 收集基础内存信息
+     */
+    private collectBaseMemoryInfo;
+    /**
+     * 收集组件内存统计（仅用于内存快照）
+     */
+    private collectComponentMemoryStats;
+    private collectSystemMemoryStats;
+    private calculateQuickSystemSize;
+    /**
+     * 收集对象池内存统计
+     */
+    private collectPoolMemoryStats;
+    /**
+     * 收集性能统计信息
+     */
+    private collectPerformanceStats;
+    /**
+     * 获取内存大小分类
+     */
+    private getMemorySizeCategory;
+    /**
+     * 获取调试数据
+     */
+    getDebugData(): IECSDebugData;
+    /**
+     * 连接WebSocket
+     */
+    private connectWebSocket;
+    /**
+     * 发送调试数据
+     */
+    private sendDebugData;
 }
 
 /**
@@ -4190,11 +4420,11 @@ declare class Core {
      */
     _scene?: Scene;
     /**
-     * 调试报告器
+     * 调试管理器
      *
      * 负责收集和发送调试数据。
      */
-    _debugReporter?: DebugReporter;
+    _debugManager?: DebugManager;
     /**
      * Core配置
      */
@@ -5518,5 +5748,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentStorage, ComponentTypeManager, Core, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, Entity, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, IdentifierPool, IndexType, IndexUpdateBatcher, IntervalSystem, Matcher, NumberExtension, PassiveSystem, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, TieredObjectPool, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, createECSAPI };
+export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentStorage, ComponentTypeManager, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, IdentifierPool, IndexType, IndexUpdateBatcher, IntervalSystem, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, SceneDataCollector, SystemDataCollector, TieredObjectPool, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI };
 export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEventBus, IEventData, IEventListenerConfig, IEventStats, IPerformanceDebugData, IPerformanceEventData, IPoolable, ISceneDebugData, ISceneEventData, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };