@esengine/ecs-framework 2.2.14 → 2.2.16

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.14
+ * @esengine/ecs-framework v2.2.16
  * TypeScript definitions
  */
 /**
@@ -251,6 +251,8 @@ interface IComponent {
     onAddedToEntity(): void;
     /** 组件从实体移除时的回调 */
     onRemovedFromEntity(): void;
+    /** 组件反序列化后的回调 */
+    onDeserialized(): void | Promise<void>;
 }
 /**
  * 系统基础接口
@@ -692,8 +694,6 @@ interface ISceneDebugData {
     sceneEntityCount: number;
     /** 场景系统数 */
     sceneSystemCount: number;
-    /** 场景内存使用量 */
-    sceneMemory: number;
     /** 场景启动时间 */
     sceneUptime: number;
 }
@@ -773,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>;
 }
 
 /**
@@ -1658,6 +1684,12 @@ declare class EntityList {
      * @param isAdd 是否为添加操作
      */
     private updateNameIndex;
+    /**
+     * 重新排序实体
+     * @param entityId 要移动的实体ID
+     * @param newIndex 新的索引位置
+     */
+    reorderEntity(entityId: number, newIndex: number): void;
     /**
      * 获取实体列表的统计信息
      * @returns 统计信息
@@ -1892,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;
 /**
  * 服务生命周期
  */
@@ -1988,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
@@ -2027,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装饰器标记的服务
      *
@@ -2288,6 +2333,7 @@ interface QueryCondition$1 {
     tag?: number;
     name?: string;
     component?: ComponentType;
+    matchNothing?: boolean;
 }
 /**
  * 实体匹配条件描述符
@@ -2345,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 组件类型
@@ -2403,8 +2472,13 @@ declare class Matcher {
     getCondition(): Readonly<QueryCondition$1>;
     /**
      * 检查是否为空条件
+     * 注意：matchNothing 不算空条件，因为它是明确的"不匹配任何实体"语义
      */
     isEmpty(): boolean;
+    /**
+     * 检查是否为"不匹配任何实体"的匹配器
+     */
+    isNothing(): boolean;
     /**
      * 重置所有条件
      */
@@ -4509,6 +4583,10 @@ declare class SceneSerializer {
      * @param options 反序列化选项
      */
     static deserialize(scene: IScene, saveData: string | Uint8Array, options?: SceneDeserializationOptions): void;
+    /**
+     * 递归调用实体及其子实体所有组件的 onDeserialized 方法
+     */
+    private static callOnDeserializedRecursively;
     /**
      * 递归添加实体的所有子实体到场景
      *
@@ -7197,15 +7275,27 @@ declare abstract class WorkerEntitySystem<TEntityData = any> extends EntitySyste
  * 存储组件类型名称的Symbol键
  */
 declare const COMPONENT_TYPE_NAME: unique symbol;
+/**
+ * 存储组件依赖的Symbol键
+ */
+declare const COMPONENT_DEPENDENCIES: unique symbol;
 /**
  * 存储系统类型名称的Symbol键
  */
 declare const SYSTEM_TYPE_NAME: unique symbol;
+/**
+ * 组件装饰器配置选项
+ */
+interface ComponentOptions {
+    /** 依赖的其他组件名称列表 */
+    requires?: string[];
+}
 /**
  * 组件类型装饰器
  * 用于为组件类指定固定的类型名称，避免在代码混淆后失效
  *
  * @param typeName 组件类型名称
+ * @param options 组件配置选项
  * @example
  * ```typescript
  * @ECSComponent('Position')
@@ -7213,9 +7303,19 @@ declare const SYSTEM_TYPE_NAME: unique symbol;
  *     x: number = 0;
  *     y: number = 0;
  * }
+ *
+ * // 带依赖声明
+ * @ECSComponent('SpriteAnimator', { requires: ['Sprite'] })
+ * class SpriteAnimatorComponent extends Component {
+ *     // ...
+ * }
  * ```
  */
-declare function ECSComponent(typeName: string): <T extends new (...args: any[]) => Component>(target: T) => T;
+declare function ECSComponent(typeName: string, options?: ComponentOptions): <T extends new (...args: any[]) => Component>(target: T) => T;
+/**
+ * 获取组件的依赖列表
+ */
+declare function getComponentDependencies(componentType: ComponentType$1): string[] | undefined;
 /**
  * System元数据配置
  */
@@ -7338,6 +7438,649 @@ declare function getEntityRefMetadata(component: any): EntityRefMetadata | null;
  */
 declare function hasEntityRef(component: any): boolean;
 
+/*! *****************************************************************************
+Copyright (C) Microsoft. All rights reserved.
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE-2.0
+
+THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
+WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
+MERCHANTABLITY OR NON-INFRINGEMENT.
+
+See the Apache Version 2.0 License for specific language governing permissions
+and limitations under the License.
+***************************************************************************** */
+
+
+
+declare global {
+    namespace Reflect {
+        /**
+          * Applies a set of decorators to a target object.
+          * @param decorators An array of decorators.
+          * @param target The target object.
+          * @returns The result of applying the provided decorators.
+          * @remarks Decorators are applied in reverse order of their positions in the array.
+          * @example
+          *
+          *     class Example { }
+          *
+          *     // constructor
+          *     Example = Reflect.decorate(decoratorsArray, Example);
+          *
+          */
+        function decorate(decorators: ClassDecorator[], target: Function): Function;
+        /**
+          * Applies a set of decorators to a property of a target object.
+          * @param decorators An array of decorators.
+          * @param target The target object.
+          * @param propertyKey The property key to decorate.
+          * @param attributes A property descriptor.
+          * @remarks Decorators are applied in reverse order.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod() { }
+          *         method() { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     Reflect.decorate(decoratorsArray, Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     Reflect.decorate(decoratorsArray, Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     Object.defineProperty(Example, "staticMethod",
+          *         Reflect.decorate(decoratorsArray, Example, "staticMethod",
+          *             Object.getOwnPropertyDescriptor(Example, "staticMethod")));
+          *
+          *     // method (on prototype)
+          *     Object.defineProperty(Example.prototype, "method",
+          *         Reflect.decorate(decoratorsArray, Example.prototype, "method",
+          *             Object.getOwnPropertyDescriptor(Example.prototype, "method")));
+          *
+          */
+        function decorate(decorators: (PropertyDecorator | MethodDecorator)[], target: Object, propertyKey: string | symbol, attributes?: PropertyDescriptor): PropertyDescriptor;
+        /**
+          * A default metadata decorator factory that can be used on a class, class member, or parameter.
+          * @param metadataKey The key for the metadata entry.
+          * @param metadataValue The value for the metadata entry.
+          * @returns A decorator function.
+          * @remarks
+          * If `metadataKey` is already defined for the target and target key, the
+          * metadataValue for that key will be overwritten.
+          * @example
+          *
+          *     // constructor
+          *     @Reflect.metadata(key, value)
+          *     class Example {
+          *     }
+          *
+          *     // property (on constructor, TypeScript only)
+          *     class Example {
+          *         @Reflect.metadata(key, value)
+          *         static staticProperty;
+          *     }
+          *
+          *     // property (on prototype, TypeScript only)
+          *     class Example {
+          *         @Reflect.metadata(key, value)
+          *         property;
+          *     }
+          *
+          *     // method (on constructor)
+          *     class Example {
+          *         @Reflect.metadata(key, value)
+          *         static staticMethod() { }
+          *     }
+          *
+          *     // method (on prototype)
+          *     class Example {
+          *         @Reflect.metadata(key, value)
+          *         method() { }
+          *     }
+          *
+          */
+        function metadata(metadataKey: any, metadataValue: any): {
+            (target: Function): void;
+            (target: Object, propertyKey: string | symbol): void;
+        };
+        /**
+          * Define a unique metadata entry on the target.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param metadataValue A value that contains attached metadata.
+          * @param target The target object on which to define metadata.
+          * @example
+          *
+          *     class Example {
+          *     }
+          *
+          *     // constructor
+          *     Reflect.defineMetadata("custom:annotation", options, Example);
+          *
+          *     // decorator factory as metadata-producing annotation.
+          *     function MyAnnotation(options): ClassDecorator {
+          *         return target => Reflect.defineMetadata("custom:annotation", options, target);
+          *     }
+          *
+          */
+        function defineMetadata(metadataKey: any, metadataValue: any, target: Object): void;
+        /**
+          * Define a unique metadata entry on the target.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param metadataValue A value that contains attached metadata.
+          * @param target The target object on which to define metadata.
+          * @param propertyKey The property key for the target.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod(p) { }
+          *         method(p) { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     Reflect.defineMetadata("custom:annotation", Number, Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     Reflect.defineMetadata("custom:annotation", Number, Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     Reflect.defineMetadata("custom:annotation", Number, Example, "staticMethod");
+          *
+          *     // method (on prototype)
+          *     Reflect.defineMetadata("custom:annotation", Number, Example.prototype, "method");
+          *
+          *     // decorator factory as metadata-producing annotation.
+          *     function MyAnnotation(options): PropertyDecorator {
+          *         return (target, key) => Reflect.defineMetadata("custom:annotation", options, target, key);
+          *     }
+          *
+          */
+        function defineMetadata(metadataKey: any, metadataValue: any, target: Object, propertyKey: string | symbol): void;
+        /**
+          * Gets a value indicating whether the target object or its prototype chain has the provided metadata key defined.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @returns `true` if the metadata key was defined on the target object or its prototype chain; otherwise, `false`.
+          * @example
+          *
+          *     class Example {
+          *     }
+          *
+          *     // constructor
+          *     result = Reflect.hasMetadata("custom:annotation", Example);
+          *
+          */
+        function hasMetadata(metadataKey: any, target: Object): boolean;
+        /**
+          * Gets a value indicating whether the target object or its prototype chain has the provided metadata key defined.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @param propertyKey The property key for the target.
+          * @returns `true` if the metadata key was defined on the target object or its prototype chain; otherwise, `false`.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod(p) { }
+          *         method(p) { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     result = Reflect.hasMetadata("custom:annotation", Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     result = Reflect.hasMetadata("custom:annotation", Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     result = Reflect.hasMetadata("custom:annotation", Example, "staticMethod");
+          *
+          *     // method (on prototype)
+          *     result = Reflect.hasMetadata("custom:annotation", Example.prototype, "method");
+          *
+          */
+        function hasMetadata(metadataKey: any, target: Object, propertyKey: string | symbol): boolean;
+        /**
+          * Gets a value indicating whether the target object has the provided metadata key defined.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @returns `true` if the metadata key was defined on the target object; otherwise, `false`.
+          * @example
+          *
+          *     class Example {
+          *     }
+          *
+          *     // constructor
+          *     result = Reflect.hasOwnMetadata("custom:annotation", Example);
+          *
+          */
+        function hasOwnMetadata(metadataKey: any, target: Object): boolean;
+        /**
+          * Gets a value indicating whether the target object has the provided metadata key defined.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @param propertyKey The property key for the target.
+          * @returns `true` if the metadata key was defined on the target object; otherwise, `false`.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod(p) { }
+          *         method(p) { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     result = Reflect.hasOwnMetadata("custom:annotation", Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     result = Reflect.hasOwnMetadata("custom:annotation", Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     result = Reflect.hasOwnMetadata("custom:annotation", Example, "staticMethod");
+          *
+          *     // method (on prototype)
+          *     result = Reflect.hasOwnMetadata("custom:annotation", Example.prototype, "method");
+          *
+          */
+        function hasOwnMetadata(metadataKey: any, target: Object, propertyKey: string | symbol): boolean;
+        /**
+          * Gets the metadata value for the provided metadata key on the target object or its prototype chain.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @returns The metadata value for the metadata key if found; otherwise, `undefined`.
+          * @example
+          *
+          *     class Example {
+          *     }
+          *
+          *     // constructor
+          *     result = Reflect.getMetadata("custom:annotation", Example);
+          *
+          */
+        function getMetadata(metadataKey: any, target: Object): any;
+        /**
+          * Gets the metadata value for the provided metadata key on the target object or its prototype chain.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @param propertyKey The property key for the target.
+          * @returns The metadata value for the metadata key if found; otherwise, `undefined`.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod(p) { }
+          *         method(p) { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     result = Reflect.getMetadata("custom:annotation", Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     result = Reflect.getMetadata("custom:annotation", Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     result = Reflect.getMetadata("custom:annotation", Example, "staticMethod");
+          *
+          *     // method (on prototype)
+          *     result = Reflect.getMetadata("custom:annotation", Example.prototype, "method");
+          *
+          */
+        function getMetadata(metadataKey: any, target: Object, propertyKey: string | symbol): any;
+        /**
+          * Gets the metadata value for the provided metadata key on the target object.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @returns The metadata value for the metadata key if found; otherwise, `undefined`.
+          * @example
+          *
+          *     class Example {
+          *     }
+          *
+          *     // constructor
+          *     result = Reflect.getOwnMetadata("custom:annotation", Example);
+          *
+          */
+        function getOwnMetadata(metadataKey: any, target: Object): any;
+        /**
+          * Gets the metadata value for the provided metadata key on the target object.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @param propertyKey The property key for the target.
+          * @returns The metadata value for the metadata key if found; otherwise, `undefined`.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod(p) { }
+          *         method(p) { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     result = Reflect.getOwnMetadata("custom:annotation", Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     result = Reflect.getOwnMetadata("custom:annotation", Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     result = Reflect.getOwnMetadata("custom:annotation", Example, "staticMethod");
+          *
+          *     // method (on prototype)
+          *     result = Reflect.getOwnMetadata("custom:annotation", Example.prototype, "method");
+          *
+          */
+        function getOwnMetadata(metadataKey: any, target: Object, propertyKey: string | symbol): any;
+        /**
+          * Gets the metadata keys defined on the target object or its prototype chain.
+          * @param target The target object on which the metadata is defined.
+          * @returns An array of unique metadata keys.
+          * @example
+          *
+          *     class Example {
+          *     }
+          *
+          *     // constructor
+          *     result = Reflect.getMetadataKeys(Example);
+          *
+          */
+        function getMetadataKeys(target: Object): any[];
+        /**
+          * Gets the metadata keys defined on the target object or its prototype chain.
+          * @param target The target object on which the metadata is defined.
+          * @param propertyKey The property key for the target.
+          * @returns An array of unique metadata keys.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod(p) { }
+          *         method(p) { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     result = Reflect.getMetadataKeys(Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     result = Reflect.getMetadataKeys(Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     result = Reflect.getMetadataKeys(Example, "staticMethod");
+          *
+          *     // method (on prototype)
+          *     result = Reflect.getMetadataKeys(Example.prototype, "method");
+          *
+          */
+        function getMetadataKeys(target: Object, propertyKey: string | symbol): any[];
+        /**
+          * Gets the unique metadata keys defined on the target object.
+          * @param target The target object on which the metadata is defined.
+          * @returns An array of unique metadata keys.
+          * @example
+          *
+          *     class Example {
+          *     }
+          *
+          *     // constructor
+          *     result = Reflect.getOwnMetadataKeys(Example);
+          *
+          */
+        function getOwnMetadataKeys(target: Object): any[];
+        /**
+          * Gets the unique metadata keys defined on the target object.
+          * @param target The target object on which the metadata is defined.
+          * @param propertyKey The property key for the target.
+          * @returns An array of unique metadata keys.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod(p) { }
+          *         method(p) { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     result = Reflect.getOwnMetadataKeys(Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     result = Reflect.getOwnMetadataKeys(Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     result = Reflect.getOwnMetadataKeys(Example, "staticMethod");
+          *
+          *     // method (on prototype)
+          *     result = Reflect.getOwnMetadataKeys(Example.prototype, "method");
+          *
+          */
+        function getOwnMetadataKeys(target: Object, propertyKey: string | symbol): any[];
+        /**
+          * Deletes the metadata entry from the target object with the provided key.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @returns `true` if the metadata entry was found and deleted; otherwise, false.
+          * @example
+          *
+          *     class Example {
+          *     }
+          *
+          *     // constructor
+          *     result = Reflect.deleteMetadata("custom:annotation", Example);
+          *
+          */
+        function deleteMetadata(metadataKey: any, target: Object): boolean;
+        /**
+          * Deletes the metadata entry from the target object with the provided key.
+          * @param metadataKey A key used to store and retrieve metadata.
+          * @param target The target object on which the metadata is defined.
+          * @param propertyKey The property key for the target.
+          * @returns `true` if the metadata entry was found and deleted; otherwise, false.
+          * @example
+          *
+          *     class Example {
+          *         // property declarations are not part of ES6, though they are valid in TypeScript:
+          *         // static staticProperty;
+          *         // property;
+          *
+          *         static staticMethod(p) { }
+          *         method(p) { }
+          *     }
+          *
+          *     // property (on constructor)
+          *     result = Reflect.deleteMetadata("custom:annotation", Example, "staticProperty");
+          *
+          *     // property (on prototype)
+          *     result = Reflect.deleteMetadata("custom:annotation", Example.prototype, "property");
+          *
+          *     // method (on constructor)
+          *     result = Reflect.deleteMetadata("custom:annotation", Example, "staticMethod");
+          *
+          *     // method (on prototype)
+          *     result = Reflect.deleteMetadata("custom:annotation", Example.prototype, "method");
+          *
+          */
+        function deleteMetadata(metadataKey: any, target: Object, propertyKey: string | symbol): boolean;
+    }
+}
+
+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
+ * 属性字段的操作按钮配置
+ */
+interface PropertyAction {
+    /** Action identifier | 操作标识符 */
+    id: string;
+    /** Button label | 按钮标签 */
+    label: string;
+    /** Button tooltip | 按钮提示 */
+    tooltip?: string;
+    /** Icon name from Lucide | Lucide图标名称 */
+    icon?: string;
+}
+/**
+ * 控制关系声明
+ * Control relationship declaration
+ */
+interface PropertyControl {
+    /** 被控制的组件名称 | Target component name */
+    component: string;
+    /** 被控制的属性名称 | Target property name */
+    property: string;
+}
+/**
+ * 属性基础选项
+ * Base property options shared by all types
+ */
+interface PropertyOptionsBase {
+    /** 显示标签 | Display label */
+    label?: string;
+    /** 是否只读 | Read-only flag */
+    readOnly?: boolean;
+    /** 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;
+/**
+ * 属性装饰器 - 声明组件属性的编辑器元数据
+ *
+ * @example
+ * ```typescript
+ * @ECSComponent('Transform')
+ * export class TransformComponent extends Component {
+ *     @Property({ type: 'vector3', label: 'Position' })
+ *     public position: Vector3 = { x: 0, y: 0, z: 0 };
+ *
+ *     @Property({ type: 'number', label: 'Speed', min: 0, max: 100 })
+ *     public speed: number = 10;
+ * }
+ * ```
+ */
+declare function Property(options: PropertyOptions): PropertyDecorator;
+/**
+ * 获取组件类的所有属性元数据
+ */
+declare function getPropertyMetadata(target: Function): Record<string, PropertyOptions> | undefined;
+/**
+ * 检查组件类是否有属性元数据
+ */
+declare function hasPropertyMetadata(target: Function): boolean;
+
 /**
  * 实体构建器 - 提供流式API创建和配置实体
  */
@@ -11265,5 +12008,5 @@ declare function getFullPlatformConfig(): Promise<any>;
 declare function supportsFeature(feature: 'worker' | 'shared-array-buffer' | 'transferable-objects' | 'module-worker'): boolean;
 declare function hasAdapter(): boolean;
 
-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 };
+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, 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 };