@esengine/ecs-framework 2.2.4 → 2.2.6

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.4
+ * @esengine/ecs-framework v2.2.6
  * TypeScript definitions
  */
 /**
@@ -470,6 +470,8 @@ interface ICoreConfig {
     enableEntitySystems?: boolean;
     /** 调试配置 */
     debugConfig?: IECSDebugConfig;
+    /** WorldManager配置 */
+    worldManagerConfig?: IWorldManagerConfig;
 }
 /**
  * ECS调试数据接口
@@ -4754,6 +4756,18 @@ declare class SceneSerializer {
      * @param options 反序列化选项
      */
     static deserialize(scene: IScene, saveData: string | Uint8Array, options?: SceneDeserializationOptions): void;
+    /**
+     * 递归添加实体的所有子实体到场景
+     *
+     * 修复反序列化时子实体丢失的问题：
+     * EntitySerializer.deserialize会提前设置子实体的scene引用，
+     * 导致Entity.addChild的条件判断(!child.scene)跳过scene.addEntity调用。
+     * 因此需要在SceneSerializer中统一递归添加所有子实体。
+     *
+     * @param entity 父实体
+     * @param scene 目标场景
+     */
+    private static addChildrenRecursively;
     /**
      * 序列化场景自定义数据
      *
@@ -5144,11 +5158,11 @@ declare class Scene implements IScene {
      */
     private readonly logger;
     /**
-     * 性能监控器
+     * 性能监控器缓存
      *
-     * 用于监控场景和系统的性能。可以在构造函数中注入，如果不提供则从Core获取。
+     * 用于监控场景和系统的性能。从 ServiceContainer 获取。
      */
-    private readonly _performanceMonitor;
+    private _performanceMonitor;
     /**
      * 场景是否已开始运行
      */
@@ -5195,6 +5209,12 @@ declare class Scene implements IScene {
      * 创建场景实例
      */
     constructor(config?: ISceneConfig);
+    /**
+     * 获取性能监控器
+     *
+     * 从 ServiceContainer 获取，如果未注册则创建默认实例（向后兼容）
+     */
+    private get performanceMonitor();
     /**
      * 初始化场景
      *
@@ -6146,6 +6166,12 @@ interface IScene {
      * 引用追踪器
      */
     readonly referenceTracker: ReferenceTracker;
+    /**
+     * 服务容器
+     *
+     * 场景级别的依赖注入容器，用于管理服务的生命周期。
+     */
+    readonly services: ServiceContainer;
     /**
      * 获取系统列表
      */
@@ -6232,13 +6258,6 @@ interface ISceneConfig {
      * 场景名称
      */
     name?: string;
-    /**
-     * 性能监控器实例（可选）
-     *
-     * 如果不提供，Scene会自动从Core.services获取全局PerformanceMonitor。
-     * 提供此参数可以实现场景级别的独立性能监控。
-     */
-    performanceMonitor?: any;
 }
 
 /**
@@ -7757,11 +7776,15 @@ declare class SceneManager implements IService {
      * 场景切换回调函数
      */
     private _onSceneChangedCallback?;
+    /**
+     * 性能监控器（从 Core 注入）
+     */
+    private _performanceMonitor;
     /**
      * 默认场景ID
      */
     private static readonly DEFAULT_SCENE_ID;
-    constructor();
+    constructor(performanceMonitor?: PerformanceMonitor);
     /**
      * 设置场景切换回调
      *
@@ -9349,6 +9372,7 @@ declare class DebugManager implements IService, IUpdatable {
     private lastSendTime;
     private sendInterval;
     private isRunning;
+    private originalConsole;
     constructor(sceneManager: SceneManager, performanceMonitor: PerformanceMonitor, configService: DebugConfigService);
     /**
      * 启动调试管理器
@@ -9358,6 +9382,22 @@ declare class DebugManager implements IService, IUpdatable {
      * 停止调试管理器
      */
     stop(): void;
+    /**
+     * 拦截 console 日志并转发到编辑器
+     */
+    private interceptConsole;
+    /**
+     * 格式化日志消息
+     */
+    private formatLogMessage;
+    /**
+     * 安全的 JSON 序列化,支持循环引用和深度限制
+     */
+    private safeStringify;
+    /**
+     * 发送日志到编辑器
+     */
+    private sendLog;
     /**
      * 更新配置
      */
@@ -10047,6 +10087,156 @@ declare class PluginManager implements IService {
     dispose(): void;
 }
 
+/**
+ * ECS 调试插件统计信息
+ */
+interface ECSDebugStats {
+    scenes: SceneDebugInfo[];
+    totalEntities: number;
+    totalSystems: number;
+    timestamp: number;
+}
+/**
+ * 场景调试信息
+ */
+interface SceneDebugInfo {
+    name: string;
+    entityCount: number;
+    systems: SystemDebugInfo[];
+    entities: EntityDebugInfo[];
+}
+/**
+ * 系统调试信息
+ */
+interface SystemDebugInfo {
+    name: string;
+    enabled: boolean;
+    updateOrder: number;
+    entityCount: number;
+    performance?: {
+        avgExecutionTime: number;
+        maxExecutionTime: number;
+        totalCalls: number;
+    };
+}
+/**
+ * 实体调试信息
+ */
+interface EntityDebugInfo {
+    id: number;
+    name: string;
+    enabled: boolean;
+    tag: number;
+    componentCount: number;
+    components: ComponentDebugInfo[];
+}
+/**
+ * 组件调试信息
+ */
+interface ComponentDebugInfo {
+    type: string;
+    data: any;
+}
+/**
+ * ECS 调试插件
+ *
+ * 提供运行时调试功能：
+ * - 实时查看实体和组件信息
+ * - System 执行统计
+ * - 性能监控
+ * - 实体查询
+ *
+ * @example
+ * ```typescript
+ * const core = Core.create();
+ * const debugPlugin = new DebugPlugin({ autoStart: true, updateInterval: 1000 });
+ * await core.pluginManager.install(debugPlugin);
+ *
+ * // 获取调试信息
+ * const stats = debugPlugin.getStats();
+ * console.log('Total entities:', stats.totalEntities);
+ *
+ * // 查询实体
+ * const entities = debugPlugin.queryEntities({ tag: 1 });
+ * ```
+ */
+declare class DebugPlugin implements IPlugin, IService {
+    readonly name = "@esengine/debug-plugin";
+    readonly version = "1.0.0";
+    private worldManager;
+    private updateInterval;
+    private updateTimer;
+    private autoStart;
+    /**
+     * 创建调试插件实例
+     *
+     * @param options - 配置选项
+     */
+    constructor(options?: {
+        autoStart?: boolean;
+        updateInterval?: number;
+    });
+    /**
+     * 安装插件
+     */
+    install(core: Core, services: ServiceContainer): Promise<void>;
+    /**
+     * 卸载插件
+     */
+    uninstall(): Promise<void>;
+    /**
+     * 实现 IService 接口
+     */
+    dispose(): void;
+    /**
+     * 启动调试监控
+     */
+    start(): void;
+    /**
+     * 停止调试监控
+     */
+    stop(): void;
+    /**
+     * 获取当前 ECS 统计信息
+     */
+    getStats(): ECSDebugStats;
+    /**
+     * 获取场景调试信息
+     */
+    getSceneInfo(scene: IScene): SceneDebugInfo;
+    /**
+     * 获取系统调试信息
+     */
+    private getSystemInfo;
+    /**
+     * 获取实体调试信息
+     */
+    getEntityInfo(entity: Entity): EntityDebugInfo;
+    /**
+     * 获取组件调试信息
+     */
+    private getComponentInfo;
+    /**
+     * 查询实体
+     *
+     * @param filter - 查询过滤器
+     */
+    queryEntities(filter: {
+        sceneId?: string;
+        tag?: number;
+        name?: string;
+        hasComponent?: string;
+    }): EntityDebugInfo[];
+    /**
+     * 打印统计信息到日志
+     */
+    private logStats;
+    /**
+     * 导出调试数据为 JSON
+     */
+    exportJSON(): string;
+}
+
 /**
  * 依赖注入装饰器
  *
@@ -10824,5 +11014,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, 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, supportsFeature, tryGetComponent, updateComponent };
-export type { AnyComponentConstructor, BitMask64Data, ComponentChange, ComponentConstructor, ComponentInstance, ComponentMigrationFunction, ComponentType$1 as ComponentType, ComponentTypeMap, ComponentTypeName, ComponentTypeNames, DataOnly, DeepPartial, DeepReadonly, DeserializationStrategy, EntityChange, 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, SceneDeserializationOptions, SceneMigrationFunction, SceneSerializationOptions, SerializableComponent, SerializableFields, SerializableOptions, SerializationFormat, SerializationMetadata, SerializedComponent, SerializedEntity, SerializedScene, ServiceType, SharedArrayBufferProcessFunction, SupportedTypedArray, SystemEntityType, SystemLifecycleHooks, SystemMetadata, TypeSafeBuilder, TypedEventHandler, TypedQueryCondition, UpdatableMetadata, ValidComponent, ValidComponentArray, WorkerCreationOptions, WorkerProcessFunction, WorkerSystemConfig };
+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, 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 };