@esengine/ecs-framework 2.1.19 → 2.1.21

package/README.md

@@ -31,8 +31,27 @@ npm install @esengine/ecs-framework
 ```typescript
 import { Core, Scene, Entity, Component, EntitySystem } from '@esengine/ecs-framework';
 
-// 创建核心实例
-const core = Core.create(true); // 调试模式
+// 创建核心实例 - 使用配置对象（推荐）
+const core = Core.create({
+    debug: true,                    // 启用调试模式
+    enableEntitySystems: true,     // 启用实体系统
+    debugConfig: {                 // 可选：调试配置
+        enabled: true,
+        websocketUrl: 'ws://localhost:8080',
+        autoReconnect: true,
+        updateInterval: 1000,
+        channels: {
+            entities: true,
+            systems: true,
+            performance: true,
+            components: true,
+            scenes: true
+        }
+    }
+});
+
+// 简化创建 - 向后兼容（仍然支持）
+const core2 = Core.create(true); // 等同于 { debug: true, enableEntitySystems: true }
 
 // 创建场景
 const scene = new Scene();
@@ -305,6 +324,7 @@ enum ECSEventType {
 | 实体管理器 | ✅ 统一接口 | ❌ 低级 API | ✅ 高级接口 |
 | 性能优化 | ✅ 多重优化 | ✅ 极致性能 | ✅ React 优化 |
 | JavaScript引擎集成 | ✅ 专为JS引擎设计 | ✅ 通用设计 | ⚠️ 主要 React |
+| 可视化调试工具 | ✅ [Cocos插件](https://store.cocos.com/app/detail/7823) | ❌ 无官方工具 | ✅ React DevTools |
 
 **选择指南：**
 - 选择本框架：需要完整的游戏开发工具链和中文社区支持
@@ -331,6 +351,7 @@ ecs-framework/
 ### 🎯 新手入门
 - **[📖 新手教程完整指南](docs/beginner-tutorials.md)** - 完整学习路径，从零开始 ⭐ **强烈推荐**
 - **[🚀 快速入门](docs/getting-started.md)** - 详细的入门教程，包含Laya/Cocos/Node.js集成指南 ⭐ **平台集成必读**
+  - 💡 **Cocos Creator用户特别提示**：我们提供[专用调试插件](https://store.cocos.com/app/detail/7823)，支持可视化ECS调试
 - [🧠 技术概念详解](docs/concepts-explained.md) - 通俗易懂的技术概念解释 ⭐ **推荐新手阅读**
 - [🎯 位掩码使用指南](docs/bitmask-guide.md) - 位掩码概念、原理和高级使用技巧
 - [💡 使用场景示例](docs/use-cases.md) - 不同类型游戏的具体应用案例

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.19
+ * @esengine/ecs-framework v2.1.21
  * TypeScript definitions
  */
 /**
@@ -759,6 +759,207 @@ interface IPerformanceEventData extends IEventData {
     /** 额外数据 */
     metadata?: Record<string, any>;
 }
+/**
+ * ECS调试配置接口
+ */
+interface IECSDebugConfig {
+    /** 是否启用调试 */
+    enabled: boolean;
+    /** WebSocket服务器URL */
+    websocketUrl: string;
+    /** 是否自动重连 */
+    autoReconnect?: boolean;
+    /** 数据更新间隔（毫秒） */
+    updateInterval?: number;
+    /** 数据通道配置 */
+    channels: {
+        entities: boolean;
+        systems: boolean;
+        performance: boolean;
+        components: boolean;
+        scenes: boolean;
+    };
+}
+/**
+ * Core配置接口
+ */
+interface ICoreConfig {
+    /** 是否启用调试模式 */
+    debug?: boolean;
+    /** 是否启用实体系统 */
+    enableEntitySystems?: boolean;
+    /** 调试配置 */
+    debugConfig?: IECSDebugConfig;
+}
+/**
+ * ECS调试数据接口
+ */
+interface IECSDebugData {
+    /** 时间戳 */
+    timestamp: number;
+    /** 框架版本 */
+    frameworkVersion?: string;
+    /** 是否正在运行 */
+    isRunning: boolean;
+    /** 框架是否已加载 */
+    frameworkLoaded: boolean;
+    /** 当前场景名称 */
+    currentScene: string;
+    /** 实体数据 */
+    entities?: IEntityDebugData;
+    /** 系统数据 */
+    systems?: ISystemDebugData;
+    /** 性能数据 */
+    performance?: IPerformanceDebugData;
+    /** 组件数据 */
+    components?: IComponentDebugData;
+    /** 场景数据 */
+    scenes?: ISceneDebugData;
+}
+/**
+ * 实体调试数据接口
+ */
+interface IEntityDebugData {
+    /** 总实体数 */
+    totalEntities: number;
+    /** 激活实体数 */
+    activeEntities: number;
+    /** 待添加实体数 */
+    pendingAdd: number;
+    /** 待移除实体数 */
+    pendingRemove: number;
+    /** 按Archetype分组的实体分布 */
+    entitiesPerArchetype: Array<{
+        signature: string;
+        count: number;
+        memory: number;
+    }>;
+    /** 组件数量最多的前几个实体 */
+    topEntitiesByComponents: Array<{
+        id: string;
+        name: string;
+        componentCount: number;
+        memory: number;
+    }>;
+    /** 实体详情列表 */
+    entityDetails?: Array<{
+        id: string | number;
+        name?: string;
+        tag?: string;
+        enabled: boolean;
+        componentCount: number;
+        components: string[];
+    }>;
+}
+/**
+ * 系统调试数据接口
+ */
+interface ISystemDebugData {
+    /** 总系统数 */
+    totalSystems: number;
+    /** 系统信息列表 */
+    systemsInfo: Array<{
+        name: string;
+        type: string;
+        entityCount: number;
+        executionTime?: number;
+        averageExecutionTime?: number;
+        minExecutionTime?: number;
+        maxExecutionTime?: number;
+        executionTimeHistory?: number[];
+        memoryUsage?: number;
+        updateOrder: number;
+        enabled: boolean;
+        lastUpdateTime?: number;
+    }>;
+}
+/**
+ * 性能调试数据接口
+ */
+interface IPerformanceDebugData {
+    /** ECS框架执行时间（毫秒） */
+    frameTime: number;
+    /** 引擎总帧时间（毫秒） */
+    engineFrameTime?: number;
+    /** ECS占总帧时间百分比 */
+    ecsPercentage?: number;
+    /** 内存使用量（MB） */
+    memoryUsage: number;
+    /** FPS */
+    fps: number;
+    /** 平均ECS执行时间（毫秒） */
+    averageFrameTime: number;
+    /** 最小ECS执行时间（毫秒） */
+    minFrameTime: number;
+    /** 最大ECS执行时间（毫秒） */
+    maxFrameTime: number;
+    /** ECS执行时间历史记录 */
+    frameTimeHistory: number[];
+    /** 系统性能详情 */
+    systemPerformance: Array<{
+        systemName: string;
+        averageTime: number;
+        maxTime: number;
+        minTime: number;
+        samples: number;
+        percentage?: number;
+    }>;
+    /** 系统占比分析数据 */
+    systemBreakdown?: Array<{
+        systemName: string;
+        executionTime: number;
+        percentage: number;
+    }>;
+    /** 内存分配详情 */
+    memoryDetails?: {
+        entities: number;
+        components: number;
+        systems: number;
+        pooled: number;
+        totalMemory: number;
+        usedMemory: number;
+        freeMemory: number;
+        gcCollections: number;
+    };
+}
+/**
+ * 组件调试数据接口
+ */
+interface IComponentDebugData {
+    /** 组件类型数 */
+    componentTypes: number;
+    /** 组件实例总数 */
+    componentInstances: number;
+    /** 组件分布统计 */
+    componentStats: Array<{
+        typeName: string;
+        instanceCount: number;
+        memoryPerInstance: number;
+        totalMemory: number;
+        poolSize: number;
+        poolUtilization: number;
+        averagePerEntity?: number;
+    }>;
+}
+/**
+ * 场景调试数据接口
+ */
+interface ISceneDebugData {
+    /** 当前场景名称 */
+    currentSceneName: string;
+    /** 场景是否已初始化 */
+    isInitialized: boolean;
+    /** 场景运行时间（秒） */
+    sceneRunTime: number;
+    /** 场景实体数 */
+    sceneEntityCount: number;
+    /** 场景系统数 */
+    sceneSystemCount: number;
+    /** 场景内存使用量 */
+    sceneMemory: number;
+    /** 场景启动时间 */
+    sceneUptime: number;
+}
 
 /**
  * 游戏组件基类
@@ -2122,7 +2323,8 @@ declare abstract class EntitySystem implements ISystemBase {
     /**
      * 系统初始化
      *
-     * 在系统创建时调用，子类可以重写此方法进行初始化操作。
+     * 在系统创建时调用，自动检查场景中已存在的实体是否匹配此系统。
+     * 子类可以重写此方法进行额外的初始化操作。
      */
     initialize(): void;
     /**
@@ -3754,6 +3956,150 @@ 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;
+    /**
+     * 停止调试报告器
+     */
+    stop(): void;
+    /**
+     * 更新配置
+     * @param newConfig 新配置
+     */
+    updateConfig(newConfig: IECSDebugConfig): void;
+    /**
+     * 连接WebSocket
+     */
+    private connectWebSocket;
+    /**
+     * 启动数据流
+     */
+    private startDataStream;
+    /**
+     * 发送消息
+     */
+    private send;
+    /**
+     * 处理接收到的消息
+     * @param message 消息内容
+     */
+    private handleMessage;
+    /**
+     * 收集调试数据
+     * @returns 调试数据对象
+     */
+    private collectDebugData;
+    /**
+     * 更新FPS计算
+     */
+    private updateFPS;
+    /**
+     * 获取框架版本
+     */
+    private getFrameworkVersion;
+    /**
+     * 获取当前场景名称
+     */
+    private getCurrentSceneName;
+    /**
+     * 收集实体数据
+     */
+    private collectEntityData;
+    /**
+     * 获取实体详情
+     */
+    private getEntityDetails;
+    /**
+     * 收集系统数据
+     */
+    private collectSystemData;
+    /**
+     * 收集性能数据
+     */
+    private collectPerformanceData;
+    /**
+     * 获取ECS框架整体性能数据
+     */
+    private getECSPerformanceData;
+    /**
+     * 获取系统性能数据
+     */
+    private getSystemPerformance;
+    /**
+     * 获取内存详情
+     */
+    private getMemoryDetails;
+    /**
+     * 收集组件数据
+     */
+    private collectComponentData;
+    /**
+     * 计算组件实际内存大小
+     */
+    private calculateComponentMemorySize;
+    /**
+     * 估算对象内存大小（字节）
+     */
+    private estimateObjectSize;
+    /**
+     * 收集场景数据
+     */
+    private collectSceneData;
+    /**
+     * 手动触发数据收集
+     * @returns 当前调试数据
+     */
+    getDebugData(): IECSDebugData;
+    /**
+     * 重置场景时间
+     */
+    onSceneChanged(): void;
+    /**
+     * 获取连接状态
+     */
+    get connected(): boolean;
+    /**
+     * 手动重连
+     */
+    reconnect(): void;
+    /**
+     * 获取Archetype分布
+     */
+    private getArchetypeDistribution;
+    /**
+     * 获取组件数量最多的实体
+     */
+    private getTopEntitiesByComponents;
+}
+
 /**
  * 游戏引擎核心类
  *
@@ -3843,11 +4189,20 @@ declare class Core {
      * 当前活动场景
      */
     _scene?: Scene;
+    /**
+     * 调试报告器
+     *
+     * 负责收集和发送调试数据。
+     */
+    _debugReporter?: DebugReporter;
+    /**
+     * Core配置
+     */
+    private _config;
     /**
      * 创建核心实例
      *
-     * @param debug - 是否启用调试模式，默认为true
-     * @param enableEntitySystems - 是否启用实体系统，默认为true
+     * @param config - Core配置对象
      */
     private constructor();
     /**
@@ -3876,10 +4231,10 @@ declare class Core {
      *
      * 如果实例已存在，则返回现有实例。
      *
-     * @param debug - 是否为调试模式，默认为true
+     * @param config - Core配置，也可以直接传入boolean表示debug模式（向后兼容）
      * @returns Core实例
      */
-    static create(debug?: boolean): Core;
+    static create(config?: ICoreConfig | boolean): Core;
     /**
      * 更新游戏逻辑
      *
@@ -3945,6 +4300,28 @@ declare class Core {
      * @returns ECS API实例，如果未初始化则返回null
      */
     static get ecsAPI(): ECSFluentAPI | null;
+    /**
+     * 启用调试功能
+     *
+     * @param config 调试配置
+     */
+    static enableDebug(config: IECSDebugConfig): void;
+    /**
+     * 禁用调试功能
+     */
+    static disableDebug(): void;
+    /**
+     * 获取调试数据
+     *
+     * @returns 当前调试数据，如果调试未启用则返回null
+     */
+    static getDebugData(): any;
+    /**
+     * 检查调试是否启用
+     *
+     * @returns 调试状态
+     */
+    static get isDebugEnabled(): boolean;
     /**
      * 场景切换回调
      *
@@ -5019,6 +5396,54 @@ declare class ComponentPool<T extends Component> {
      */
     getMaxSize(): number;
 }
+/**
+ * 全局组件池管理器
+ */
+declare class ComponentPoolManager {
+    private static instance;
+    private pools;
+    private constructor();
+    static getInstance(): ComponentPoolManager;
+    /**
+     * 注册组件池
+     */
+    registerPool<T extends Component>(componentName: string, createFn: () => T, resetFn?: (component: T) => void, maxSize?: number): void;
+    /**
+     * 获取组件实例
+     */
+    acquireComponent<T extends Component>(componentName: string): T | null;
+    /**
+     * 释放组件实例
+     */
+    releaseComponent<T extends Component>(componentName: string, component: T): void;
+    /**
+     * 预热所有池
+     */
+    prewarmAll(count?: number): void;
+    /**
+     * 清空所有池
+     */
+    clearAll(): void;
+    /**
+     * 获取池统计信息
+     */
+    getPoolStats(): Map<string, {
+        available: number;
+        maxSize: number;
+    }>;
+    /**
+     * 获取池利用率信息（用于调试）
+     */
+    getPoolUtilization(): Map<string, {
+        used: number;
+        total: number;
+        utilization: number;
+    }>;
+    /**
+     * 获取指定组件的池利用率
+     */
+    getComponentUtilization(componentName: string): number;
+}
 
 /**
  * 类型工具类
@@ -5093,5 +5518,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentIndexManager, ComponentPool, 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 type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentEventData, IEntityEventData, IEventBus, IEventData, IEventListenerConfig, IEventStats, IPerformanceEventData, IPoolable, ISceneEventData, ISystemBase, ISystemEventData, ITimer, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+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 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 };