@esengine/ecs-framework 2.2.12 → 2.2.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @esengine/ecs-framework v2.2.12
2
+ * @esengine/ecs-framework v2.2.14
3
3
  * TypeScript definitions
4
4
  */
5
5
  /**
@@ -919,16 +919,16 @@ declare class BitMask64Utils {
919
919
  private static getSegmentByBitIndex;
920
920
  }
921
921
 
922
+ /**
923
+ * SoA存储器支持的TypedArray类型
924
+ */
925
+ type SupportedTypedArray = Float32Array | Float64Array | Int32Array | Uint32Array | Int16Array | Uint16Array | Int8Array | Uint8Array | Uint8ClampedArray;
926
+
922
927
  /**
923
928
  * 启用SoA优化装饰器
924
929
  * 默认关闭SoA,只有在大规模批量操作场景下才建议开启
925
930
  */
926
931
  declare function EnableSoA<T extends ComponentType>(target: T): T;
927
- /**
928
- * 高精度数值装饰器
929
- * 标记字段需要保持完整精度,存储为复杂对象而非TypedArray
930
- */
931
- declare function HighPrecision(target: any, propertyKey: string | symbol): void;
932
932
  /**
933
933
  * 64位浮点数装饰器
934
934
  * 标记字段使用Float64Array存储(更高精度但更多内存)
@@ -994,51 +994,11 @@ declare function SerializeArray(target: any, propertyKey: string | symbol): void
994
994
  * 标记字段需要深拷贝处理(适用于嵌套对象)
995
995
  */
996
996
  declare function DeepCopy(target: any, propertyKey: string | symbol): void;
997
- /**
998
- * 自动类型推断装饰器
999
- * 根据字段的默认值和数值范围自动选择最优的TypedArray类型
1000
- *
1001
- * @param options 类型推断选项
1002
- * @param options.minValue 数值的最小值(用于范围优化)
1003
- * @param options.maxValue 数值的最大值(用于范围优化)
1004
- * @param options.precision 是否需要浮点精度(true: 使用浮点数组, false: 使用整数数组)
1005
- * @param options.signed 是否需要符号位(仅在整数模式下有效)
1006
- */
1007
- declare function AutoTyped(options?: {
1008
- minValue?: number;
1009
- maxValue?: number;
1010
- precision?: boolean;
1011
- signed?: boolean;
1012
- }): (target: any, propertyKey: string | symbol) => void;
1013
- /**
1014
- * 自动类型推断器
1015
- * 根据数值类型和范围自动选择最优的TypedArray类型
1016
- */
1017
- declare class TypeInference {
1018
- /**
1019
- * 根据数值范围推断最优的TypedArray类型
1020
- */
1021
- static inferOptimalType(value: any, options?: {
1022
- minValue?: number;
1023
- maxValue?: number;
1024
- precision?: boolean;
1025
- signed?: boolean;
1026
- }): string;
1027
- /**
1028
- * 根据推断的类型名创建对应的TypedArray构造函数
1029
- */
1030
- static getTypedArrayConstructor(typeName: string): typeof Float32Array | typeof Float64Array | typeof Int32Array | typeof Uint32Array | typeof Int16Array | typeof Uint16Array | typeof Int8Array | typeof Uint8Array | typeof Uint8ClampedArray;
1031
- }
1032
- /**
1033
- * SoA存储器支持的TypedArray类型
1034
- */
1035
- type SupportedTypedArray = Float32Array | Float64Array | Int32Array | Uint32Array | Int16Array | Uint16Array | Int8Array | Uint8Array | Uint8ClampedArray;
1036
997
  /**
1037
998
  * SoA存储器(需要装饰器启用)
1038
999
  * 使用Structure of Arrays存储模式,在大规模批量操作时提供优异性能
1039
1000
  */
1040
1001
  declare class SoAStorage<T extends Component> {
1041
- private static readonly _logger;
1042
1002
  private fields;
1043
1003
  private stringFields;
1044
1004
  private serializedFields;
@@ -1049,23 +1009,24 @@ declare class SoAStorage<T extends Component> {
1049
1009
  private _size;
1050
1010
  private _capacity;
1051
1011
  readonly type: ComponentType<T>;
1012
+ private fieldTypes;
1013
+ private serializeMapFields;
1014
+ private serializeSetFields;
1015
+ private serializeArrayFields;
1052
1016
  constructor(componentType: ComponentType<T>);
1053
1017
  private initializeFields;
1054
1018
  addComponent(entityId: number, component: T): void;
1055
1019
  private updateComponentAtIndex;
1020
+ getComponent(entityId: number): T | null;
1056
1021
  /**
1057
- * 序列化值为JSON字符串
1058
- */
1059
- private serializeValue;
1060
- /**
1061
- * 反序列化JSON字符串为值
1022
+ * 创建组件的 Proxy 视图
1023
+ * 读写操作直接映射到底层 TypedArray,无数据复制
1062
1024
  */
1063
- private deserializeValue;
1025
+ private createProxyView;
1064
1026
  /**
1065
- * 深拷贝对象
1027
+ * 获取组件的快照副本(用于序列化等需要独立副本的场景)
1066
1028
  */
1067
- private deepClone;
1068
- getComponent(entityId: number): T | null;
1029
+ getComponentSnapshot(entityId: number): T | null;
1069
1030
  private getFieldType;
1070
1031
  hasComponent(entityId: number): boolean;
1071
1032
  removeComponent(entityId: number): T | null;
@@ -1286,6 +1247,9 @@ declare class LoggerManager {
1286
1247
  /**
1287
1248
  * 设置日志器工厂方法
1288
1249
  * @param factory 日志器工厂方法
1250
+ *
1251
+ * 注意: 应该在导入 ECS 模块之前调用此方法。
1252
+ * 设置后, 每次调用 getLogger() 都会通过 factory 创建新的 logger 实例, 由用户侧管理
1289
1253
  */
1290
1254
  setLoggerFactory(factory: (name?: string) => ILogger): void;
1291
1255
  }
@@ -5037,7 +5001,7 @@ declare class Scene implements IScene {
5037
5001
  *
5038
5002
  * 从 ServiceContainer 获取,如果未注册则创建默认实例(向后兼容)
5039
5003
  */
5040
- private get performanceMonitor();
5004
+ get performanceMonitor(): PerformanceMonitor;
5041
5005
  /**
5042
5006
  * 初始化场景
5043
5007
  *
@@ -5066,6 +5030,16 @@ declare class Scene implements IScene {
5066
5030
  * 结束场景,清除实体、实体处理器等
5067
5031
  *
5068
5032
  * 这个方法会结束场景。它将移除所有实体,结束实体处理器等,并调用unload方法。
5033
+ *
5034
+ * 执行顺序:
5035
+ * 1. 调用 unload() - 用户可以在此访问实体和系统进行清理
5036
+ * 2. 清理所有实体
5037
+ * 3. 清空服务容器,触发所有系统的 onDestroy()
5038
+ *
5039
+ * 注意:
5040
+ * - onRemoved 回调不会在 Scene.end() 时触发,因为这是批量销毁场景
5041
+ * - 用户清理:在 Scene.unload() 中处理(可访问实体和系统)
5042
+ * - 系统清理:在 System.onDestroy() 中处理(实体已被清理)
5069
5043
  */
5070
5044
  end(): void;
5071
5045
  /**
@@ -5204,7 +5178,7 @@ declare class Scene implements IScene {
5204
5178
  * 在场景中添加一个EntitySystem处理器
5205
5179
  *
5206
5180
  * 支持两种使用方式:
5207
- * 1. 传入类型(推荐):自动使用DI创建实例,支持@Injectable和@Inject装饰器
5181
+ * 1. 传入类型(推荐):自动使用DI创建实例,支持@Injectable和@InjectProperty装饰器
5208
5182
  * 2. 传入实例:直接使用提供的实例
5209
5183
  *
5210
5184
  * @param systemTypeOrInstance 系统类型或系统实例
@@ -5215,7 +5189,10 @@ declare class Scene implements IScene {
5215
5189
  * // 方式1:传入类型,自动DI(推荐)
5216
5190
  * @Injectable()
5217
5191
  * class PhysicsSystem extends EntitySystem {
5218
- * constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
5192
+ * @InjectProperty(CollisionSystem)
5193
+ * private collision!: CollisionSystem;
5194
+ *
5195
+ * constructor() {
5219
5196
  * super(Matcher.empty().all(Transform));
5220
5197
  * }
5221
5198
  * }
@@ -5248,7 +5225,10 @@ declare class Scene implements IScene {
5248
5225
  * @Injectable()
5249
5226
  * @ECSSystem('Physics', { updateOrder: 10 })
5250
5227
  * class PhysicsSystem extends EntitySystem implements IService {
5251
- * constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
5228
+ * @InjectProperty(CollisionSystem)
5229
+ * private collision!: CollisionSystem;
5230
+ *
5231
+ * constructor() {
5252
5232
  * super(Matcher.empty().all(Transform, RigidBody));
5253
5233
  * }
5254
5234
  * dispose() {}
@@ -5281,7 +5261,7 @@ declare class Scene implements IScene {
5281
5261
  /**
5282
5262
  * 获取指定类型的EntitySystem处理器
5283
5263
  *
5284
- * @deprecated 推荐使用依赖注入代替此方法。使用 `scene.services.resolve(SystemType)` 或在System构造函数中使用 `@Inject(SystemType)` 装饰器。
5264
+ * @deprecated 推荐使用依赖注入代替此方法。使用 `scene.services.resolve(SystemType)` 或使用 `@InjectProperty(SystemType)` 装饰器。
5285
5265
  *
5286
5266
  * @param type 处理器类型
5287
5267
  * @returns 处理器实例,如果未找到则返回null
@@ -5290,8 +5270,11 @@ declare class Scene implements IScene {
5290
5270
  * ```typescript
5291
5271
  * @Injectable()
5292
5272
  * class MySystem extends EntitySystem {
5293
- * constructor(@Inject(PhysicsSystem) private physics: PhysicsSystem) {
5294
- * super();
5273
+ * @InjectProperty(PhysicsSystem)
5274
+ * private physics!: PhysicsSystem;
5275
+ *
5276
+ * constructor() {
5277
+ * super(Matcher.empty());
5295
5278
  * }
5296
5279
  * }
5297
5280
  * ```
@@ -5539,6 +5522,7 @@ declare abstract class EntitySystem implements ISystemBase, IService {
5539
5522
  private _matcher;
5540
5523
  private _eventListeners;
5541
5524
  private _scene;
5525
+ private _destroyed;
5542
5526
  protected logger: ReturnType<typeof createLogger>;
5543
5527
  /**
5544
5528
  * 实体ID映射缓存
@@ -5614,6 +5598,10 @@ declare abstract class EntitySystem implements ISystemBase, IService {
5614
5598
  * 重置系统状态
5615
5599
  *
5616
5600
  * 当系统从场景中移除时调用,重置初始化状态以便重新添加时能正确初始化。
5601
+ *
5602
+ * 注意:此方法由 Scene.removeEntityProcessor 调用,在 unregister(触发dispose)之后调用。
5603
+ * dispose 已经调用了 onDestroy 并设置了 _destroyed 标志,所以这里不需要重置该标志。
5604
+ * 重置 _destroyed 会违反服务容器的语义(dispose 后不应重用)。
5617
5605
  */
5618
5606
  reset(): void;
5619
5607
  /**
@@ -5765,6 +5753,7 @@ declare abstract class EntitySystem implements ISystemBase, IService {
5765
5753
  *
5766
5754
  * 默认行为:
5767
5755
  * - 移除所有事件监听器
5756
+ * - 调用 onDestroy 回调(仅首次)
5768
5757
  * - 清空所有缓存
5769
5758
  * - 重置初始化状态
5770
5759
  *
@@ -7256,11 +7245,14 @@ interface SystemMetadata {
7256
7245
  * }
7257
7246
  * }
7258
7247
  *
7259
- * // 配置更新顺序
7248
+ * // 配置更新顺序和依赖注入
7260
7249
  * @Injectable()
7261
7250
  * @ECSSystem('Physics', { updateOrder: 10 })
7262
7251
  * class PhysicsSystem extends EntitySystem {
7263
- * constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
7252
+ * @InjectProperty(CollisionSystem)
7253
+ * private collision!: CollisionSystem;
7254
+ *
7255
+ * constructor() {
7264
7256
  * super(Matcher.empty().all(Transform, RigidBody));
7265
7257
  * }
7266
7258
  * }
@@ -7937,6 +7929,13 @@ interface IWorldConfig {
7937
7929
  * World类 - ECS世界管理器
7938
7930
  *
7939
7931
  * World是Scene的容器,每个World可以管理多个Scene。
7932
+ * World拥有独立的服务容器,用于管理World级别的全局服务。
7933
+ *
7934
+ * 服务容器层级:
7935
+ * - Core.services: 应用程序全局服务
7936
+ * - World.services: World级别服务(每个World独立)
7937
+ * - Scene.services: Scene级别服务(每个Scene独立)
7938
+ *
7940
7939
  * 这种设计允许创建独立的游戏世界,如:
7941
7940
  * - 游戏房间(每个房间一个World)
7942
7941
  * - 不同的游戏模式
@@ -7947,10 +7946,16 @@ interface IWorldConfig {
7947
7946
  * // 创建游戏房间的World
7948
7947
  * const roomWorld = new World({ name: 'Room_001' });
7949
7948
  *
7949
+ * // 注册World级别的服务
7950
+ * roomWorld.services.registerSingleton(RoomManager);
7951
+ *
7950
7952
  * // 在World中创建Scene
7951
7953
  * const gameScene = roomWorld.createScene('game', new Scene());
7952
7954
  * const uiScene = roomWorld.createScene('ui', new Scene());
7953
7955
  *
7956
+ * // 在Scene中使用World级别的服务
7957
+ * const roomManager = roomWorld.services.resolve(RoomManager);
7958
+ *
7954
7959
  * // 更新整个World
7955
7960
  * roomWorld.update(deltaTime);
7956
7961
  * ```
@@ -7961,21 +7966,27 @@ declare class World {
7961
7966
  private readonly _scenes;
7962
7967
  private readonly _activeScenes;
7963
7968
  private readonly _globalSystems;
7969
+ private readonly _services;
7964
7970
  private _isActive;
7965
7971
  private _createdAt;
7966
7972
  constructor(config?: IWorldConfig);
7973
+ /**
7974
+ * World级别的服务容器
7975
+ * 用于管理World范围内的全局服务
7976
+ */
7977
+ get services(): ServiceContainer;
7967
7978
  /**
7968
7979
  * 创建并添加Scene到World
7969
7980
  */
7970
- createScene<T extends IScene>(sceneId: string, sceneInstance?: T): T;
7981
+ createScene<T extends IScene>(sceneName: string, sceneInstance?: T): T;
7971
7982
  /**
7972
7983
  * 移除Scene
7973
7984
  */
7974
- removeScene(sceneId: string): boolean;
7985
+ removeScene(sceneName: string): boolean;
7975
7986
  /**
7976
7987
  * 获取Scene
7977
7988
  */
7978
- getScene<T extends IScene>(sceneId: string): T | null;
7989
+ getScene<T extends IScene>(sceneName: string): T | null;
7979
7990
  /**
7980
7991
  * 获取所有Scene ID
7981
7992
  */
@@ -7991,11 +8002,11 @@ declare class World {
7991
8002
  /**
7992
8003
  * 设置Scene激活状态
7993
8004
  */
7994
- setSceneActive(sceneId: string, active: boolean): void;
8005
+ setSceneActive(sceneName: string, active: boolean): void;
7995
8006
  /**
7996
8007
  * 检查Scene是否激活
7997
8008
  */
7998
- isSceneActive(sceneId: string): boolean;
8009
+ isSceneActive(sceneName: string): boolean;
7999
8010
  /**
8000
8011
  * 获取活跃Scene数量
8001
8012
  */
@@ -8116,9 +8127,9 @@ interface IWorldManagerConfig {
8116
8127
  */
8117
8128
  autoCleanup?: boolean;
8118
8129
  /**
8119
- * 清理间隔(毫秒)
8130
+ * 清理间隔(帧数)
8120
8131
  */
8121
- cleanupInterval?: number;
8132
+ cleanupFrameInterval?: number;
8122
8133
  /**
8123
8134
  * 是否启用调试模式
8124
8135
  */
@@ -8160,22 +8171,21 @@ interface IWorldManagerConfig {
8160
8171
  declare class WorldManager implements IService {
8161
8172
  private readonly _config;
8162
8173
  private readonly _worlds;
8163
- private readonly _activeWorlds;
8164
- private _cleanupTimer;
8165
8174
  private _isRunning;
8175
+ private _framesSinceCleanup;
8166
8176
  constructor(config?: IWorldManagerConfig);
8167
8177
  /**
8168
8178
  * 创建新World
8169
8179
  */
8170
- createWorld(worldId: string, config?: IWorldConfig): World;
8180
+ createWorld(worldName: string, config?: IWorldConfig): World;
8171
8181
  /**
8172
8182
  * 移除World
8173
8183
  */
8174
- removeWorld(worldId: string): boolean;
8184
+ removeWorld(worldName: string): boolean;
8175
8185
  /**
8176
8186
  * 获取World
8177
8187
  */
8178
- getWorld(worldId: string): World | null;
8188
+ getWorld(worldName: string): World | null;
8179
8189
  /**
8180
8190
  * 获取所有World ID
8181
8191
  */
@@ -8187,11 +8197,11 @@ declare class WorldManager implements IService {
8187
8197
  /**
8188
8198
  * 设置World激活状态
8189
8199
  */
8190
- setWorldActive(worldId: string, active: boolean): void;
8200
+ setWorldActive(worldName: string, active: boolean): void;
8191
8201
  /**
8192
8202
  * 检查World是否激活
8193
8203
  */
8194
- isWorldActive(worldId: string): boolean;
8204
+ isWorldActive(worldName: string): boolean;
8195
8205
  /**
8196
8206
  * 更新所有活跃的World
8197
8207
  *
@@ -8239,22 +8249,10 @@ declare class WorldManager implements IService {
8239
8249
  memoryUsage: number;
8240
8250
  isRunning: boolean;
8241
8251
  config: {
8242
- /**
8243
- * 最大World数量
8244
- */
8245
- maxWorlds?: number;
8246
- /**
8247
- * 是否自动清理空World
8248
- */
8249
- autoCleanup?: boolean;
8250
- /**
8251
- * 清理间隔(毫秒)
8252
- */
8253
- cleanupInterval?: number;
8254
- /**
8255
- * 是否启用调试模式
8256
- */
8257
- debug?: boolean;
8252
+ maxWorlds: number;
8253
+ autoCleanup: boolean;
8254
+ cleanupFrameInterval: number;
8255
+ debug: boolean;
8258
8256
  };
8259
8257
  worlds: any[];
8260
8258
  };
@@ -8293,22 +8291,10 @@ declare class WorldManager implements IService {
8293
8291
  memoryUsage: number;
8294
8292
  isRunning: boolean;
8295
8293
  config: {
8296
- /**
8297
- * 最大World数量
8298
- */
8299
- maxWorlds?: number;
8300
- /**
8301
- * 是否自动清理空World
8302
- */
8303
- autoCleanup?: boolean;
8304
- /**
8305
- * 清理间隔(毫秒)
8306
- */
8307
- cleanupInterval?: number;
8308
- /**
8309
- * 是否启用调试模式
8310
- */
8311
- debug?: boolean;
8294
+ maxWorlds: number;
8295
+ autoCleanup: boolean;
8296
+ cleanupFrameInterval: number;
8297
+ debug: boolean;
8312
8298
  };
8313
8299
  };
8314
8300
  /**
@@ -8324,16 +8310,12 @@ declare class WorldManager implements IService {
8324
8310
  * 调用 destroy 方法进行清理
8325
8311
  */
8326
8312
  dispose(): void;
8327
- /**
8328
- * 启动清理定时器
8329
- */
8330
- private startCleanupTimer;
8331
- /**
8332
- * 停止清理定时器
8333
- */
8334
- private stopCleanupTimer;
8335
8313
  /**
8336
8314
  * 判断World是否应该被清理
8315
+ * 清理策略:
8316
+ * 1. World未激活
8317
+ * 2. 没有Scene或所有Scene都是空的
8318
+ * 3. 创建时间超过10分钟
8337
8319
  */
8338
8320
  private shouldCleanupWorld;
8339
8321
  /**
@@ -9542,20 +9524,6 @@ declare class WebSocketManager {
9542
9524
  private handleConnectionFailure;
9543
9525
  }
9544
9526
 
9545
- /**
9546
- * 调试配置服务
9547
- *
9548
- * 管理调试系统的配置信息
9549
- */
9550
- declare class DebugConfigService implements IService {
9551
- private _config;
9552
- constructor();
9553
- setConfig(config: IECSDebugConfig): void;
9554
- getConfig(): IECSDebugConfig;
9555
- isEnabled(): boolean;
9556
- dispose(): void;
9557
- }
9558
-
9559
9527
  /**
9560
9528
  * 调试管理器
9561
9529
  *
@@ -9571,12 +9539,13 @@ declare class DebugManager implements IService, IUpdatable {
9571
9539
  private sceneCollector;
9572
9540
  private sceneManager;
9573
9541
  private performanceMonitor;
9542
+ private configService;
9574
9543
  private frameCounter;
9575
9544
  private lastSendTime;
9576
9545
  private sendInterval;
9577
9546
  private isRunning;
9578
9547
  private originalConsole;
9579
- constructor(sceneManager: SceneManager, performanceMonitor: PerformanceMonitor, configService: DebugConfigService);
9548
+ onInitialize(): void;
9580
9549
  /**
9581
9550
  * 启动调试管理器
9582
9551
  */
@@ -9674,6 +9643,20 @@ declare class DebugManager implements IService, IUpdatable {
9674
9643
  dispose(): void;
9675
9644
  }
9676
9645
 
9646
+ /**
9647
+ * 调试配置服务
9648
+ *
9649
+ * 管理调试系统的配置信息
9650
+ */
9651
+ declare class DebugConfigService implements IService {
9652
+ private _config;
9653
+ constructor();
9654
+ setConfig(config: IECSDebugConfig): void;
9655
+ getConfig(): IECSDebugConfig;
9656
+ isEnabled(): boolean;
9657
+ dispose(): void;
9658
+ }
9659
+
9677
9660
  /**
9678
9661
  * 插件状态
9679
9662
  */
@@ -10425,7 +10408,7 @@ declare class DebugPlugin implements IPlugin, IService {
10425
10408
  * @param filter - 查询过滤器
10426
10409
  */
10427
10410
  queryEntities(filter: {
10428
- sceneId?: string;
10411
+ sceneName?: string;
10429
10412
  tag?: number;
10430
10413
  name?: string;
10431
10414
  hasComponent?: string;
@@ -10443,7 +10426,7 @@ declare class DebugPlugin implements IPlugin, IService {
10443
10426
  /**
10444
10427
  * 依赖注入装饰器
10445
10428
  *
10446
- * 提供 @Injectable、@Inject 和 @Updatable 装饰器,用于标记可注入的类和依赖注入点
10429
+ * 提供 @Injectable、@InjectProperty 和 @Updatable 装饰器,用于标记可注入的类和依赖注入点
10447
10430
  */
10448
10431
 
10449
10432
  /**
@@ -10496,10 +10479,11 @@ interface UpdatableMetadata {
10496
10479
  *
10497
10480
  * @Injectable()
10498
10481
  * class PhysicsSystem extends EntitySystem {
10499
- * constructor(
10500
- * @Inject(TimeService) private timeService: TimeService
10501
- * ) {
10502
- * super();
10482
+ * @InjectProperty(TimeService)
10483
+ * private timeService!: TimeService;
10484
+ *
10485
+ * constructor() {
10486
+ * super(Matcher.empty());
10503
10487
  * }
10504
10488
  * }
10505
10489
  * ```
@@ -10536,13 +10520,43 @@ declare function Injectable(): ClassDecorator;
10536
10520
  */
10537
10521
  declare function Updatable(priority?: number): ClassDecorator;
10538
10522
  /**
10539
- * @Inject() 装饰器
10523
+ * @InjectProperty() 装饰器
10540
10524
  *
10541
- * 标记构造函数参数需要注入的服务类型
10525
+ * 通过属性装饰器注入依赖
10526
+ *
10527
+ * 注入时机:在构造函数执行后、onInitialize() 调用前完成
10528
+ *
10529
+ * @param serviceType 服务类型
10530
+ *
10531
+ * @example
10532
+ * ```typescript
10533
+ * @Injectable()
10534
+ * class PhysicsSystem extends EntitySystem {
10535
+ * @InjectProperty(TimeService)
10536
+ * private timeService!: TimeService;
10542
10537
  *
10543
- * @param serviceType 服务类型标识符
10538
+ * @InjectProperty(CollisionService)
10539
+ * private collision!: CollisionService;
10540
+ *
10541
+ * constructor() {
10542
+ * super(Matcher.empty());
10543
+ * }
10544
+ *
10545
+ * public onInitialize(): void {
10546
+ * // 此时属性已注入完成,可以安全使用
10547
+ * console.log(this.timeService.getDeltaTime());
10548
+ * }
10549
+ * }
10550
+ * ```
10544
10551
  */
10545
- declare function Inject(serviceType: ServiceType<IService> | string | symbol): ParameterDecorator;
10552
+ declare function InjectProperty(serviceType: ServiceType<IService>): PropertyDecorator;
10553
+ /**
10554
+ * 获取属性注入元数据
10555
+ *
10556
+ * @param target 目标类
10557
+ * @returns 属性名到服务类型的映射
10558
+ */
10559
+ declare function getPropertyInjectMetadata(target: Constructor): Map<string | symbol, ServiceType<IService>>;
10546
10560
  /**
10547
10561
  * 创建实例并自动注入依赖
10548
10562
  *
@@ -10556,6 +10570,13 @@ declare function Inject(serviceType: ServiceType<IService> | string | symbol): P
10556
10570
  * ```
10557
10571
  */
10558
10572
  declare function createInstance<T>(constructor: new (...args: any[]) => T, container: ServiceContainer): T;
10573
+ /**
10574
+ * 为实例注入属性依赖
10575
+ *
10576
+ * @param instance 目标实例
10577
+ * @param container 服务容器
10578
+ */
10579
+ declare function injectProperties<T extends object>(instance: T, container: ServiceContainer): void;
10559
10580
  /**
10560
10581
  * 检查类是否标记为可更新
10561
10582
  *
@@ -11244,5 +11265,5 @@ declare function getFullPlatformConfig(): Promise<any>;
11244
11265
  declare function supportsFeature(feature: 'worker' | 'shared-array-buffer' | 'transferable-objects' | 'module-worker'): boolean;
11245
11266
  declare function hasAdapter(): boolean;
11246
11267
 
11247
- 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 };
11268
+ 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 };
11248
11269
  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 };