@esengine/ecs-framework 2.2.13 → 2.2.14

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.13
+ * @esengine/ecs-framework v2.2.14
  * TypeScript definitions
  */
 /**
@@ -919,16 +919,16 @@ declare class BitMask64Utils {
     private static getSegmentByBitIndex;
 }
 
+/**
+ * SoA存储器支持的TypedArray类型
+ */
+type SupportedTypedArray = Float32Array | Float64Array | Int32Array | Uint32Array | Int16Array | Uint16Array | Int8Array | Uint8Array | Uint8ClampedArray;
+
 /**
  * 启用SoA优化装饰器
  * 默认关闭SoA，只有在大规模批量操作场景下才建议开启
  */
 declare function EnableSoA<T extends ComponentType>(target: T): T;
-/**
- * 高精度数值装饰器
- * 标记字段需要保持完整精度，存储为复杂对象而非TypedArray
- */
-declare function HighPrecision(target: any, propertyKey: string | symbol): void;
 /**
  * 64位浮点数装饰器
  * 标记字段使用Float64Array存储（更高精度但更多内存）
@@ -994,51 +994,11 @@ declare function SerializeArray(target: any, propertyKey: string | symbol): void
  * 标记字段需要深拷贝处理（适用于嵌套对象）
  */
 declare function DeepCopy(target: any, propertyKey: string | symbol): void;
-/**
- * 自动类型推断装饰器
- * 根据字段的默认值和数值范围自动选择最优的TypedArray类型
- *
- * @param options 类型推断选项
- * @param options.minValue 数值的最小值（用于范围优化）
- * @param options.maxValue 数值的最大值（用于范围优化）
- * @param options.precision 是否需要浮点精度（true: 使用浮点数组, false: 使用整数数组）
- * @param options.signed 是否需要符号位（仅在整数模式下有效）
- */
-declare function AutoTyped(options?: {
-    minValue?: number;
-    maxValue?: number;
-    precision?: boolean;
-    signed?: boolean;
-}): (target: any, propertyKey: string | symbol) => void;
-/**
- * 自动类型推断器
- * 根据数值类型和范围自动选择最优的TypedArray类型
- */
-declare class TypeInference {
-    /**
-     * 根据数值范围推断最优的TypedArray类型
-     */
-    static inferOptimalType(value: any, options?: {
-        minValue?: number;
-        maxValue?: number;
-        precision?: boolean;
-        signed?: boolean;
-    }): string;
-    /**
-     * 根据推断的类型名创建对应的TypedArray构造函数
-     */
-    static getTypedArrayConstructor(typeName: string): typeof Float32Array | typeof Float64Array | typeof Int32Array | typeof Uint32Array | typeof Int16Array | typeof Uint16Array | typeof Int8Array | typeof Uint8Array | typeof Uint8ClampedArray;
-}
-/**
- * SoA存储器支持的TypedArray类型
- */
-type SupportedTypedArray = Float32Array | Float64Array | Int32Array | Uint32Array | Int16Array | Uint16Array | Int8Array | Uint8Array | Uint8ClampedArray;
 /**
  * SoA存储器（需要装饰器启用）
  * 使用Structure of Arrays存储模式，在大规模批量操作时提供优异性能
  */
 declare class SoAStorage<T extends Component> {
-    private static readonly _logger;
     private fields;
     private stringFields;
     private serializedFields;
@@ -1049,23 +1009,24 @@ declare class SoAStorage<T extends Component> {
     private _size;
     private _capacity;
     readonly type: ComponentType<T>;
+    private fieldTypes;
+    private serializeMapFields;
+    private serializeSetFields;
+    private serializeArrayFields;
     constructor(componentType: ComponentType<T>);
     private initializeFields;
     addComponent(entityId: number, component: T): void;
     private updateComponentAtIndex;
+    getComponent(entityId: number): T | null;
     /**
-     * 序列化值为JSON字符串
-     */
-    private serializeValue;
-    /**
-     * 反序列化JSON字符串为值
+     * 创建组件的 Proxy 视图
+     * 读写操作直接映射到底层 TypedArray，无数据复制
      */
-    private deserializeValue;
+    private createProxyView;
     /**
-     * 深拷贝对象
+     * 获取组件的快照副本（用于序列化等需要独立副本的场景）
      */
-    private deepClone;
-    getComponent(entityId: number): T | null;
+    getComponentSnapshot(entityId: number): T | null;
     private getFieldType;
     hasComponent(entityId: number): boolean;
     removeComponent(entityId: number): T | null;
@@ -5217,7 +5178,7 @@ declare class Scene implements IScene {
      * 在场景中添加一个EntitySystem处理器
      *
      * 支持两种使用方式：
-     * 1. 传入类型（推荐）：自动使用DI创建实例，支持@Injectable和@Inject装饰器
+     * 1. 传入类型（推荐）：自动使用DI创建实例，支持@Injectable和@InjectProperty装饰器
      * 2. 传入实例：直接使用提供的实例
      *
      * @param systemTypeOrInstance 系统类型或系统实例
@@ -5228,7 +5189,10 @@ declare class Scene implements IScene {
      * // 方式1：传入类型，自动DI（推荐）
      * @Injectable()
      * class PhysicsSystem extends EntitySystem {
-     *     constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
+     *     @InjectProperty(CollisionSystem)
+     *     private collision!: CollisionSystem;
+     *
+     *     constructor() {
      *         super(Matcher.empty().all(Transform));
      *     }
      * }
@@ -5261,7 +5225,10 @@ declare class Scene implements IScene {
      * @Injectable()
      * @ECSSystem('Physics', { updateOrder: 10 })
      * class PhysicsSystem extends EntitySystem implements IService {
-     *     constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
+     *     @InjectProperty(CollisionSystem)
+     *     private collision!: CollisionSystem;
+     *
+     *     constructor() {
      *         super(Matcher.empty().all(Transform, RigidBody));
      *     }
      *     dispose() {}
@@ -5294,7 +5261,7 @@ declare class Scene implements IScene {
     /**
      * 获取指定类型的EntitySystem处理器
      *
-     * @deprecated 推荐使用依赖注入代替此方法。使用 `scene.services.resolve(SystemType)` 或在System构造函数中使用 `@Inject(SystemType)` 装饰器。
+     * @deprecated 推荐使用依赖注入代替此方法。使用 `scene.services.resolve(SystemType)` 或使用 `@InjectProperty(SystemType)` 装饰器。
      *
      * @param type 处理器类型
      * @returns 处理器实例，如果未找到则返回null
@@ -5303,8 +5270,11 @@ declare class Scene implements IScene {
      * ```typescript
      * @Injectable()
      * class MySystem extends EntitySystem {
-     *     constructor(@Inject(PhysicsSystem) private physics: PhysicsSystem) {
-     *         super();
+     *     @InjectProperty(PhysicsSystem)
+     *     private physics!: PhysicsSystem;
+     *
+     *     constructor() {
+     *         super(Matcher.empty());
      *     }
      * }
      * ```
@@ -7275,11 +7245,14 @@ interface SystemMetadata {
  *     }
  * }
  *
- * // 配置更新顺序
+ * // 配置更新顺序和依赖注入
  * @Injectable()
  * @ECSSystem('Physics', { updateOrder: 10 })
  * class PhysicsSystem extends EntitySystem {
- *     constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
+ *     @InjectProperty(CollisionSystem)
+ *     private collision!: CollisionSystem;
+ *
+ *     constructor() {
  *         super(Matcher.empty().all(Transform, RigidBody));
  *     }
  * }
@@ -8005,15 +7978,15 @@ declare class World {
     /**
      * 创建并添加Scene到World
      */
-    createScene<T extends IScene>(sceneId: string, sceneInstance?: T): T;
+    createScene<T extends IScene>(sceneName: string, sceneInstance?: T): T;
     /**
      * 移除Scene
      */
-    removeScene(sceneId: string): boolean;
+    removeScene(sceneName: string): boolean;
     /**
      * 获取Scene
      */
-    getScene<T extends IScene>(sceneId: string): T | null;
+    getScene<T extends IScene>(sceneName: string): T | null;
     /**
      * 获取所有Scene ID
      */
@@ -8029,11 +8002,11 @@ declare class World {
     /**
      * 设置Scene激活状态
      */
-    setSceneActive(sceneId: string, active: boolean): void;
+    setSceneActive(sceneName: string, active: boolean): void;
     /**
      * 检查Scene是否激活
      */
-    isSceneActive(sceneId: string): boolean;
+    isSceneActive(sceneName: string): boolean;
     /**
      * 获取活跃Scene数量
      */
@@ -8204,15 +8177,15 @@ declare class WorldManager implements IService {
     /**
      * 创建新World
      */
-    createWorld(worldId: string, config?: IWorldConfig): World;
+    createWorld(worldName: string, config?: IWorldConfig): World;
     /**
      * 移除World
      */
-    removeWorld(worldId: string): boolean;
+    removeWorld(worldName: string): boolean;
     /**
      * 获取World
      */
-    getWorld(worldId: string): World | null;
+    getWorld(worldName: string): World | null;
     /**
      * 获取所有World ID
      */
@@ -8224,11 +8197,11 @@ declare class WorldManager implements IService {
     /**
      * 设置World激活状态
      */
-    setWorldActive(worldId: string, active: boolean): void;
+    setWorldActive(worldName: string, active: boolean): void;
     /**
      * 检查World是否激活
      */
-    isWorldActive(worldId: string): boolean;
+    isWorldActive(worldName: string): boolean;
     /**
      * 更新所有活跃的World
      *
@@ -9551,20 +9524,6 @@ declare class WebSocketManager {
     private handleConnectionFailure;
 }
 
-/**
- * 调试配置服务
- *
- * 管理调试系统的配置信息
- */
-declare class DebugConfigService implements IService {
-    private _config;
-    constructor();
-    setConfig(config: IECSDebugConfig): void;
-    getConfig(): IECSDebugConfig;
-    isEnabled(): boolean;
-    dispose(): void;
-}
-
 /**
  * 调试管理器
  *
@@ -9580,12 +9539,13 @@ declare class DebugManager implements IService, IUpdatable {
     private sceneCollector;
     private sceneManager;
     private performanceMonitor;
+    private configService;
     private frameCounter;
     private lastSendTime;
     private sendInterval;
     private isRunning;
     private originalConsole;
-    constructor(sceneManager: SceneManager, performanceMonitor: PerformanceMonitor, configService: DebugConfigService);
+    onInitialize(): void;
     /**
      * 启动调试管理器
      */
@@ -9683,6 +9643,20 @@ declare class DebugManager implements IService, IUpdatable {
     dispose(): void;
 }
 
+/**
+ * 调试配置服务
+ *
+ * 管理调试系统的配置信息
+ */
+declare class DebugConfigService implements IService {
+    private _config;
+    constructor();
+    setConfig(config: IECSDebugConfig): void;
+    getConfig(): IECSDebugConfig;
+    isEnabled(): boolean;
+    dispose(): void;
+}
+
 /**
  * 插件状态
  */
@@ -10434,7 +10408,7 @@ declare class DebugPlugin implements IPlugin, IService {
      * @param filter - 查询过滤器
      */
     queryEntities(filter: {
-        sceneId?: string;
+        sceneName?: string;
         tag?: number;
         name?: string;
         hasComponent?: string;
@@ -10452,7 +10426,7 @@ declare class DebugPlugin implements IPlugin, IService {
 /**
  * 依赖注入装饰器
  *
- * 提供 @Injectable、@Inject 和 @Updatable 装饰器，用于标记可注入的类和依赖注入点
+ * 提供 @Injectable、@InjectProperty 和 @Updatable 装饰器，用于标记可注入的类和依赖注入点
  */
 
 /**
@@ -10505,10 +10479,11 @@ interface UpdatableMetadata {
  *
  * @Injectable()
  * class PhysicsSystem extends EntitySystem {
- *     constructor(
- *         @Inject(TimeService) private timeService: TimeService
- *     ) {
- *         super();
+ *     @InjectProperty(TimeService)
+ *     private timeService!: TimeService;
+ *
+ *     constructor() {
+ *         super(Matcher.empty());
  *     }
  * }
  * ```
@@ -10545,13 +10520,43 @@ declare function Injectable(): ClassDecorator;
  */
 declare function Updatable(priority?: number): ClassDecorator;
 /**
- * @Inject() 装饰器
+ * @InjectProperty() 装饰器
  *
- * 标记构造函数参数需要注入的服务类型
+ * 通过属性装饰器注入依赖
  *
- * @param serviceType 服务类型标识符
+ * 注入时机：在构造函数执行后、onInitialize() 调用前完成
+ *
+ * @param serviceType 服务类型
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class PhysicsSystem extends EntitySystem {
+ *     @InjectProperty(TimeService)
+ *     private timeService!: TimeService;
+ *
+ *     @InjectProperty(CollisionService)
+ *     private collision!: CollisionService;
+ *
+ *     constructor() {
+ *         super(Matcher.empty());
+ *     }
+ *
+ *     public onInitialize(): void {
+ *         // 此时属性已注入完成，可以安全使用
+ *         console.log(this.timeService.getDeltaTime());
+ *     }
+ * }
+ * ```
+ */
+declare function InjectProperty(serviceType: ServiceType<IService>): PropertyDecorator;
+/**
+ * 获取属性注入元数据
+ *
+ * @param target 目标类
+ * @returns 属性名到服务类型的映射
  */
-declare function Inject(serviceType: ServiceType<IService> | string | symbol): ParameterDecorator;
+declare function getPropertyInjectMetadata(target: Constructor): Map<string | symbol, ServiceType<IService>>;
 /**
  * 创建实例并自动注入依赖
  *
@@ -10565,6 +10570,13 @@ declare function Inject(serviceType: ServiceType<IService> | string | symbol): P
  * ```
  */
 declare function createInstance<T>(constructor: new (...args: any[]) => T, container: ServiceContainer): T;
+/**
+ * 为实例注入属性依赖
+ *
+ * @param instance 目标实例
+ * @param container 服务容器
+ */
+declare function injectProperties<T extends object>(instance: T, container: ServiceContainer): void;
 /**
  * 检查类是否标记为可更新
  *
@@ -11253,5 +11265,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, BinarySerializer, 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 { BinarySerializer, 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, IdentifierPool, IgnoreSerialization, IncrementalSerializer, InjectProperty, 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, 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, getPropertyInjectMetadata, getSceneByEntityId, getSerializationMetadata, getSystemInstanceTypeName, getSystemMetadata, getSystemTypeName, getUpdatableMetadata, hasAdapter, hasAnyComponent, hasComponents, hasEntityRef, 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, 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 };