@esengine/ecs-framework 2.1.51 → 2.1.52

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.51
+ * @esengine/ecs-framework v2.1.52
  * TypeScript definitions
  */
 /**
@@ -532,9 +532,226 @@ declare class PoolManager {
     reset(): void;
 }
 
+/**
+ * TypeScript类型工具集
+ *
+ * 提供高级类型推断和类型安全的工具类型
+ */
+
+/**
+ * 组件类型提取器
+ * 从组件构造函数中提取实例类型
+ */
+type ComponentInstance<T> = T extends new (...args: any[]) => infer R ? R : never;
+/**
+ * 组件构造函数类型
+ *
+ * 与 ComponentType 保持一致，避免类型转换
+ */
+type ComponentConstructor<T extends IComponent = IComponent> = new (...args: any[]) => T;
+/**
+ * 组件类型的通用约束
+ *
+ * 用于确保类型参数是有效的组件构造函数
+ */
+type AnyComponentConstructor = ComponentConstructor<any>;
+/**
+ * 多组件类型提取
+ * 从组件构造函数数组中提取所有实例类型的联合
+ */
+type ExtractComponents<T extends readonly ComponentConstructor[]> = {
+    [K in keyof T]: ComponentInstance<T[K]>;
+};
+/**
+ * 组件类型映射
+ * 将组件构造函数数组转换为实例类型的元组
+ */
+type ComponentTypeMap<T extends readonly ComponentConstructor[]> = {
+    [K in keyof T]: T[K] extends ComponentConstructor<infer C> ? C : never;
+};
+/**
+ * 实体with组件的类型
+ * 表示一个实体确定拥有某些组件
+ */
+interface EntityWithComponents<T extends readonly ComponentConstructor[]> {
+    readonly id: number;
+    readonly name: string;
+    /**
+     * 类型安全的组件获取
+     * 确保返回非空的组件实例
+     */
+    getComponent<C extends ComponentConstructor>(componentType: C): ComponentInstance<C>;
+    /**
+     * 检查是否拥有组件
+     */
+    hasComponent<C extends ComponentConstructor>(componentType: C): boolean;
+    /**
+     * 获取所有组件
+     */
+    readonly components: ComponentTypeMap<T>;
+}
+/**
+ * 查询结果类型
+ * 根据查询条件推断实体必定拥有的组件
+ */
+type QueryResult$1<All extends readonly ComponentConstructor[] = [], Any extends readonly ComponentConstructor[] = [], None extends readonly ComponentConstructor[] = []> = {
+    /**
+     * 实体列表，确保拥有All中的所有组件
+     */
+    readonly entities: ReadonlyArray<EntityWithComponents<All>>;
+    /**
+     * 实体数量
+     */
+    readonly length: number;
+    /**
+     * 遍历实体
+     */
+    forEach(callback: (entity: EntityWithComponents<All>, index: number) => void): void;
+    /**
+     * 映射转换
+     */
+    map<R>(callback: (entity: EntityWithComponents<All>, index: number) => R): R[];
+    /**
+     * 过滤实体
+     */
+    filter(predicate: (entity: EntityWithComponents<All>, index: number) => boolean): QueryResult$1<All, Any, None>;
+};
+/**
+ * System处理的实体类型
+ * 根据Matcher推断System处理的实体类型
+ */
+type SystemEntityType<M> = M extends {
+    getCondition(): {
+        all: infer All extends readonly ComponentConstructor[];
+    };
+} ? EntityWithComponents<All> : never;
+/**
+ * 组件字段类型提取
+ * 提取组件中所有可序列化的字段
+ */
+type SerializableFields<T> = {
+    [K in keyof T]: T[K] extends Function ? never : K;
+}[keyof T];
+/**
+ * 只读组件类型
+ * 将组件的所有字段转为只读
+ */
+type ReadonlyComponent<T extends IComponent> = {
+    readonly [K in keyof T]: T[K];
+};
+/**
+ * 部分组件类型
+ * 用于组件更新操作
+ */
+type PartialComponent<T extends IComponent> = {
+    [K in SerializableFields<T>]?: T[K];
+};
+/**
+ * 组件类型约束
+ * 确保类型参数是有效的组件
+ */
+type ValidComponent<T> = T extends Component ? T : never;
+/**
+ * 组件数组约束
+ * 确保数组中的所有元素都是组件构造函数
+ */
+type ValidComponentArray<T extends readonly any[]> = T extends readonly ComponentConstructor[] ? T : never;
+/**
+ * 事件处理器类型
+ * 提供类型安全的事件处理
+ */
+type TypedEventHandler<T> = (data: T) => void | Promise<void>;
+/**
+ * 系统生命周期钩子类型
+ */
+interface SystemLifecycleHooks<T extends readonly ComponentConstructor[]> {
+    /**
+     * 实体添加到系统时调用
+     */
+    onAdded?: (entity: EntityWithComponents<T>) => void;
+    /**
+     * 实体从系统移除时调用
+     */
+    onRemoved?: (entity: EntityWithComponents<T>) => void;
+    /**
+     * 系统初始化时调用
+     */
+    onInitialize?: () => void;
+    /**
+     * 系统销毁时调用
+     */
+    onDestroy?: () => void;
+}
+/**
+ * Fluent API构建器类型
+ */
+interface TypeSafeBuilder<T> {
+    /**
+     * 完成构建
+     */
+    build(): T;
+}
+/**
+ * 实体查询条件类型
+ */
+interface TypedQueryCondition<All extends readonly ComponentConstructor[] = [], Any extends readonly ComponentConstructor[] = [], None extends readonly ComponentConstructor[] = []> {
+    all: All;
+    any: Any;
+    none: None;
+    tag?: number;
+    name?: string;
+}
+/**
+ * 组件类型守卫
+ */
+declare function isComponentType<T extends IComponent>(value: any): value is ComponentConstructor<T>;
+/**
+ * 类型安全的组件数组守卫
+ */
+declare function isComponentArray(value: any[]): value is ComponentConstructor[];
+/**
+ * 提取组件类型名称（编译时）
+ */
+type ComponentTypeName<T extends ComponentConstructor> = T extends {
+    prototype: {
+        constructor: {
+            name: infer N;
+        };
+    };
+} ? N : string;
+/**
+ * 多组件类型名称联合
+ */
+type ComponentTypeNames<T extends readonly ComponentConstructor[]> = {
+    [K in keyof T]: ComponentTypeName<T[K]>;
+}[number];
+/**
+ * 深度只读类型
+ */
+type DeepReadonly<T> = {
+    readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
+};
+/**
+ * 深度可选类型
+ */
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/**
+ * 排除方法的类型
+ */
+type DataOnly<T> = {
+    [K in keyof T as T[K] extends Function ? never : K]: T[K];
+};
+/**
+ * 可序列化的组件数据
+ */
+type SerializableComponent<T extends IComponent> = DeepPartial<DataOnly<T>>;
+
 /**
  * 框架核心类型定义
  */
+
 /**
  * 组件接口
  *
@@ -1068,30 +1285,23 @@ declare abstract class Component implements IComponent {
 
 /**
  * 基础 64 位段结构
+ * [低32位，高32位]
  */
-interface BitMask64Segment {
-    /** 低32位（bit 0-31） */
-    lo: number;
-    /** 高32位（bit 32-63） */
-    hi: number;
-}
+type BitMask64Segment = [number, number];
 /**
  * 位掩码数据结构
- * 基础模式（64位）：使用 lo + hi 存储 64 位，segments 为空
- * 扩展模式（128+位）：lo + hi 作为第一段，segments 存储额外的 64 位段
+ * 基础模式（64位）：使用 base[lo , hi] 存储 64 位，segments 为空
+ * 扩展模式（128+位）：base[lo , hi] 作为第一段，segments 存储额外的 64 位段
  * segments[0] 对应 bit 64-127，segments[1] 对应 bit 128-191，以此类推
  */
 interface BitMask64Data {
-    /** 低32位（bit 0-31） */
-    lo: number;
-    /** 高32位（bit 32-63） */
-    hi: number;
+    base: BitMask64Segment;
     /** 扩展段数组，每个元素是一个 64 位段，用于超过 64 位的场景 */
     segments?: BitMask64Segment[];
 }
 declare class BitMask64Utils {
     /** 零掩码常量，所有位都为0 */
-    static readonly ZERO: BitMask64Data;
+    static readonly ZERO: Readonly<BitMask64Data>;
     /**
      * 根据位索引创建64位掩码
      * @param bitIndex 位索引，范围 [0, 63]
@@ -1114,7 +1324,6 @@ declare class BitMask64Utils {
     static hasAny(mask: BitMask64Data, bits: BitMask64Data): boolean;
     /**
      * 检查掩码是否包含所有指定的位
-     * 支持扩展模式，自动处理超过 64 位的掩码
      * @param mask 要检查的掩码
      * @param bits 指定的位模式
      * @returns 如果掩码包含bits中的所有位则返回true
@@ -1132,7 +1341,7 @@ declare class BitMask64Utils {
      * @param mask 要检查的掩码
      * @returns 如果掩码所有位都为0则返回true
      */
-    static isZero(mask: BitMask64Data | BitMask64Segment): boolean;
+    static isZero(mask: BitMask64Data): boolean;
     /**
      * 检查两个掩码是否相等
      * @param a 第一个掩码
@@ -1141,17 +1350,22 @@ declare class BitMask64Utils {
      */
     static equals(a: BitMask64Data, b: BitMask64Data): boolean;
     /**
-     * 设置掩码中指定位为1
+     * 设置掩码中指定位为1，必要时自动扩展
      * @param mask 要修改的掩码（原地修改）
-     * @param bitIndex 位索引，范围 [0, 63]
+     * @param bitIndex 位索引，不小于零
      * @throws 当位索引超出范围时抛出错误
      */
     static setBit(mask: BitMask64Data, bitIndex: number): void;
     /**
-     * 清除掩码中指定位为0
+     * 获取掩码中指定位，如果位超出当前掩码的区段长度，则直接返回0
+     * @param mask 掩码
+     * @param bitIndex 位索引，不小于零
+     */
+    static getBit(mask: BitMask64Data, bitIndex: number): boolean;
+    /**
+     * 清除掩码中指定位为0，如果位超出当前掩码的区段长度，则什么也不做
      * @param mask 要修改的掩码（原地修改）
-     * @param bitIndex 位索引，范围 [0, 63]
-     * @throws 当位索引超出范围时抛出错误
+     * @param bitIndex 位索引，不小于0
      */
     static clearBit(mask: BitMask64Data, bitIndex: number): void;
     /**
@@ -1178,7 +1392,7 @@ declare class BitMask64Utils {
      */
     static clear(mask: BitMask64Data): void;
     /**
-     * 将源掩码的值复制到目标掩码
+     * 将源掩码的值复制到目标掩码，如果source包含扩展段，则target也会至少扩展到source扩展段的长度
      * @param source 源掩码
      * @param target 目标掩码（原地修改）
      */
@@ -1190,13 +1404,13 @@ declare class BitMask64Utils {
      */
     static clone(mask: BitMask64Data): BitMask64Data;
     /**
-     * 将掩码转换为字符串表示
+     * 将掩码转换为字符串表示,每个区段之间将使用空格分割。
      * @param mask 要转换的掩码
-     * @param radix 进制，支持2（二进制）或16（十六进制），默认为2
+     * @param radix 进制，支持2（二进制）或16（十六进制），默认为2，其他的值被视为2
+     * @param printHead 打印头
      * @returns 掩码的字符串表示，二进制不带前缀，十六进制带0x前缀
-     * @throws 当进制不支持时抛出错误
      */
-    static toString(mask: BitMask64Data, radix?: number): string;
+    static toString(mask: BitMask64Data, radix?: 2 | 16, printHead?: boolean): string;
     /**
      * 计算掩码中设置为1的位数
      * @param mask 要计算的掩码
@@ -1204,24 +1418,13 @@ declare class BitMask64Utils {
      */
     static popCount(mask: BitMask64Data): number;
     /**
-     * 设置扩展位（支持超过 64 位的索引）
-     * @param mask 要修改的掩码（原地修改）
-     * @param bitIndex 位索引（可以超过 63）
-     */
-    static setBitExtended(mask: BitMask64Data, bitIndex: number): void;
-    /**
-     * 获取扩展位（支持超过 64 位的索引）
-     * @param mask 要检查的掩码
-     * @param bitIndex 位索引（可以超过 63）
-     * @returns 如果位被设置则返回 true
-     */
-    static getBitExtended(mask: BitMask64Data, bitIndex: number): boolean;
-    /**
-     * 清除扩展位（支持超过 64 位的索引）
-     * @param mask 要修改的掩码（原地修改）
-     * @param bitIndex 位索引（可以超过 63）
+     * 获取包含目标位的BitMask64Segment
+     * @param mask 要操作的掩码
+     * @param bitIndex 目标位
+     * @param createNewSegment 如果bitIndex超过了当前范围，是否自动补充扩展区域，默认为真
+     * @private
      */
-    static clearBitExtended(mask: BitMask64Data, bitIndex: number): void;
+    private static getSegmentByBitIndex;
 }
 
 /**
@@ -2546,8 +2749,7 @@ declare class IdentifierPool {
 
 /**
  * 位集合类，用于高效的位操作
- * 自动扩展支持：默认 64 位，超过时自动扩展到 128/256 位
- * 扩展模式性能略有下降，但仍然比数组遍历快得多
+ * 支持任意位的位运算操作.
  */
 declare class Bits {
     /** 存储位数据的掩码，支持扩展 */
@@ -3656,162 +3858,1083 @@ declare class TypeSafeEventSystem {
 }
 
 /**
- * 游戏场景默认实现类
+ * 类型安全的Query查询系统
  *
- * 实现IScene接口，提供场景的基础功能。
- * 推荐使用组合而非继承的方式来构建自定义场景。
+ * 提供完整的TypeScript类型推断，在编译时确保类型安全
  */
-declare class Scene implements IScene {
-    /**
-     * 场景名称
-     *
-     * 用于标识和调试的友好名称。
-     */
-    name: string;
-    /**
-     * 场景中的实体集合
-     *
-     * 管理场景内所有实体的生命周期。
-     */
-    readonly entities: EntityList;
+
+/**
+ * 类型安全的查询结果
+ *
+ * 根据查询条件自动推断实体必定拥有的组件类型
+ */
+declare class TypedQueryResult<TAll extends readonly ComponentConstructor[]> {
+    private _entities;
+    private _componentTypes;
+    constructor(entities: readonly Entity[], componentTypes: TAll);
     /**
-     * 实体系统处理器集合
-     *
-     * 管理场景内所有实体系统的执行。
+     * 获取实体列表
      */
-    readonly entityProcessors: EntityProcessorList;
+    get entities(): readonly Entity[];
     /**
-     * 实体ID池
-     *
-     * 用于分配和回收实体的唯一标识符。
+     * 实体数量
      */
-    readonly identifierPool: IdentifierPool;
+    get length(): number;
     /**
-     * 组件存储管理器
+     * 遍历所有实体
      *
-     * 高性能的组件存储和查询系统。
+     * @example
+     * ```typescript
+     * query.forEach((entity) => {
+     *     // entity.getComponent返回类型自动推断
+     *     const pos = entity.getComponent(Position); // Position类型
+     *     const vel = entity.getComponent(Velocity); // Velocity类型
+     * });
+     * ```
      */
-    readonly componentStorageManager: ComponentStorageManager;
+    forEach(callback: (entity: Entity, index: number) => void): void;
     /**
-     * 查询系统
-     *
-     * 基于位掩码的高性能实体查询系统。
+     * 映射转换实体
      */
-    readonly querySystem: QuerySystem;
+    map<R>(callback: (entity: Entity, index: number) => R): R[];
     /**
-     * 事件系统
-     *
-     * 类型安全的事件系统。
+     * 过滤实体
      */
-    readonly eventSystem: TypeSafeEventSystem;
+    filter(predicate: (entity: Entity, index: number) => boolean): TypedQueryResult<TAll>;
     /**
-     * 场景是否已开始运行
+     * 查找第一个匹配的实体
      */
-    private _didSceneBegin;
+    find(predicate: (entity: Entity, index: number) => boolean): Entity | undefined;
     /**
-     * 获取系统列表（兼容性属性）
+     * 检查是否存在匹配的实体
      */
-    get systems(): EntitySystem[];
+    some(predicate: (entity: Entity, index: number) => boolean): boolean;
     /**
-     * 创建场景实例
+     * 检查是否所有实体都匹配
      */
-    constructor(config?: ISceneConfig);
+    every(predicate: (entity: Entity, index: number) => boolean): boolean;
     /**
-     * 初始化场景
-     *
-     * 在场景创建时调用，子类可以重写此方法来设置初始实体和组件。
+     * 获取指定索引的实体
      */
-    initialize(): void;
+    get(index: number): Entity | undefined;
     /**
-     * 场景开始运行时的回调
-     *
-     * 在场景开始运行时调用，可以在此方法中执行场景启动逻辑。
+     * 获取第一个实体
      */
-    onStart(): void;
+    get first(): Entity | undefined;
     /**
-     * 场景卸载时的回调
-     *
-     * 在场景被销毁时调用，可以在此方法中执行清理工作。
+     * 获取最后一个实体
      */
-    unload(): void;
+    get last(): Entity | undefined;
     /**
-     * 开始场景，启动实体处理器等
-     *
-     * 这个方法会启动场景。它将启动实体处理器等，并调用onStart方法。
+     * 检查查询结果是否为空
      */
-    begin(): void;
+    get isEmpty(): boolean;
     /**
-     * 结束场景，清除实体、实体处理器等
-     *
-     * 这个方法会结束场景。它将移除所有实体，结束实体处理器等，并调用unload方法。
+     * 转换为数组
      */
-    end(): void;
+    toArray(): Entity[];
     /**
-     * 更新场景
+     * 获取组件类型信息（用于调试）
      */
-    update(): void;
+    getComponentTypes(): readonly ComponentConstructor[];
     /**
-     * 将实体添加到此场景，并返回它
-     * @param name 实体名称
+     * 迭代器支持
      */
-    createEntity(name: string): Entity;
+    [Symbol.iterator](): Iterator<Entity>;
+}
+/**
+ * 类型安全的查询构建器
+ *
+ * 支持链式调用，自动推断查询结果的类型
+ *
+ * @example
+ * ```typescript
+ * // 基础查询
+ * const query = new TypedQueryBuilder()
+ *     .withAll(Position, Velocity)
+ *     .build();
+ *
+ * // 复杂查询
+ * const complexQuery = new TypedQueryBuilder()
+ *     .withAll(Transform, Renderer)
+ *     .withAny(BoxCollider, CircleCollider)
+ *     .withNone(Disabled)
+ *     .withTag(EntityTags.Enemy)
+ *     .build();
+ * ```
+ */
+declare class TypedQueryBuilder<TAll extends readonly ComponentConstructor[] = [], TAny extends readonly ComponentConstructor[] = [], TNone extends readonly ComponentConstructor[] = []> {
+    private _all;
+    private _any;
+    private _none;
+    private _tag?;
+    private _name?;
+    constructor(all?: TAll, any?: TAny, none?: TNone, tag?: number, name?: string);
     /**
-     * 清除所有EntitySystem的实体缓存
-     * 当实体或组件发生变化时调用
+     * 要求实体拥有所有指定的组件
+     *
+     * @param types 组件类型
+     * @returns 新的查询构建器，类型参数更新
      */
-    clearSystemEntityCaches(): void;
+    withAll<TNewAll extends readonly ComponentConstructor[]>(...types: TNewAll): TypedQueryBuilder<readonly [...TAll, ...TNewAll], TAny, TNone>;
     /**
-     * 在场景的实体列表中添加一个实体
-     * @param entity 要添加的实体
-     * @param deferCacheClear 是否延迟缓存清理（用于批量操作）
+     * 要求实体至少拥有一个指定的组件
+     *
+     * @param types 组件类型
+     * @returns 新的查询构建器
      */
-    addEntity(entity: Entity, deferCacheClear?: boolean): Entity;
+    withAny<TNewAny extends readonly ComponentConstructor[]>(...types: TNewAny): TypedQueryBuilder<TAll, readonly [...TAny, ...TNewAny], TNone>;
     /**
-     * 批量创建实体（高性能版本）
-     * @param count 要创建的实体数量
-     * @param namePrefix 实体名称前缀
-     * @returns 创建的实体列表
+     * 排除拥有指定组件的实体
+     *
+     * @param types 组件类型
+     * @returns 新的查询构建器
      */
-    createEntities(count: number, namePrefix?: string): Entity[];
+    withNone<TNewNone extends readonly ComponentConstructor[]>(...types: TNewNone): TypedQueryBuilder<TAll, TAny, readonly [...TNone, ...TNewNone]>;
     /**
-     * 从场景中删除所有实体
+     * 按标签过滤实体
+     *
+     * @param tag 标签值
+     * @returns 新的查询构建器
      */
-    destroyAllEntities(): void;
+    withTag(tag: number): TypedQueryBuilder<TAll, TAny, TNone>;
     /**
-     * 搜索并返回第一个具有名称的实体
+     * 按名称过滤实体
+     *
      * @param name 实体名称
+     * @returns 新的查询构建器
      */
-    findEntity(name: string): Entity | null;
-    /**
-     * 根据ID查找实体
-     * @param id 实体ID
-     */
-    findEntityById(id: number): Entity | null;
+    withName(name: string): TypedQueryBuilder<TAll, TAny, TNone>;
     /**
-     * 根据标签查找实体
-     * @param tag 实体标签
+     * 构建Matcher对象
+     *
+     * @returns Matcher实例，用于传统查询API
      */
-    findEntitiesByTag(tag: number): Entity[];
+    buildMatcher(): Matcher;
     /**
-     * 根据名称查找实体（别名方法）
-     * @param name 实体名称
+     * 获取查询条件
+     *
+     * @returns 查询条件对象
      */
-    getEntityByName(name: string): Entity | null;
+    getCondition(): QueryCondition;
     /**
-     * 根据标签查找实体（别名方法）
-     * @param tag 实体标签
+     * 获取required组件类型（用于类型推断）
      */
-    getEntitiesByTag(tag: number): Entity[];
+    getRequiredTypes(): TAll;
     /**
-     * 在场景中添加一个EntitySystem处理器
-     * @param processor 处理器
+     * 克隆查询构建器
      */
-    addEntityProcessor(processor: EntitySystem): EntitySystem;
+    clone(): TypedQueryBuilder<TAll, TAny, TNone>;
+}
+/**
+ * 创建类型安全的查询构建器
+ *
+ * @example
+ * ```typescript
+ * const query = createQuery()
+ *     .withAll(Position, Velocity)
+ *     .withNone(Disabled);
+ *
+ * // 在System或Scene中使用
+ * const entities = scene.query(query);
+ * entities.forEach(entity => {
+ *     const pos = entity.getComponent(Position);  // 自动推断为Position
+ *     const vel = entity.getComponent(Velocity);  // 自动推断为Velocity
+ * });
+ * ```
+ */
+declare function createQuery(): TypedQueryBuilder<[], [], []>;
+/**
+ * 创建单组件查询的便捷方法
+ *
+ * @param componentType 组件类型
+ * @returns 查询构建器
+ *
+ * @example
+ * ```typescript
+ * const healthEntities = queryFor(HealthComponent);
+ * ```
+ */
+declare function queryFor<T extends ComponentConstructor>(componentType: T): TypedQueryBuilder<readonly [T], [], []>;
+/**
+ * 创建多组件查询的便捷方法
+ *
+ * @param types 组件类型数组
+ * @returns 查询构建器
+ *
+ * @example
+ * ```typescript
+ * const movableEntities = queryForAll(Position, Velocity);
+ * ```
+ */
+declare function queryForAll<T extends readonly ComponentConstructor[]>(...types: T): TypedQueryBuilder<T, [], []>;
+
+/**
+ * 组件序列化器
+ *
+ * 负责组件的序列化和反序列化操作
+ */
+
+/**
+ * 序列化后的组件数据
+ */
+interface SerializedComponent {
+    /**
+     * 组件类型名称
+     */
+    type: string;
+    /**
+     * 序列化版本
+     */
+    version: number;
+    /**
+     * 组件数据
+     */
+    data: Record<string, any>;
+}
+/**
+ * 组件序列化器类
+ */
+declare class ComponentSerializer {
+    /**
+     * 序列化单个组件
+     *
+     * @param component 要序列化的组件实例
+     * @returns 序列化后的组件数据，如果组件不可序列化则返回null
+     */
+    static serialize(component: Component): SerializedComponent | null;
+    /**
+     * 反序列化组件
+     *
+     * @param serializedData 序列化的组件数据
+     * @param componentRegistry 组件类型注册表 (类型名 -> 构造函数)
+     * @returns 反序列化后的组件实例，如果失败则返回null
+     */
+    static deserialize(serializedData: SerializedComponent, componentRegistry: Map<string, ComponentType>): Component | null;
+    /**
+     * 批量序列化组件
+     *
+     * @param components 组件数组
+     * @returns 序列化后的组件数据数组
+     */
+    static serializeComponents(components: Component[]): SerializedComponent[];
+    /**
+     * 批量反序列化组件
+     *
+     * @param serializedComponents 序列化的组件数据数组
+     * @param componentRegistry 组件类型注册表
+     * @returns 反序列化后的组件数组
+     */
+    static deserializeComponents(serializedComponents: SerializedComponent[], componentRegistry: Map<string, ComponentType>): Component[];
+    /**
+     * 默认值序列化
+     *
+     * 处理基本类型、数组、对象等的序列化
+     */
+    private static serializeValue;
+    /**
+     * 默认值反序列化
+     */
+    private static deserializeValue;
+    /**
+     * 验证序列化数据的版本
+     *
+     * @param serializedData 序列化数据
+     * @param expectedVersion 期望的版本号
+     * @returns 版本是否匹配
+     */
+    static validateVersion(serializedData: SerializedComponent, expectedVersion: number): boolean;
+    /**
+     * 获取组件的序列化信息
+     *
+     * @param component 组件实例或组件类
+     * @returns 序列化信息对象，包含类型名、版本、可序列化字段列表
+     */
+    static getSerializationInfo(component: Component | ComponentType): {
+        type: string;
+        version: number;
+        fields: string[];
+        ignoredFields: string[];
+        isSerializable: boolean;
+    } | null;
+}
+
+/**
+ * 实体序列化器
+ *
+ * 负责实体的序列化和反序列化操作
+ */
+
+/**
+ * 序列化后的实体数据
+ */
+interface SerializedEntity {
+    /**
+     * 实体ID
+     */
+    id: number;
+    /**
+     * 实体名称
+     */
+    name: string;
+    /**
+     * 实体标签
+     */
+    tag: number;
+    /**
+     * 激活状态
+     */
+    active: boolean;
+    /**
+     * 启用状态
+     */
+    enabled: boolean;
+    /**
+     * 更新顺序
+     */
+    updateOrder: number;
+    /**
+     * 组件列表
+     */
+    components: SerializedComponent[];
+    /**
+     * 子实体列表
+     */
+    children: SerializedEntity[];
+    /**
+     * 父实体ID（如果有）
+     */
+    parentId?: number;
+}
+/**
+ * 实体序列化器类
+ */
+declare class EntitySerializer {
+    /**
+     * 序列化单个实体
+     *
+     * @param entity 要序列化的实体
+     * @param includeChildren 是否包含子实体（默认true）
+     * @returns 序列化后的实体数据
+     */
+    static serialize(entity: Entity, includeChildren?: boolean): SerializedEntity;
+    /**
+     * 反序列化实体
+     *
+     * @param serializedEntity 序列化的实体数据
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator 实体ID生成器（用于生成新ID或保持原ID）
+     * @param preserveIds 是否保持原始ID（默认false）
+     * @returns 反序列化后的实体
+     */
+    static deserialize(serializedEntity: SerializedEntity, componentRegistry: Map<string, ComponentType>, idGenerator: () => number, preserveIds?: boolean): Entity;
+    /**
+     * 批量序列化实体
+     *
+     * @param entities 实体数组
+     * @param includeChildren 是否包含子实体
+     * @returns 序列化后的实体数据数组
+     */
+    static serializeEntities(entities: Entity[], includeChildren?: boolean): SerializedEntity[];
+    /**
+     * 批量反序列化实体
+     *
+     * @param serializedEntities 序列化的实体数据数组
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator 实体ID生成器
+     * @param preserveIds 是否保持原始ID
+     * @returns 反序列化后的实体数组
+     */
+    static deserializeEntities(serializedEntities: SerializedEntity[], componentRegistry: Map<string, ComponentType>, idGenerator: () => number, preserveIds?: boolean): Entity[];
+    /**
+     * 创建实体的深拷贝
+     *
+     * @param entity 要拷贝的实体
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator ID生成器
+     * @returns 拷贝后的新实体
+     */
+    static clone(entity: Entity, componentRegistry: Map<string, ComponentType>, idGenerator: () => number): Entity;
+}
+
+/**
+ * 场景序列化器
+ *
+ * 负责整个场景的序列化和反序列化，包括实体、组件等
+ */
+
+/**
+ * 场景序列化格式
+ */
+type SerializationFormat = 'json' | 'binary';
+/**
+ * 场景序列化策略
+ */
+type DeserializationStrategy = 'merge' | 'replace';
+/**
+ * 版本迁移函数
+ */
+type MigrationFunction = (oldVersion: number, newVersion: number, data: any) => any;
+/**
+ * 场景序列化选项
+ */
+interface SceneSerializationOptions {
+    /**
+     * 要序列化的组件类型列表
+     * 如果未指定，则序列化所有可序列化的组件
+     */
+    components?: ComponentType[];
+    /**
+     * 是否序列化系统状态（当前不支持）
+     */
+    systems?: boolean;
+    /**
+     * 序列化格式
+     */
+    format?: SerializationFormat;
+    /**
+     * 是否美化JSON输出（仅在format='json'时有效）
+     */
+    pretty?: boolean;
+    /**
+     * 是否包含元数据（如序列化时间、版本等）
+     */
+    includeMetadata?: boolean;
+}
+/**
+ * 场景反序列化选项
+ */
+interface SceneDeserializationOptions {
+    /**
+     * 反序列化策略
+     * - 'merge': 合并到现有场景
+     * - 'replace': 替换现有场景内容
+     */
+    strategy?: DeserializationStrategy;
+    /**
+     * 版本迁移函数
+     */
+    migration?: MigrationFunction;
+    /**
+     * 是否保持原始实体ID
+     */
+    preserveIds?: boolean;
+    /**
+     * 组件类型注册表
+     * 如果未提供，将尝试从全局注册表获取
+     */
+    componentRegistry?: Map<string, ComponentType>;
+}
+/**
+ * 序列化后的场景数据
+ */
+interface SerializedScene {
+    /**
+     * 场景名称
+     */
+    name: string;
+    /**
+     * 序列化版本
+     */
+    version: number;
+    /**
+     * 序列化时间戳
+     */
+    timestamp?: number;
+    /**
+     * 场景自定义数据
+     *
+     * 存储场景级别的配置和状态
+     */
+    sceneData?: Record<string, any>;
+    /**
+     * 实体列表
+     */
+    entities: SerializedEntity[];
+    /**
+     * 元数据
+     */
+    metadata?: {
+        entityCount: number;
+        componentTypeCount: number;
+        serializationOptions?: SceneSerializationOptions;
+    };
+    /**
+     * 组件类型注册信息
+     */
+    componentTypeRegistry: Array<{
+        typeName: string;
+        version: number;
+    }>;
+}
+/**
+ * 场景序列化器类
+ */
+declare class SceneSerializer {
+    /**
+     * 当前序列化版本
+     */
+    private static readonly SERIALIZATION_VERSION;
+    /**
+     * 序列化场景
+     *
+     * @param scene 要序列化的场景
+     * @param options 序列化选项
+     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     */
+    static serialize(scene: IScene, options?: SceneSerializationOptions): string | Buffer;
+    /**
+     * 反序列化场景
+     *
+     * @param scene 目标场景
+     * @param saveData 序列化的数据（JSON字符串或二进制Buffer）
+     * @param options 反序列化选项
+     */
+    static deserialize(scene: IScene, saveData: string | Buffer, options?: SceneDeserializationOptions): void;
+    /**
+     * 序列化场景自定义数据
+     *
+     * 将 Map<string, any> 转换为普通对象
+     */
+    private static serializeSceneData;
+    /**
+     * 反序列化场景自定义数据
+     *
+     * 将普通对象还原为 Map<string, any>
+     */
+    private static deserializeSceneData;
+    /**
+     * 序列化单个值
+     */
+    private static serializeValue;
+    /**
+     * 反序列化单个值
+     */
+    private static deserializeValue;
+    /**
+     * 过滤要序列化的实体和组件
+     */
+    private static filterEntities;
+    /**
+     * 构建组件类型注册表
+     */
+    private static buildComponentTypeRegistry;
+    /**
+     * 获取全局组件注册表
+     *
+     * 从所有已注册的组件类型构建注册表
+     */
+    private static getGlobalComponentRegistry;
+    /**
+     * 验证保存数据的有效性
+     *
+     * @param saveData 序列化的数据
+     * @returns 验证结果
+     */
+    static validate(saveData: string): {
+        valid: boolean;
+        version?: number;
+        errors?: string[];
+    };
+    /**
+     * 获取保存数据的信息（不完全反序列化）
+     *
+     * @param saveData 序列化的数据
+     * @returns 保存数据的元信息
+     */
+    static getInfo(saveData: string): {
+        name: string;
+        version: number;
+        timestamp?: number;
+        entityCount: number;
+        componentTypeCount: number;
+    } | null;
+}
+
+/**
+ * 增量序列化器
+ *
+ * 提供高性能的增量序列化支持，只序列化变更的数据
+ * 适用于网络同步、大场景存档、时间回溯等场景
+ */
+
+/**
+ * 变更操作类型
+ */
+declare enum ChangeOperation {
+    /** 添加新实体 */
+    EntityAdded = "entity_added",
+    /** 删除实体 */
+    EntityRemoved = "entity_removed",
+    /** 实体属性更新 */
+    EntityUpdated = "entity_updated",
+    /** 添加组件 */
+    ComponentAdded = "component_added",
+    /** 删除组件 */
+    ComponentRemoved = "component_removed",
+    /** 组件数据更新 */
+    ComponentUpdated = "component_updated",
+    /** 场景数据更新 */
+    SceneDataUpdated = "scene_data_updated"
+}
+/**
+ * 实体变更记录
+ */
+interface EntityChange {
+    /** 操作类型 */
+    operation: ChangeOperation;
+    /** 实体ID */
+    entityId: number;
+    /** 实体名称（用于Added操作） */
+    entityName?: string;
+    /** 实体数据（用于Added/Updated操作） */
+    entityData?: Partial<SerializedEntity>;
+}
+/**
+ * 组件变更记录
+ */
+interface ComponentChange {
+    /** 操作类型 */
+    operation: ChangeOperation;
+    /** 实体ID */
+    entityId: number;
+    /** 组件类型名称 */
+    componentType: string;
+    /** 组件数据（用于Added/Updated操作） */
+    componentData?: SerializedComponent;
+}
+/**
+ * 场景数据变更记录
+ */
+interface SceneDataChange {
+    /** 操作类型 */
+    operation: ChangeOperation;
+    /** 变更的键 */
+    key: string;
+    /** 新值 */
+    value: any;
+    /** 是否删除 */
+    deleted?: boolean;
+}
+/**
+ * 增量序列化数据
+ */
+interface IncrementalSnapshot {
+    /** 快照版本号 */
+    version: number;
+    /** 时间戳 */
+    timestamp: number;
+    /** 场景名称 */
+    sceneName: string;
+    /** 基础版本号（相对于哪个快照的增量） */
+    baseVersion: number;
+    /** 实体变更列表 */
+    entityChanges: EntityChange[];
+    /** 组件变更列表 */
+    componentChanges: ComponentChange[];
+    /** 场景数据变更列表 */
+    sceneDataChanges: SceneDataChange[];
+}
+/**
+ * 场景快照（用于对比）
+ */
+interface SceneSnapshot {
+    /** 快照版本号 */
+    version: number;
+    /** 实体ID集合 */
+    entityIds: Set<number>;
+    /** 实体数据映射 */
+    entities: Map<number, {
+        name: string;
+        tag: number;
+        active: boolean;
+        enabled: boolean;
+        updateOrder: number;
+        parentId?: number;
+    }>;
+    /** 组件数据映射 (entityId -> componentType -> serializedData) */
+    components: Map<number, Map<string, string>>;
+    /** 场景自定义数据 */
+    sceneData: Map<string, string>;
+}
+/**
+ * 增量序列化格式
+ */
+type IncrementalSerializationFormat = 'json' | 'binary';
+/**
+ * 增量序列化选项
+ */
+interface IncrementalSerializationOptions {
+    /**
+     * 是否包含组件数据的深度对比
+     * 默认true，设为false可提升性能但可能漏掉组件内部字段变更
+     */
+    deepComponentComparison?: boolean;
+    /**
+     * 是否跟踪场景数据变更
+     * 默认true
+     */
+    trackSceneData?: boolean;
+    /**
+     * 是否压缩快照（使用JSON序列化）
+     * 默认false，设为true可减少内存占用但增加CPU开销
+     */
+    compressSnapshot?: boolean;
+    /**
+     * 序列化格式
+     * - 'json': JSON格式（可读性好，方便调试）
+     * - 'binary': MessagePack二进制格式（体积小，性能高）
+     * 默认 'json'
+     */
+    format?: IncrementalSerializationFormat;
+    /**
+     * 是否美化JSON输出（仅在format='json'时有效）
+     * 默认false
+     */
+    pretty?: boolean;
+}
+/**
+ * 增量序列化器类
+ */
+declare class IncrementalSerializer {
+    /** 当前快照版本号 */
+    private static snapshotVersion;
+    /**
+     * 创建场景快照
+     *
+     * @param scene 要快照的场景
+     * @param options 序列化选项
+     * @returns 场景快照对象
+     */
+    static createSnapshot(scene: IScene, options?: IncrementalSerializationOptions): SceneSnapshot;
+    /**
+     * 计算增量变更
+     *
+     * @param scene 当前场景
+     * @param baseSnapshot 基础快照
+     * @param options 序列化选项
+     * @returns 增量快照
+     */
+    static computeIncremental(scene: IScene, baseSnapshot: SceneSnapshot, options?: IncrementalSerializationOptions): IncrementalSnapshot;
+    /**
+     * 检测组件变更
+     */
+    private static detectComponentChanges;
+    /**
+     * 检测场景数据变更
+     */
+    private static detectSceneDataChanges;
+    /**
+     * 应用增量变更到场景
+     *
+     * @param scene 目标场景
+     * @param incremental 增量快照
+     * @param componentRegistry 组件类型注册表
+     */
+    static applyIncremental(scene: IScene, incremental: IncrementalSnapshot, componentRegistry: Map<string, ComponentType>): void;
+    private static applyEntityAdded;
+    private static applyEntityRemoved;
+    private static applyEntityUpdated;
+    private static applyComponentAdded;
+    private static applyComponentRemoved;
+    private static applyComponentUpdated;
+    /**
+     * 序列化增量快照
+     *
+     * @param incremental 增量快照
+     * @param options 序列化选项
+     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     *
+     * @example
+     * ```typescript
+     * // JSON格式（默认）
+     * const jsonData = IncrementalSerializer.serializeIncremental(snapshot);
+     *
+     * // 二进制格式
+     * const binaryData = IncrementalSerializer.serializeIncremental(snapshot, {
+     *     format: 'binary'
+     * });
+     *
+     * // 美化JSON
+     * const prettyJson = IncrementalSerializer.serializeIncremental(snapshot, {
+     *     format: 'json',
+     *     pretty: true
+     * });
+     * ```
+     */
+    static serializeIncremental(incremental: IncrementalSnapshot, options?: {
+        format?: IncrementalSerializationFormat;
+        pretty?: boolean;
+    }): string | Buffer;
+    /**
+     * 反序列化增量快照
+     *
+     * @param data 序列化的数据（JSON字符串或二进制Buffer）
+     * @returns 增量快照
+     *
+     * @example
+     * ```typescript
+     * // 从JSON反序列化
+     * const snapshot = IncrementalSerializer.deserializeIncremental(jsonString);
+     *
+     * // 从二进制反序列化
+     * const snapshot = IncrementalSerializer.deserializeIncremental(buffer);
+     * ```
+     */
+    static deserializeIncremental(data: string | Buffer): IncrementalSnapshot;
+    /**
+     * 计算增量快照的大小（字节）
+     *
+     * @param incremental 增量快照
+     * @param format 序列化格式，默认为 'json'
+     * @returns 字节数
+     */
+    static getIncrementalSize(incremental: IncrementalSnapshot, format?: IncrementalSerializationFormat): number;
+    /**
+     * 获取增量快照的统计信息
+     *
+     * @param incremental 增量快照
+     * @returns 统计信息
+     */
+    static getIncrementalStats(incremental: IncrementalSnapshot): {
+        totalChanges: number;
+        entityChanges: number;
+        componentChanges: number;
+        sceneDataChanges: number;
+        addedEntities: number;
+        removedEntities: number;
+        updatedEntities: number;
+        addedComponents: number;
+        removedComponents: number;
+        updatedComponents: number;
+    };
+    /**
+     * 重置快照版本号（用于测试）
+     */
+    static resetVersion(): void;
+}
+
+/**
+ * 游戏场景默认实现类
+ *
+ * 实现IScene接口，提供场景的基础功能。
+ * 推荐使用组合而非继承的方式来构建自定义场景。
+ */
+declare class Scene implements IScene {
+    /**
+     * 场景名称
+     *
+     * 用于标识和调试的友好名称。
+     */
+    name: string;
+    /**
+     * 场景自定义数据
+     *
+     * 用于存储场景级别的配置和状态数据。
+     */
+    readonly sceneData: Map<string, any>;
+    /**
+     * 场景中的实体集合
+     *
+     * 管理场景内所有实体的生命周期。
+     */
+    readonly entities: EntityList;
+    /**
+     * 实体系统处理器集合
+     *
+     * 管理场景内所有实体系统的执行。
+     */
+    readonly entityProcessors: EntityProcessorList;
+    /**
+     * 实体ID池
+     *
+     * 用于分配和回收实体的唯一标识符。
+     */
+    readonly identifierPool: IdentifierPool;
+    /**
+     * 组件存储管理器
+     *
+     * 高性能的组件存储和查询系统。
+     */
+    readonly componentStorageManager: ComponentStorageManager;
+    /**
+     * 查询系统
+     *
+     * 基于位掩码的高性能实体查询系统。
+     */
+    readonly querySystem: QuerySystem;
+    /**
+     * 事件系统
+     *
+     * 类型安全的事件系统。
+     */
+    readonly eventSystem: TypeSafeEventSystem;
+    /**
+     * 场景是否已开始运行
+     */
+    private _didSceneBegin;
+    /**
+     * 获取系统列表（兼容性属性）
+     */
+    get systems(): EntitySystem[];
+    /**
+     * 创建场景实例
+     */
+    constructor(config?: ISceneConfig);
+    /**
+     * 初始化场景
+     *
+     * 在场景创建时调用，子类可以重写此方法来设置初始实体和组件。
+     */
+    initialize(): void;
+    /**
+     * 场景开始运行时的回调
+     *
+     * 在场景开始运行时调用，可以在此方法中执行场景启动逻辑。
+     */
+    onStart(): void;
+    /**
+     * 场景卸载时的回调
+     *
+     * 在场景被销毁时调用，可以在此方法中执行清理工作。
+     */
+    unload(): void;
+    /**
+     * 开始场景，启动实体处理器等
+     *
+     * 这个方法会启动场景。它将启动实体处理器等，并调用onStart方法。
+     */
+    begin(): void;
+    /**
+     * 结束场景，清除实体、实体处理器等
+     *
+     * 这个方法会结束场景。它将移除所有实体，结束实体处理器等，并调用unload方法。
+     */
+    end(): void;
+    /**
+     * 更新场景
+     */
+    update(): void;
+    /**
+     * 将实体添加到此场景，并返回它
+     * @param name 实体名称
+     */
+    createEntity(name: string): Entity;
+    /**
+     * 清除所有EntitySystem的实体缓存
+     * 当实体或组件发生变化时调用
+     */
+    clearSystemEntityCaches(): void;
+    /**
+     * 在场景的实体列表中添加一个实体
+     * @param entity 要添加的实体
+     * @param deferCacheClear 是否延迟缓存清理（用于批量操作）
+     */
+    addEntity(entity: Entity, deferCacheClear?: boolean): Entity;
+    /**
+     * 批量创建实体（高性能版本）
+     * @param count 要创建的实体数量
+     * @param namePrefix 实体名称前缀
+     * @returns 创建的实体列表
+     */
+    createEntities(count: number, namePrefix?: string): Entity[];
+    /**
+     * 从场景中删除所有实体
+     */
+    destroyAllEntities(): void;
+    /**
+     * 搜索并返回第一个具有名称的实体
+     * @param name 实体名称
+     */
+    findEntity(name: string): Entity | null;
+    /**
+     * 根据ID查找实体
+     * @param id 实体ID
+     */
+    findEntityById(id: number): Entity | null;
+    /**
+     * 根据标签查找实体
+     * @param tag 实体标签
+     */
+    findEntitiesByTag(tag: number): Entity[];
+    /**
+     * 根据名称查找实体（别名方法）
+     * @param name 实体名称
+     */
+    getEntityByName(name: string): Entity | null;
+    /**
+     * 根据标签查找实体（别名方法）
+     * @param tag 实体标签
+     */
+    getEntitiesByTag(tag: number): Entity[];
+    /**
+     * 查询拥有所有指定组件的实体
+     *
+     * @param componentTypes - 组件类型数组
+     * @returns 查询结果
+     *
+     * @example
+     * ```typescript
+     * const result = scene.queryAll(Position, Velocity);
+     * for (const entity of result.entities) {
+     *     const pos = entity.getComponent(Position);
+     *     const vel = entity.getComponent(Velocity);
+     * }
+     * ```
+     */
+    queryAll(...componentTypes: any[]): {
+        entities: readonly Entity[];
+    };
+    /**
+     * 查询拥有任意一个指定组件的实体
+     *
+     * @param componentTypes - 组件类型数组
+     * @returns 查询结果
+     */
+    queryAny(...componentTypes: any[]): {
+        entities: readonly Entity[];
+    };
+    /**
+     * 查询不包含指定组件的实体
+     *
+     * @param componentTypes - 组件类型数组
+     * @returns 查询结果
+     */
+    queryNone(...componentTypes: any[]): {
+        entities: readonly Entity[];
+    };
+    /**
+     * 创建类型安全的查询构建器
+     *
+     * @returns 查询构建器，支持链式调用
+     *
+     * @example
+     * ```typescript
+     * // 使用查询构建器
+     * const matcher = scene.query()
+     *     .withAll(Position, Velocity)
+     *     .withNone(Disabled)
+     *     .buildMatcher();
+     *
+     * // 在System中使用
+     * class MovementSystem extends EntitySystem {
+     *     constructor() {
+     *         super(matcher);
+     *     }
+     * }
+     * ```
+     */
+    query(): TypedQueryBuilder;
+    /**
+     * 在场景中添加一个EntitySystem处理器
+     * @param processor 处理器
+     */
+    addEntityProcessor(processor: EntitySystem): EntitySystem<[]>;
     /**
      * 添加系统到场景（addEntityProcessor的别名）
      * @param system 系统
      */
-    addSystem(system: EntitySystem): EntitySystem;
+    addSystem(system: EntitySystem): EntitySystem<[]>;
     /**
      * 从场景中删除EntitySystem处理器
      * @param processor 要删除的处理器
@@ -3856,6 +4979,155 @@ declare class Scene implements IScene {
         }>;
         componentStats: Map<string, any>;
     };
+    /**
+     * 序列化场景
+     *
+     * 将场景及其所有实体、组件序列化为JSON字符串或二进制Buffer
+     *
+     * @param options 序列化选项
+     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     *
+     * @example
+     * ```typescript
+     * // JSON格式
+     * const jsonData = scene.serialize({
+     *     format: 'json',
+     *     pretty: true
+     * });
+     *
+     * // 二进制格式（更小、更快）
+     * const binaryData = scene.serialize({
+     *     format: 'binary'
+     * });
+     * ```
+     */
+    serialize(options?: SceneSerializationOptions): string | Buffer;
+    /**
+     * 反序列化场景
+     *
+     * 从序列化数据恢复场景状态
+     *
+     * @param saveData 序列化的数据（JSON字符串或二进制Buffer）
+     * @param options 反序列化选项
+     *
+     * @example
+     * ```typescript
+     * // 从JSON恢复（自动从ComponentRegistry获取组件类型）
+     * scene.deserialize(jsonData, {
+     *     strategy: 'replace'
+     * });
+     *
+     * // 从二进制恢复
+     * scene.deserialize(binaryData, {
+     *     strategy: 'replace'
+     * });
+     * ```
+     */
+    deserialize(saveData: string | Buffer, options?: SceneDeserializationOptions): void;
+    /** 增量序列化的基础快照 */
+    private _incrementalBaseSnapshot?;
+    /**
+     * 创建增量序列化的基础快照
+     *
+     * 在需要进行增量序列化前，先调用此方法创建基础快照
+     *
+     * @param options 序列化选项
+     *
+     * @example
+     * ```typescript
+     * // 创建基础快照
+     * scene.createIncrementalSnapshot();
+     *
+     * // 进行一些修改...
+     * entity.addComponent(new PositionComponent(100, 200));
+     *
+     * // 计算增量变更
+     * const incremental = scene.serializeIncremental();
+     * ```
+     */
+    createIncrementalSnapshot(options?: IncrementalSerializationOptions): void;
+    /**
+     * 增量序列化场景
+     *
+     * 只序列化相对于基础快照的变更部分
+     *
+     * @param options 序列化选项
+     * @returns 增量快照对象
+     *
+     * @example
+     * ```typescript
+     * // 创建基础快照
+     * scene.createIncrementalSnapshot();
+     *
+     * // 修改场景
+     * const entity = scene.createEntity('NewEntity');
+     * entity.addComponent(new PositionComponent(50, 100));
+     *
+     * // 获取增量变更
+     * const incremental = scene.serializeIncremental();
+     * console.log(`变更数量: ${incremental.entityChanges.length}`);
+     *
+     * // 序列化为JSON
+     * const json = IncrementalSerializer.serializeIncremental(incremental);
+     * ```
+     */
+    serializeIncremental(options?: IncrementalSerializationOptions): IncrementalSnapshot;
+    /**
+     * 应用增量变更到场景
+     *
+     * @param incremental 增量快照数据（IncrementalSnapshot对象、JSON字符串或二进制Buffer）
+     * @param componentRegistry 组件类型注册表（可选，默认使用全局注册表）
+     *
+     * @example
+     * ```typescript
+     * // 应用增量变更对象
+     * scene.applyIncremental(incrementalSnapshot);
+     *
+     * // 从JSON字符串应用
+     * const jsonData = IncrementalSerializer.serializeIncremental(snapshot, { format: 'json' });
+     * scene.applyIncremental(jsonData);
+     *
+     * // 从二进制Buffer应用
+     * const binaryData = IncrementalSerializer.serializeIncremental(snapshot, { format: 'binary' });
+     * scene.applyIncremental(binaryData);
+     * ```
+     */
+    applyIncremental(incremental: IncrementalSnapshot | string | Buffer, componentRegistry?: Map<string, any>): void;
+    /**
+     * 更新增量快照基准
+     *
+     * 将当前场景状态设为新的增量序列化基准
+     *
+     * @param options 序列化选项
+     *
+     * @example
+     * ```typescript
+     * // 创建初始快照
+     * scene.createIncrementalSnapshot();
+     *
+     * // 进行一些修改并序列化
+     * const incremental1 = scene.serializeIncremental();
+     *
+     * // 更新基准，之后的增量将基于当前状态
+     * scene.updateIncrementalSnapshot();
+     *
+     * // 继续修改
+     * const incremental2 = scene.serializeIncremental();
+     * ```
+     */
+    updateIncrementalSnapshot(options?: IncrementalSerializationOptions): void;
+    /**
+     * 清除增量快照
+     *
+     * 释放快照占用的内存
+     */
+    clearIncrementalSnapshot(): void;
+    /**
+     * 检查是否有增量快照
+     *
+     * @returns 如果已创建增量快照返回true
+     */
+    hasIncrementalSnapshot(): boolean;
 }
 
 /**
@@ -3864,11 +5136,16 @@ declare class Scene implements IScene {
  * 用于处理一组符合特定条件的实体。系统是ECS架构中的逻辑处理单元，
  * 负责对拥有特定组件组合的实体执行业务逻辑。
  *
+ * 支持泛型参数以提供类型安全的组件访问：
+ *
+ * @template TComponents - 系统需要的组件类型数组
+ *
  * @example
  * ```typescript
+ * // 传统方式
  * class MovementSystem extends EntitySystem {
  *     constructor() {
- *         super(Transform, Velocity);
+ *         super(Matcher.of(Transform, Velocity));
  *     }
  *
  *     protected process(entities: readonly Entity[]): void {
@@ -3879,9 +5156,24 @@ declare class Scene implements IScene {
  *         }
  *     }
  * }
+ *
+ * // 类型安全方式
+ * class MovementSystem extends EntitySystem<[typeof Transform, typeof Velocity]> {
+ *     constructor() {
+ *         super(Matcher.of(Transform, Velocity));
+ *     }
+ *
+ *     protected process(entities: readonly Entity[]): void {
+ *         for (const entity of entities) {
+ *             // 类型安全的组件访问
+ *             const [transform, velocity] = this.getComponents(entity);
+ *             transform.position.add(velocity.value);
+ *         }
+ *     }
+ * }
  * ```
  */
-declare abstract class EntitySystem implements ISystemBase {
+declare abstract class EntitySystem<TComponents extends readonly ComponentConstructor[] = []> implements ISystemBase {
     private _updateOrder;
     private _enabled;
     private _performanceMonitor;
@@ -4132,6 +5424,162 @@ declare abstract class EntitySystem implements ISystemBase {
      * 注意：事件监听器会被框架自动清理，无需手动处理。
      */
     protected onDestroy(): void;
+    /**
+     * 类型安全地获取单个组件
+     *
+     * 相比Entity.getComponent，此方法保证返回非空值，
+     * 如果组件不存在会抛出错误而不是返回null
+     *
+     * @param entity 实体
+     * @param componentType 组件类型
+     * @returns 组件实例（保证非空）
+     * @throws 如果组件不存在则抛出错误
+     *
+     * @example
+     * ```typescript
+     * protected process(entities: readonly Entity[]): void {
+     *     for (const entity of entities) {
+     *         const transform = this.requireComponent(entity, Transform);
+     *         // transform 保证非空，类型为 Transform
+     *     }
+     * }
+     * ```
+     */
+    protected requireComponent<T extends ComponentConstructor>(entity: Entity, componentType: T): ComponentInstance<T>;
+    /**
+     * 批量获取实体的所有必需组件
+     *
+     * 根据泛型参数TComponents推断返回类型，
+     * 返回一个元组，包含所有组件实例
+     *
+     * @param entity 实体
+     * @param components 组件类型数组
+     * @returns 组件实例元组
+     *
+     * @example
+     * ```typescript
+     * class MySystem extends EntitySystem<[typeof Position, typeof Velocity]> {
+     *     protected process(entities: readonly Entity[]): void {
+     *         for (const entity of entities) {
+     *             const [pos, vel] = this.getComponents(entity, Position, Velocity);
+     *             // pos: Position, vel: Velocity (自动类型推断)
+     *             pos.x += vel.x;
+     *         }
+     *     }
+     * }
+     * ```
+     */
+    protected getComponents<T extends readonly ComponentConstructor[]>(entity: Entity, ...components: T): {
+        [K in keyof T]: ComponentInstance<T[K]>;
+    };
+    /**
+     * 遍历实体并处理每个实体
+     *
+     * 提供更简洁的语法糖，避免手动遍历
+     *
+     * @param entities 实体列表
+     * @param processor 处理函数
+     *
+     * @example
+     * ```typescript
+     * protected process(entities: readonly Entity[]): void {
+     *     this.forEach(entities, (entity) => {
+     *         const transform = this.requireComponent(entity, Transform);
+     *         transform.position.y -= 9.8 * Time.deltaTime;
+     *     });
+     * }
+     * ```
+     */
+    protected forEach(entities: readonly Entity[], processor: (entity: Entity, index: number) => void): void;
+    /**
+     * 过滤实体
+     *
+     * @param entities 实体列表
+     * @param predicate 过滤条件
+     * @returns 过滤后的实体数组
+     *
+     * @example
+     * ```typescript
+     * protected process(entities: readonly Entity[]): void {
+     *     const activeEntities = this.filterEntities(entities, (entity) => {
+     *         const health = this.requireComponent(entity, Health);
+     *         return health.value > 0;
+     *     });
+     * }
+     * ```
+     */
+    protected filterEntities(entities: readonly Entity[], predicate: (entity: Entity, index: number) => boolean): Entity[];
+    /**
+     * 映射实体到另一种类型
+     *
+     * @param entities 实体列表
+     * @param mapper 映射函数
+     * @returns 映射后的结果数组
+     *
+     * @example
+     * ```typescript
+     * protected process(entities: readonly Entity[]): void {
+     *     const positions = this.mapEntities(entities, (entity) => {
+     *         const transform = this.requireComponent(entity, Transform);
+     *         return transform.position;
+     *     });
+     * }
+     * ```
+     */
+    protected mapEntities<R>(entities: readonly Entity[], mapper: (entity: Entity, index: number) => R): R[];
+    /**
+     * 查找第一个满足条件的实体
+     *
+     * @param entities 实体列表
+     * @param predicate 查找条件
+     * @returns 第一个满足条件的实体，或undefined
+     *
+     * @example
+     * ```typescript
+     * protected process(entities: readonly Entity[]): void {
+     *     const player = this.findEntity(entities, (entity) =>
+     *         entity.hasComponent(PlayerTag)
+     *     );
+     * }
+     * ```
+     */
+    protected findEntity(entities: readonly Entity[], predicate: (entity: Entity, index: number) => boolean): Entity | undefined;
+    /**
+     * 检查是否存在满足条件的实体
+     *
+     * @param entities 实体列表
+     * @param predicate 检查条件
+     * @returns 是否存在满足条件的实体
+     *
+     * @example
+     * ```typescript
+     * protected process(entities: readonly Entity[]): void {
+     *     const hasLowHealth = this.someEntity(entities, (entity) => {
+     *         const health = this.requireComponent(entity, Health);
+     *         return health.value < 20;
+     *     });
+     * }
+     * ```
+     */
+    protected someEntity(entities: readonly Entity[], predicate: (entity: Entity, index: number) => boolean): boolean;
+    /**
+     * 检查是否所有实体都满足条件
+     *
+     * @param entities 实体列表
+     * @param predicate 检查条件
+     * @returns 是否所有实体都满足条件
+     *
+     * @example
+     * ```typescript
+     * protected process(entities: readonly Entity[]): void {
+     *     const allHealthy = this.everyEntity(entities, (entity) => {
+     *         const health = this.requireComponent(entity, Health);
+     *         return health.value > 50;
+     *     });
+     * }
+     * ```
+     */
+    protected everyEntity(entities: readonly Entity[], predicate: (entity: Entity, index: number) => boolean): boolean;
 }
 
 /**
@@ -4184,7 +5632,7 @@ declare class EntityProcessorList {
      */
     private sortProcessors;
     /** 获取处理器列表 */
-    get processors(): EntitySystem[];
+    get processors(): EntitySystem<[]>[];
     /** 获取处理器数量 */
     get count(): number;
 }
@@ -4199,6 +5647,24 @@ interface IScene {
      * 场景名称
      */
     name: string;
+    /**
+     * 场景自定义数据
+     *
+     * 用于存储场景级别的配置和状态数据，例如：
+     * - 天气状态
+     * - 时间设置
+     * - 游戏难度
+     * - 音频配置
+     * - 关卡检查点
+     *
+     * @example
+     * ```typescript
+     * scene.sceneData.set('weather', 'rainy');
+     * scene.sceneData.set('timeOfDay', 14.5);
+     * scene.sceneData.set('checkpoint', { x: 100, y: 200 });
+     * ```
+     */
+    readonly sceneData: Map<string, any>;
     /**
      * 场景中的实体集合
      */
@@ -4530,9 +5996,15 @@ declare class Entity {
     /**
      * 创建并添加组件
      *
-     * @param componentType - 组件类型
+     * @param componentType - 组件类型构造函数
      * @param args - 组件构造函数参数
      * @returns 创建的组件实例
+     *
+     * @example
+     * ```typescript
+     * const position = entity.createComponent(Position, 100, 200);
+     * const health = entity.createComponent(Health, 100);
+     * ```
      */
     createComponent<T extends Component>(componentType: ComponentType<T>, ...args: any[]): T;
     /**
@@ -4547,29 +6019,61 @@ declare class Entity {
      *
      * @param component - 要添加的组件实例
      * @returns 添加的组件实例
-     * @throws {Error} 如果组件类型已存在
+     * @throws {Error} 如果实体已存在该类型的组件
+     *
+     * @example
+     * ```typescript
+     * const position = new Position(100, 200);
+     * entity.addComponent(position);
+     * ```
      */
     addComponent<T extends Component>(component: T): T;
     /**
      * 获取指定类型的组件
      *
-     * @param type - 组件类型
-     * @returns 组件实例或null
+     * @param type - 组件类型构造函数
+     * @returns 组件实例，如果不存在则返回null
+     *
+     * @example
+     * ```typescript
+     * const position = entity.getComponent(Position);
+     * if (position) {
+     *     position.x += 10;
+     *     position.y += 20;
+     * }
+     * ```
      */
     getComponent<T extends Component>(type: ComponentType<T>): T | null;
     /**
-     * 检查实体是否有指定类型的组件
+     * 检查实体是否拥有指定类型的组件
      *
-     * @param type - 组件类型
-     * @returns 如果有该组件则返回true
+     * @param type - 组件类型构造函数
+     * @returns 如果实体拥有该组件返回true，否则返回false
+     *
+     * @example
+     * ```typescript
+     * if (entity.hasComponent(Position)) {
+     *     const position = entity.getComponent(Position)!;
+     *     position.x += 10;
+     * }
+     * ```
      */
     hasComponent<T extends Component>(type: ComponentType<T>): boolean;
     /**
      * 获取或创建指定类型的组件
      *
-     * @param type - 组件类型
-     * @param args - 组件构造函数参数（仅在创建时使用）
+     * 如果组件已存在则返回现有组件，否则创建新组件并添加到实体
+     *
+     * @param type - 组件类型构造函数
+     * @param args - 组件构造函数参数（仅在创建新组件时使用）
      * @returns 组件实例
+     *
+     * @example
+     * ```typescript
+     * // 确保实体拥有Position组件
+     * const position = entity.getOrCreateComponent(Position, 0, 0);
+     * position.x = 100;
+     * ```
      */
     getOrCreateComponent<T extends Component>(type: ComponentType<T>, ...args: any[]): T;
     /**
@@ -6606,6 +8110,7 @@ declare abstract class WorkerEntitySystem<TEntityData = any> extends EntitySyste
     protected sharedBuffer: SharedArrayBuffer | null;
     protected sharedFloatArray: Float32Array | null;
     private platformAdapter;
+    private hasLoggedSyncMode;
     constructor(matcher?: Matcher, config?: WorkerSystemConfig);
     /**
      * 检查是否支持Worker
@@ -6893,6 +8398,487 @@ declare class ComponentPoolManager {
     getComponentUtilization(componentName: string): number;
 }
 
+/**
+ * 序列化装饰器
+ *
+ * 提供组件级别的序列化支持，包括字段级装饰器和类级装饰器
+ */
+
+/**
+ * 序列化元数据的Symbol键
+ */
+declare const SERIALIZABLE_METADATA: unique symbol;
+declare const SERIALIZE_FIELD: unique symbol;
+declare const SERIALIZE_OPTIONS: unique symbol;
+/**
+ * 可序列化配置选项
+ */
+interface SerializableOptions {
+    /**
+     * 序列化版本号，用于数据迁移
+     */
+    version: number;
+    /**
+     * 组件类型标识符（可选，默认使用类名）
+     */
+    typeId?: string;
+}
+/**
+ * 字段序列化配置
+ */
+interface FieldSerializeOptions {
+    /**
+     * 自定义序列化器
+     */
+    serializer?: (value: any) => any;
+    /**
+     * 自定义反序列化器
+     */
+    deserializer?: (value: any) => any;
+    /**
+     * 字段别名（用于序列化后的键名）
+     */
+    alias?: string;
+}
+/**
+ * 序列化元数据
+ */
+interface SerializationMetadata {
+    options: SerializableOptions;
+    fields: Map<string | symbol, FieldSerializeOptions>;
+    ignoredFields: Set<string | symbol>;
+}
+/**
+ * 组件可序列化装饰器
+ *
+ * 标记组件类为可序列化，必须与字段装饰器配合使用
+ *
+ * @param options 序列化配置选项
+ *
+ * @example
+ * ```typescript
+ * @ECSComponent('Player')
+ * @Serializable({ version: 1 })
+ * class PlayerComponent extends Component {
+ *     @Serialize() name: string = 'Player';
+ *     @Serialize() level: number = 1;
+ * }
+ * ```
+ */
+declare function Serializable(options: SerializableOptions): <T extends new (...args: any[]) => Component>(target: T) => T;
+/**
+ * 字段序列化装饰器
+ *
+ * 标记字段为可序列化
+ *
+ * @param options 字段序列化选项（可选）
+ *
+ * @example
+ * ```typescript
+ * @Serialize()
+ * name: string = 'Player';
+ *
+ * @Serialize({ alias: 'hp' })
+ * health: number = 100;
+ * ```
+ */
+declare function Serialize(options?: FieldSerializeOptions): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Map序列化装饰器
+ *
+ * 专门用于序列化Map类型字段
+ *
+ * @example
+ * ```typescript
+ * @SerializeAsMap()
+ * inventory: Map<string, number> = new Map();
+ * ```
+ */
+declare function SerializeAsMap(): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Set序列化装饰器
+ *
+ * 专门用于序列化Set类型字段
+ *
+ * @example
+ * ```typescript
+ * @SerializeAsSet()
+ * tags: Set<string> = new Set();
+ * ```
+ */
+declare function SerializeAsSet(): (target: any, propertyKey: string | symbol) => void;
+/**
+ * 忽略序列化装饰器
+ *
+ * 标记字段不参与序列化
+ *
+ * @example
+ * ```typescript
+ * @IgnoreSerialization()
+ * tempCache: any = null;
+ * ```
+ */
+declare function IgnoreSerialization(): (target: any, propertyKey: string | symbol) => void;
+/**
+ * 获取组件的序列化元数据
+ *
+ * @param componentClass 组件类或组件实例
+ * @returns 序列化元数据，如果组件不可序列化则返回null
+ */
+declare function getSerializationMetadata(componentClass: any): SerializationMetadata | null;
+/**
+ * 检查组件是否可序列化
+ *
+ * @param component 组件类或组件实例
+ * @returns 如果组件可序列化返回true
+ */
+declare function isSerializable(component: any): boolean;
+
+/**
+ * 版本迁移系统
+ *
+ * 提供组件和场景数据的版本迁移支持
+ */
+
+/**
+ * 组件迁移函数
+ */
+type ComponentMigrationFunction = (data: any, fromVersion: number, toVersion: number) => any;
+/**
+ * 场景迁移函数
+ */
+type SceneMigrationFunction = (scene: SerializedScene, fromVersion: number, toVersion: number) => SerializedScene;
+/**
+ * 版本迁移管理器
+ */
+declare class VersionMigrationManager {
+    /**
+     * 组件迁移函数注册表
+     * Map<组件类型名, Map<版本号, 迁移函数>>
+     */
+    private static componentMigrations;
+    /**
+     * 场景迁移函数注册表
+     * Map<版本号, 迁移函数>
+     */
+    private static sceneMigrations;
+    /**
+     * 注册组件迁移函数
+     *
+     * @param componentType 组件类型名称
+     * @param fromVersion 源版本号
+     * @param toVersion 目标版本号
+     * @param migration 迁移函数
+     *
+     * @example
+     * ```typescript
+     * // 从版本1迁移到版本2
+     * VersionMigrationManager.registerComponentMigration(
+     *     'PlayerComponent',
+     *     1,
+     *     2,
+     *     (data) => {
+     *         // 添加新字段
+     *         data.experience = 0;
+     *         return data;
+     *     }
+     * );
+     * ```
+     */
+    static registerComponentMigration(componentType: string, fromVersion: number, toVersion: number, migration: ComponentMigrationFunction): void;
+    /**
+     * 注册场景迁移函数
+     *
+     * @param fromVersion 源版本号
+     * @param toVersion 目标版本号
+     * @param migration 迁移函数
+     *
+     * @example
+     * ```typescript
+     * VersionMigrationManager.registerSceneMigration(
+     *     1,
+     *     2,
+     *     (scene) => {
+     *         // 迁移场景结构
+     *         scene.metadata = { ...scene.metadata, migratedFrom: 1 };
+     *         return scene;
+     *     }
+     * );
+     * ```
+     */
+    static registerSceneMigration(fromVersion: number, toVersion: number, migration: SceneMigrationFunction): void;
+    /**
+     * 迁移组件数据
+     *
+     * @param component 序列化的组件数据
+     * @param targetVersion 目标版本号
+     * @returns 迁移后的组件数据
+     */
+    static migrateComponent(component: SerializedComponent, targetVersion: number): SerializedComponent;
+    /**
+     * 迁移场景数据
+     *
+     * @param scene 序列化的场景数据
+     * @param targetVersion 目标版本号
+     * @returns 迁移后的场景数据
+     */
+    static migrateScene(scene: SerializedScene, targetVersion: number): SerializedScene;
+    /**
+     * 迁移场景中所有组件的版本
+     */
+    private static migrateSceneComponents;
+    /**
+     * 递归迁移实体的组件
+     */
+    private static migrateEntitiesComponents;
+    /**
+     * 清除所有迁移函数
+     */
+    static clearMigrations(): void;
+    /**
+     * 获取组件的迁移路径
+     *
+     * @param componentType 组件类型名称
+     * @returns 可用的迁移版本列表
+     */
+    static getComponentMigrationPath(componentType: string): number[];
+    /**
+     * 获取场景的迁移路径
+     *
+     * @returns 可用的场景迁移版本列表
+     */
+    static getSceneMigrationPath(): number[];
+    /**
+     * 检查是否可以迁移组件
+     *
+     * @param componentType 组件类型名称
+     * @param fromVersion 源版本
+     * @param toVersion 目标版本
+     * @returns 是否存在完整的迁移路径
+     */
+    static canMigrateComponent(componentType: string, fromVersion: number, toVersion: number): boolean;
+    /**
+     * 检查是否可以迁移场景
+     *
+     * @param fromVersion 源版本
+     * @param toVersion 目标版本
+     * @returns 是否存在完整的迁移路径
+     */
+    static canMigrateScene(fromVersion: number, toVersion: number): boolean;
+}
+/**
+ * 便捷的迁移构建器
+ *
+ * 提供链式API来定义迁移
+ */
+declare class MigrationBuilder {
+    private componentType?;
+    private fromVersion;
+    private toVersion;
+    /**
+     * 设置组件类型
+     */
+    forComponent(componentType: string): this;
+    /**
+     * 设置版本范围
+     */
+    fromVersionToVersion(from: number, to: number): this;
+    /**
+     * 注册迁移函数
+     */
+    migrate(migration: ComponentMigrationFunction | SceneMigrationFunction): void;
+}
+
+/**
+ * Entity类型安全工具函数
+ *
+ * 提供类型安全的组件操作工具函数，无需修改Entity类
+ */
+
+/**
+ * 获取组件，如果不存在则抛出错误
+ *
+ * @param entity - 实体实例
+ * @param componentType - 组件类型构造函数
+ * @returns 组件实例（保证非空）
+ * @throws {Error} 如果组件不存在
+ *
+ * @example
+ * ```typescript
+ * const position = requireComponent(entity, Position);
+ * position.x += 10;
+ * ```
+ */
+declare function requireComponent<T extends ComponentConstructor>(entity: Entity, componentType: T): ComponentInstance<T>;
+/**
+ * 尝试获取组件
+ *
+ * @param entity - 实体实例
+ * @param componentType - 组件类型构造函数
+ * @returns 组件实例或undefined
+ *
+ * @example
+ * ```typescript
+ * const health = tryGetComponent(entity, Health);
+ * if (health) {
+ *     health.value -= 10;
+ * }
+ * ```
+ */
+declare function tryGetComponent<T extends ComponentConstructor>(entity: Entity, componentType: T): ComponentInstance<T> | undefined;
+/**
+ * 批量获取组件
+ *
+ * @param entity - 实体实例
+ * @param types - 组件类型构造函数数组
+ * @returns 组件实例元组，每个元素可能为null
+ *
+ * @example
+ * ```typescript
+ * const [pos, vel, health] = getComponents(entity, Position, Velocity, Health);
+ * if (pos && vel && health) {
+ *     pos.x += vel.dx;
+ * }
+ * ```
+ */
+declare function getComponents<T extends readonly ComponentConstructor[]>(entity: Entity, ...types: T): {
+    [K in keyof T]: ComponentInstance<T[K]> | null;
+};
+/**
+ * 检查实体是否拥有所有指定的组件
+ *
+ * @param entity - 实体实例
+ * @param types - 组件类型构造函数数组
+ * @returns 如果拥有所有组件返回true，否则返回false
+ *
+ * @example
+ * ```typescript
+ * if (hasComponents(entity, Position, Velocity)) {
+ *     const pos = entity.getComponent(Position)!;
+ *     const vel = entity.getComponent(Velocity)!;
+ * }
+ * ```
+ */
+declare function hasComponents(entity: Entity, ...types: ComponentConstructor[]): boolean;
+/**
+ * 检查实体是否拥有至少一个指定的组件
+ *
+ * @param entity - 实体实例
+ * @param types - 组件类型构造函数数组
+ * @returns 如果拥有任意一个组件返回true，否则返回false
+ */
+declare function hasAnyComponent(entity: Entity, ...types: ComponentConstructor[]): boolean;
+/**
+ * 添加组件并立即配置
+ *
+ * @param entity - 实体实例
+ * @param component - 组件实例
+ * @param configure - 配置回调函数
+ * @returns 实体实例（支持链式调用）
+ *
+ * @example
+ * ```typescript
+ * addAndConfigure(entity, new Health(), health => {
+ *     health.maxValue = 100;
+ *     health.value = 50;
+ * });
+ * ```
+ */
+declare function addAndConfigure<T extends Component>(entity: Entity, component: T, configure: (component: T) => void): Entity;
+/**
+ * 获取或添加组件
+ *
+ * 如果组件已存在则返回现有组件，否则通过工厂函数创建并添加
+ *
+ * @param entity - 实体实例
+ * @param componentType - 组件类型构造函数
+ * @param factory - 组件工厂函数（仅在组件不存在时调用）
+ * @returns 组件实例
+ *
+ * @example
+ * ```typescript
+ * const health = getOrAddComponent(entity, Health, () => new Health(100));
+ * ```
+ */
+declare function getOrAddComponent<T extends ComponentConstructor>(entity: Entity, componentType: T, factory: () => ComponentInstance<T>): ComponentInstance<T>;
+/**
+ * 更新组件的部分字段
+ *
+ * @param entity - 实体实例
+ * @param componentType - 组件类型构造函数
+ * @param data - 要更新的部分数据
+ * @returns 如果更新成功返回true，组件不存在返回false
+ *
+ * @example
+ * ```typescript
+ * updateComponent(entity, Position, { x: 100 });
+ * ```
+ */
+declare function updateComponent<T extends ComponentConstructor>(entity: Entity, componentType: T, data: Partial<ComponentInstance<T>>): boolean;
+/**
+ * 类型安全的实体构建器
+ *
+ * @example
+ * ```typescript
+ * const player = buildEntity(scene.createEntity("Player"))
+ *     .with(new Position(100, 100))
+ *     .with(new Velocity(0, 0))
+ *     .withTag(1)
+ *     .build();
+ * ```
+ */
+declare class TypedEntityBuilder {
+    private _entity;
+    constructor(entity: Entity);
+    /**
+     * 添加组件
+     */
+    with<T extends Component>(component: T): this;
+    /**
+     * 添加并配置组件
+     */
+    withConfigured<T extends Component>(component: T, configure: (component: T) => void): this;
+    /**
+     * 设置标签
+     */
+    withTag(tag: number): this;
+    /**
+     * 设置名称
+     */
+    withName(name: string): this;
+    /**
+     * 设置激活状态
+     */
+    withActive(active: boolean): this;
+    /**
+     * 设置启用状态
+     */
+    withEnabled(enabled: boolean): this;
+    /**
+     * 设置更新顺序
+     */
+    withUpdateOrder(order: number): this;
+    /**
+     * 添加子实体
+     */
+    withChild(child: Entity): this;
+    /**
+     * 完成构建
+     */
+    build(): Entity;
+    /**
+     * 获取正在构建的实体
+     */
+    get entity(): Entity;
+}
+/**
+ * 创建类型安全的实体构建器
+ *
+ * @param entity - 要包装的实体
+ * @returns 实体构建器
+ */
+declare function buildEntity(entity: Entity): TypedEntityBuilder;
+
 /**
  * 类型工具类
  * 提供类型相关的实用方法
@@ -7239,5 +9225,5 @@ declare function getFullPlatformConfig(): Promise<any>;
 declare function supportsFeature(feature: 'worker' | 'shared-array-buffer' | 'transferable-objects' | 'module-worker'): boolean;
 declare function hasAdapter(): boolean;
 
-export { AutoTyped, BitMask64Utils, Bits, COMPONENT_TYPE_NAME, Colors, Component, ComponentDataCollector, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSparseSet, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DeepCopy, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityProcessorList, EntitySystem, EventBus, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, Int16, Int32, Int8, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, PlatformDetector, PlatformManager, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeArray, SerializeMap, SerializeSet, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeInference, TypeSafeEventSystem, TypeUtils, Uint16, Uint32, Uint8, Uint8Clamped, WebSocketManager, WorkerEntitySystem, World, WorldManager, createECSAPI, createLogger, getBasicWorkerConfig, getComponentInstanceTypeName, getComponentTypeName, getCurrentAdapter, getFullPlatformConfig, getSystemInstanceTypeName, getSystemTypeName, hasAdapter, registerPlatformAdapter, resetLoggerColors, setGlobalLogLevel, setLoggerColors, supportsFeature };
-export type { BitMask64Data, ComponentType$1 as ComponentType, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPlatformAdapter, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IWorldConfig, IWorldManagerConfig, LoggerColorConfig, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PlatformConfig, PlatformDetectionResult, PlatformWorker, PoolStats, SharedArrayBufferProcessFunction, SupportedTypedArray, WorkerCreationOptions, WorkerProcessFunction, WorkerSystemConfig };
+export { AutoTyped, BitMask64Utils, Bits, COMPONENT_TYPE_NAME, ChangeOperation, Colors, Component, ComponentDataCollector, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSerializer, ComponentSparseSet, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DeepCopy, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityProcessorList, EntitySerializer, EntitySystem, EventBus, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, IgnoreSerialization, IncrementalSerializer, Int16, Int32, Int8, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, MigrationBuilder, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, PlatformDetector, PlatformManager, Pool, PoolManager, ProcessingSystem, QuerySystem, SERIALIZABLE_METADATA, SERIALIZE_FIELD, SERIALIZE_OPTIONS, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SceneSerializer, Serializable, Serialize, SerializeArray, SerializeAsMap, SerializeAsSet, SerializeMap, SerializeSet, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeInference, TypeSafeEventSystem, TypeUtils, TypedEntityBuilder, TypedQueryBuilder, TypedQueryResult, Uint16, Uint32, Uint8, Uint8Clamped, VersionMigrationManager, WebSocketManager, WorkerEntitySystem, World, WorldManager, addAndConfigure, buildEntity, createECSAPI, createLogger, createQuery, getBasicWorkerConfig, getComponentInstanceTypeName, getComponentTypeName, getComponents, getCurrentAdapter, getFullPlatformConfig, getOrAddComponent, getSerializationMetadata, getSystemInstanceTypeName, getSystemTypeName, hasAdapter, hasAnyComponent, hasComponents, isComponentArray, isComponentType, isSerializable, queryFor, queryForAll, registerPlatformAdapter, requireComponent, resetLoggerColors, setGlobalLogLevel, setLoggerColors, supportsFeature, tryGetComponent, updateComponent };
+export type { AnyComponentConstructor, BitMask64Data, ComponentChange, ComponentConstructor, ComponentInstance, ComponentMigrationFunction, ComponentType$1 as ComponentType, ComponentTypeMap, ComponentTypeName, ComponentTypeNames, DataOnly, DeepPartial, DeepReadonly, DeserializationStrategy, EntityChange, EntityWithComponents, EventListenerConfig, EventStats, ExtractComponents, FieldSerializeOptions, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPlatformAdapter, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IWorldConfig, IWorldManagerConfig, IncrementalSerializationFormat, IncrementalSerializationOptions, IncrementalSnapshot, LoggerColorConfig, LoggerConfig, MigrationFunction, PartialComponent, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PlatformConfig, PlatformDetectionResult, PlatformWorker, PoolStats, QueryResult$1 as QueryResult, ReadonlyComponent, SceneDataChange, SceneDeserializationOptions, SceneMigrationFunction, SceneSerializationOptions, SerializableComponent, SerializableFields, SerializableOptions, SerializationFormat, SerializationMetadata, SerializedComponent, SerializedEntity, SerializedScene, SharedArrayBufferProcessFunction, SupportedTypedArray, SystemEntityType, SystemLifecycleHooks, TypeSafeBuilder, TypedEventHandler, TypedQueryCondition, ValidComponent, ValidComponentArray, WorkerCreationOptions, WorkerProcessFunction, WorkerSystemConfig };