@esengine/ecs-framework 2.2.15 → 2.2.16

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.15
+ * @esengine/ecs-framework v2.2.16
  * TypeScript definitions
  */
 /**
@@ -251,6 +251,8 @@ interface IComponent {
     onAddedToEntity(): void;
     /** 组件从实体移除时的回调 */
     onRemovedFromEntity(): void;
+    /** 组件反序列化后的回调 */
+    onDeserialized(): void | Promise<void>;
 }
 /**
  * 系统基础接口
@@ -771,6 +773,32 @@ declare abstract class Component implements IComponent {
      * 虽然保留此方法，但建议将复杂的清理逻辑放在 System 中处理。
      */
     onRemovedFromEntity(): void;
+    /**
+     * 组件反序列化后的回调
+     *
+     * 当组件从场景文件加载或快照恢复后调用，可以在此方法中恢复运行时数据。
+     *
+     * @remarks
+     * 这是一个生命周期钩子，用于恢复无法序列化的运行时数据。
+     * 例如：从图片路径重新加载图片尺寸信息，重建缓存等。
+     *
+     * @example
+     * ```typescript
+     * class TilemapComponent extends Component {
+     *     public tilesetImage: string = '';
+     *     private _tilesetData: TilesetData | undefined;
+     *
+     *     public async onDeserialized(): Promise<void> {
+     *         if (this.tilesetImage) {
+     *             // 重新加载 tileset 图片并恢复运行时数据
+     *             const img = await loadImage(this.tilesetImage);
+     *             this.setTilesetInfo(img.width, img.height, ...);
+     *         }
+     *     }
+     * }
+     * ```
+     */
+    onDeserialized(): void | Promise<void>;
 }
 
 /**
@@ -1896,6 +1924,12 @@ interface IService {
  * 使用 any[] 以允许任意参数类型的构造函数
  */
 type ServiceType<T extends IService> = new (...args: any[]) => T;
+/**
+ * 服务标识符
+ *
+ * 支持类构造函数或 Symbol 作为服务标识符
+ */
+type ServiceIdentifier<T extends IService = IService> = ServiceType<T> | symbol;
 /**
  * 服务生命周期
  */
@@ -1992,35 +2026,42 @@ declare class ServiceContainer {
      *
      * 直接注册已创建的实例，自动视为单例。
      *
-     * @param type - 服务类型（构造函数，仅用作标识）
+     * @param identifier - 服务标识符（构造函数或 Symbol）
      * @param instance - 服务实例
      *
      * @example
      * ```typescript
      * const config = new Config();
      * container.registerInstance(Config, config);
+     *
+     * // 使用 Symbol 作为标识符（适用于接口）
+     * const IFileSystem = Symbol('IFileSystem');
+     * container.registerInstance(IFileSystem, new TauriFileSystem());
      * ```
      */
-    registerInstance<T extends IService>(type: ServiceType<T>, instance: T): void;
+    registerInstance<T extends IService>(identifier: ServiceIdentifier<T>, instance: T): void;
     /**
      * 解析服务
      *
-     * @param type - 服务类型
+     * @param identifier - 服务标识符（构造函数或 Symbol）
      * @returns 服务实例
      * @throws 如果服务未注册或存在循环依赖
      *
      * @example
      * ```typescript
      * const timer = container.resolve(TimerManager);
+     *
+     * // 使用 Symbol
+     * const fileSystem = container.resolve(IFileSystem);
      * ```
      */
-    resolve<T extends IService>(type: ServiceType<T>): T;
+    resolve<T extends IService>(identifier: ServiceIdentifier<T>): T;
     /**
      * 尝试解析服务
      *
      * 如果服务未注册，返回null而不是抛出异常。
      *
-     * @param type - 服务类型
+     * @param identifier - 服务标识符（构造函数或 Symbol）
      * @returns 服务实例或null
      *
      * @example
@@ -2031,31 +2072,31 @@ declare class ServiceContainer {
      * }
      * ```
      */
-    tryResolve<T extends IService>(type: ServiceType<T>): T | null;
+    tryResolve<T extends IService>(identifier: ServiceIdentifier<T>): T | null;
     /**
      * 检查服务是否已注册
      *
-     * @param type - 服务类型
+     * @param identifier - 服务标识符（构造函数或 Symbol）
      * @returns 是否已注册
      */
-    isRegistered<T extends IService>(type: ServiceType<T>): boolean;
+    isRegistered<T extends IService>(identifier: ServiceIdentifier<T>): boolean;
     /**
      * 注销服务
      *
-     * @param type - 服务类型
+     * @param identifier - 服务标识符（构造函数或 Symbol）
      * @returns 是否成功注销
      */
-    unregister<T extends IService>(type: ServiceType<T>): boolean;
+    unregister<T extends IService>(identifier: ServiceIdentifier<T>): boolean;
     /**
      * 清空所有服务
      */
     clear(): void;
     /**
-     * 获取所有已注册的服务类型
+     * 获取所有已注册的服务标识符
      *
-     * @returns 服务类型数组
+     * @returns 服务标识符数组
      */
-    getRegisteredServices(): ServiceType<IService>[];
+    getRegisteredServices(): ServiceIdentifier[];
     /**
      * 更新所有使用@Updatable装饰器标记的服务
      *
@@ -2292,6 +2333,7 @@ interface QueryCondition$1 {
     tag?: number;
     name?: string;
     component?: ComponentType;
+    matchNothing?: boolean;
 }
 /**
  * 实体匹配条件描述符
@@ -2349,6 +2391,29 @@ declare class Matcher {
      * 创建空匙配器
      */
     static empty(): Matcher;
+    /**
+     * 创建不匹配任何实体的匹配器
+     * 用于只需要 onBegin/onEnd 生命周期方法但不需要处理实体的系统
+     *
+     * @example
+     * ```typescript
+     * // 创建一个只在帧开始时执行的系统
+     * class FrameBeginSystem extends EntitySystem {
+     *     constructor() {
+     *         super(Matcher.nothing());
+     *     }
+     *
+     *     protected onBegin(): void {
+     *         // 每帧开始时执行
+     *     }
+     *
+     *     protected process(entities: readonly Entity[]): void {
+     *         // 永远不会被调用，因为没有实体匹配
+     *     }
+     * }
+     * ```
+     */
+    static nothing(): Matcher;
     /**
      * 必须包含所有指定组件
      * @param types 组件类型
@@ -2407,8 +2472,13 @@ declare class Matcher {
     getCondition(): Readonly<QueryCondition$1>;
     /**
      * 检查是否为空条件
+     * 注意：matchNothing 不算空条件，因为它是明确的"不匹配任何实体"语义
      */
     isEmpty(): boolean;
+    /**
+     * 检查是否为"不匹配任何实体"的匹配器
+     */
+    isNothing(): boolean;
     /**
      * 重置所有条件
      */
@@ -4513,6 +4583,10 @@ declare class SceneSerializer {
      * @param options 反序列化选项
      */
     static deserialize(scene: IScene, saveData: string | Uint8Array, options?: SceneDeserializationOptions): void;
+    /**
+     * 递归调用实体及其子实体所有组件的 onDeserialized 方法
+     */
+    private static callOnDeserializedRecursively;
     /**
      * 递归添加实体的所有子实体到场景
      *
@@ -7856,6 +7930,19 @@ declare global {
 }
 
 type PropertyType = 'number' | 'integer' | 'string' | 'boolean' | 'color' | 'vector2' | 'vector3' | 'enum' | 'asset' | 'animationClips';
+/**
+ * 资源类型
+ * Asset type for asset properties
+ */
+type AssetType = 'texture' | 'audio' | 'scene' | 'prefab' | 'animation' | 'any';
+/**
+ * 枚举选项 - 支持简单字符串或带标签的对象
+ * Enum option - supports simple string or labeled object
+ */
+type EnumOption = string | {
+    label: string;
+    value: any;
+};
 /**
  * Action button configuration for property fields
  * 属性字段的操作按钮配置
@@ -7880,31 +7967,94 @@ interface PropertyControl {
     /** 被控制的属性名称 | Target property name */
     property: string;
 }
-interface PropertyOptions {
-    /** 属性类型 */
-    type: PropertyType;
-    /** 显示标签 */
+/**
+ * 属性基础选项
+ * Base property options shared by all types
+ */
+interface PropertyOptionsBase {
+    /** 显示标签 | Display label */
     label?: string;
-    /** 最小值 (number/integer) */
-    min?: number;
-    /** 最大值 (number/integer) */
-    max?: number;
-    /** 步进值 (number/integer) */
-    step?: number;
-    /** 枚举选项 (enum) */
-    options?: Array<{
-        label: string;
-        value: any;
-    }>;
-    /** 是否只读 */
+    /** 是否只读 | Read-only flag */
     readOnly?: boolean;
-    /** 资源文件扩展名 (asset) */
-    fileExtension?: string;
-    /** Action buttons for this property | 属性的操作按钮 */
+    /** Action buttons | 操作按钮 */
     actions?: PropertyAction[];
     /** 此属性控制的其他组件属性 | Properties this field controls */
     controls?: PropertyControl[];
 }
+/**
+ * 数值类型属性选项
+ * Number property options
+ */
+interface NumberPropertyOptions extends PropertyOptionsBase {
+    type: 'number' | 'integer';
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * 字符串类型属性选项
+ * String property options
+ */
+interface StringPropertyOptions extends PropertyOptionsBase {
+    type: 'string';
+    /** 多行文本 | Multiline text */
+    multiline?: boolean;
+}
+/**
+ * 布尔类型属性选项
+ * Boolean property options
+ */
+interface BooleanPropertyOptions extends PropertyOptionsBase {
+    type: 'boolean';
+}
+/**
+ * 颜色类型属性选项
+ * Color property options
+ */
+interface ColorPropertyOptions extends PropertyOptionsBase {
+    type: 'color';
+    /** 是否包含透明度 | Include alpha channel */
+    alpha?: boolean;
+}
+/**
+ * 向量类型属性选项
+ * Vector property options
+ */
+interface VectorPropertyOptions extends PropertyOptionsBase {
+    type: 'vector2' | 'vector3';
+}
+/**
+ * 枚举类型属性选项
+ * Enum property options
+ */
+interface EnumPropertyOptions extends PropertyOptionsBase {
+    type: 'enum';
+    /** 枚举选项列表 | Enum options list */
+    options: EnumOption[];
+}
+/**
+ * 资源类型属性选项
+ * Asset property options
+ */
+interface AssetPropertyOptions extends PropertyOptionsBase {
+    type: 'asset';
+    /** 资源类型 | Asset type */
+    assetType?: AssetType;
+    /** 文件扩展名过滤 | File extension filter */
+    extensions?: string[];
+}
+/**
+ * 动画剪辑类型属性选项
+ * Animation clips property options
+ */
+interface AnimationClipsPropertyOptions extends PropertyOptionsBase {
+    type: 'animationClips';
+}
+/**
+ * 属性选项联合类型
+ * Property options union type
+ */
+type PropertyOptions = NumberPropertyOptions | StringPropertyOptions | BooleanPropertyOptions | ColorPropertyOptions | VectorPropertyOptions | EnumPropertyOptions | AssetPropertyOptions | AnimationClipsPropertyOptions;
 declare const PROPERTY_METADATA: unique symbol;
 /**
  * 属性装饰器 - 声明组件属性的编辑器元数据
@@ -11859,4 +12009,4 @@ declare function supportsFeature(feature: 'worker' | 'shared-array-buffer' | 'tr
 declare function hasAdapter(): boolean;
 
 export { BinarySerializer, BitMask64Utils, Bits, COMPONENT_DEPENDENCIES, 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, IdentifierPool, IgnoreSerialization, IncrementalSerializer, InjectProperty, Injectable, Int16, Int32, Int8, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, MigrationBuilder, NumberExtension, PROPERTY_METADATA, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, PlatformDetector, PlatformManager, PluginManager, PluginState, Pool, PoolManager, ProcessingSystem, Property, 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, TypeSafeEventSystem, TypeUtils, TypedEntityBuilder, TypedQueryBuilder, TypedQueryResult, Uint16, Uint32, Uint8, Uint8Clamped, Updatable, VersionMigrationManager, WebSocketManager, WorkerEntitySystem, World, WorldManager, addAndConfigure, buildEntity, createECSAPI, createInstance, createLogger, createQuery, getBasicWorkerConfig, getComponentDependencies, getComponentInstanceTypeName, getComponentTypeName, getComponents, getCurrentAdapter, getEntityRefMetadata, getFullPlatformConfig, getOrAddComponent, getPropertyInjectMetadata, getPropertyMetadata, getSceneByEntityId, getSerializationMetadata, getSystemInstanceTypeName, getSystemMetadata, getSystemTypeName, getUpdatableMetadata, hasAdapter, hasAnyComponent, hasComponents, hasEntityRef, hasPropertyMetadata, injectProperties, 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, ComponentOptions, 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, PropertyControl, PropertyOptions, PropertyType, 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 };
+export type { AnyComponentConstructor, AssetType, BitMask64Data, ComponentChange, ComponentConstructor, ComponentDebugInfo, ComponentInstance, ComponentMigrationFunction, ComponentOptions, ComponentType$1 as ComponentType, ComponentTypeMap, ComponentTypeName, ComponentTypeNames, DataOnly, DeepPartial, DeepReadonly, DeserializationStrategy, ECSDebugStats, EntityChange, EntityDebugInfo, EntityRefMetadata, EntityRefRecord, EntityWithComponents, EnumOption, 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, PropertyAction, PropertyControl, PropertyOptions, PropertyType, QueryResult$1 as QueryResult, ReactiveQueryChange, ReactiveQueryConfig, ReactiveQueryListener, ReadonlyComponent, SceneDataChange, SceneDebugInfo, SceneDeserializationOptions, SceneMigrationFunction, SceneSerializationOptions, SerializableComponent, SerializableFields, SerializableOptions, SerializationFormat, SerializationMetadata, SerializedComponent, SerializedEntity, SerializedScene, ServiceIdentifier, ServiceType, SharedArrayBufferProcessFunction, SupportedTypedArray, SystemDebugInfo, SystemEntityType, SystemLifecycleHooks, SystemMetadata, TypeSafeBuilder, TypedEventHandler, TypedQueryCondition, UpdatableMetadata, ValidComponent, ValidComponentArray, WorkerCreationOptions, WorkerProcessFunction, WorkerSystemConfig };