@esengine/ecs-framework 2.2.7 → 2.2.9

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.7
+ * @esengine/ecs-framework v2.2.9
  * TypeScript definitions
  */
 /**
@@ -1097,27 +1097,6 @@ declare enum LogLevel {
     Fatal = 4,
     None = 5
 }
-/**
- * 日志接口
- */
-interface ILogger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-    fatal(message: string, ...args: unknown[]): void;
-}
-/**
- * 日志颜色配置接口
- */
-interface LoggerColorConfig {
-    debug?: string;
-    info?: string;
-    warn?: string;
-    error?: string;
-    fatal?: string;
-    reset?: string;
-}
 /**
  * 预定义的颜色常量
  */
@@ -1142,6 +1121,28 @@ declare const Colors: {
     readonly BOLD: "\u001B[1m";
     readonly UNDERLINE: "\u001B[4m";
 };
+
+/**
+ * 日志接口
+ */
+interface ILogger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    fatal(...args: unknown[]): void;
+}
+/**
+ * 日志颜色配置接口
+ */
+interface LoggerColorConfig {
+    debug?: string;
+    info?: string;
+    warn?: string;
+    error?: string;
+    fatal?: string;
+    reset?: string;
+}
 /**
  * 日志配置
  */
@@ -1159,6 +1160,7 @@ interface LoggerConfig {
     /** 自定义颜色配置 */
     colors?: LoggerColorConfig;
 }
+
 /**
  * 默认控制台日志实现
  */
@@ -1230,15 +1232,19 @@ declare class ConsoleLogger implements ILogger {
      */
     private getColors;
 }
+
 /**
  * 日志管理器
  */
 declare class LoggerManager {
     private static _instance;
     private _loggers;
-    private _defaultLogger;
+    private _defaultLogger?;
     private _defaultLevel;
+    private _loggerFactory?;
     private constructor();
+    private get defaultLogger();
+    private createDefaultLogger;
     /**
      * 获取日志管理器实例
      * @returns 日志管理器实例
@@ -1277,6 +1283,11 @@ declare class LoggerManager {
      * 重置为默认颜色配置
      */
     resetColors(): void;
+    /**
+     * 设置日志器工厂方法
+     * @param factory 日志器工厂方法
+     */
+    setLoggerFactory(factory: (name?: string) => ILogger): void;
 }
 /**
  * 默认日志器实例
@@ -1302,6 +1313,11 @@ declare function resetLoggerColors(): void;
  * @param level 日志级别
  */
 declare function setGlobalLogLevel(level: LogLevel): void;
+/**
+ * 设置日志器工厂方法
+ * @param factory 日志器工厂方法
+ */
+declare function setLoggerFactory(factory: (name?: string) => ILogger): void;
 
 /**
  * 组件类型定义
@@ -5946,7 +5962,7 @@ declare abstract class EntitySystem<TComponents extends readonly ComponentConstr
     destroy(): void;
     /**
      * 获取Logger名称
-     * 子类可以重写此方法来自定义logger名称
+     * 默认返回类的构造函数名称, 子类可以重写此方法来自定义logger名称
      */
     protected getLoggerName(): string;
     /**
@@ -6240,6 +6256,121 @@ interface IScene {
      * 获取实体处理器
      */
     getEntityProcessor<T extends EntitySystem>(type: new (...args: any[]) => T): T | null;
+    /**
+     * 根据ID查找实体
+     */
+    findEntityById(id: number): Entity | null;
+    /**
+     * 根据名称查找实体
+     */
+    getEntityByName(name: string): Entity | null;
+    /**
+     * 根据标签查找实体
+     */
+    getEntitiesByTag(tag: number): Entity[];
+    /**
+     * 批量销毁实体
+     */
+    destroyEntities(entities: Entity[]): void;
+    /**
+     * 查询拥有所有指定组件的实体
+     */
+    queryAll(...componentTypes: any[]): {
+        entities: readonly Entity[];
+    };
+    /**
+     * 查询拥有任意一个指定组件的实体
+     */
+    queryAny(...componentTypes: any[]): {
+        entities: readonly Entity[];
+    };
+    /**
+     * 查询不包含指定组件的实体
+     */
+    queryNone(...componentTypes: any[]): {
+        entities: readonly Entity[];
+    };
+    /**
+     * 创建类型安全的查询构建器
+     */
+    query(): TypedQueryBuilder;
+    /**
+     * 通过类型获取System实例
+     */
+    getSystem<T extends EntitySystem>(systemType: ServiceType<T>): T | null;
+    /**
+     * 批量注册EntitySystem到场景
+     */
+    registerSystems(systemTypes: Array<ServiceType<EntitySystem>>): EntitySystem[];
+    /**
+     * 添加系统到场景
+     */
+    addSystem(system: EntitySystem): EntitySystem;
+    /**
+     * 从场景中删除系统
+     */
+    removeSystem(system: EntitySystem): void;
+    /**
+     * 获取场景统计信息
+     */
+    getStats(): {
+        entityCount: number;
+        processorCount: number;
+        componentStorageStats: Map<string, any>;
+    };
+    /**
+     * 获取场景的调试信息
+     */
+    getDebugInfo(): {
+        name: string;
+        entityCount: number;
+        processorCount: number;
+        isRunning: boolean;
+        entities: Array<{
+            name: string;
+            id: number;
+            componentCount: number;
+            componentTypes: string[];
+        }>;
+        processors: Array<{
+            name: string;
+            updateOrder: number;
+            entityCount: number;
+        }>;
+        componentStats: Map<string, any>;
+    };
+    /**
+     * 序列化场景
+     */
+    serialize(options?: SceneSerializationOptions): string | Uint8Array;
+    /**
+     * 反序列化场景
+     */
+    deserialize(saveData: string | Uint8Array, options?: SceneDeserializationOptions): void;
+    /**
+     * 创建增量序列化的基础快照
+     */
+    createIncrementalSnapshot(options?: IncrementalSerializationOptions): void;
+    /**
+     * 增量序列化场景
+     */
+    serializeIncremental(options?: IncrementalSerializationOptions): IncrementalSnapshot;
+    /**
+     * 应用增量变更到场景
+     */
+    applyIncremental(incremental: IncrementalSnapshot | string | Uint8Array, componentRegistry?: Map<string, any>): void;
+    /**
+     * 更新增量快照基准
+     */
+    updateIncrementalSnapshot(options?: IncrementalSerializationOptions): void;
+    /**
+     * 清除增量快照
+     */
+    clearIncrementalSnapshot(): void;
+    /**
+     * 检查是否有增量快照
+     */
+    hasIncrementalSnapshot(): boolean;
 }
 /**
  * 场景工厂接口
@@ -6592,6 +6723,25 @@ declare class Entity {
      * @returns 组件实例数组
      */
     getComponents<T extends Component>(type: ComponentType<T>): T[];
+    /**
+     * 获取指定基类的组件（支持继承查找）
+     *
+     * 与 getComponent() 不同，此方法使用 instanceof 检查，支持子类查找。
+     * 性能比位掩码查询稍慢，但支持继承层次结构。
+     *
+     * @param baseType - 组件基类类型
+     * @returns 第一个匹配的组件实例，如果不存在则返回 null
+     *
+     * @example
+     * ```typescript
+     * // 查找 CompositeNodeComponent 或其子类
+     * const composite = entity.getComponentByType(CompositeNodeComponent);
+     * if (composite) {
+     *     // composite 可能是 SequenceNode, SelectorNode 等
+     * }
+     * ```
+     */
+    getComponentByType<T extends Component>(baseType: ComponentType<T>): T | null;
     /**
      * 添加子实体
      *
@@ -11014,5 +11164,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, supportsFeature, tryGetComponent, updateComponent };
+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 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 };