@esengine/ecs-framework 2.4.4 → 2.5.1

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.4.4
+ * @esengine/ecs-framework v2.5.1
  * TypeScript definitions
  */
 /**
@@ -832,10 +832,16 @@ type ISceneDebugData = {
  * @en Components in ECS architecture should be pure data containers.
  * All game logic should be implemented in EntitySystem, not inside components.
  *
+ * @zh **重要：所有 Component 子类都必须使用 @ECSComponent 装饰器！**
+ * @zh 该装饰器用于注册组件类型名称，是序列化、网络同步等功能正常工作的前提。
+ * @en **IMPORTANT: All Component subclasses MUST use the @ECSComponent decorator!**
+ * @en This decorator registers the component type name, which is required for serialization, network sync, etc.
+ *
  * @example
- * @zh 推荐做法：纯数据组件
- * @en Recommended: Pure data component
+ * @zh 正确做法：使用 @ECSComponent 装饰器
+ * @en Correct: Use @ECSComponent decorator
  * ```typescript
+ * @ECSComponent('HealthComponent')
  * class HealthComponent extends Component {
  *     public health: number = 100;
  *     public maxHealth: number = 100;
@@ -6367,7 +6373,9 @@ declare class Scene implements IScene {
      */
     end(): void;
     /**
-     * 更新场景
+     * @zh 更新场景
+     * @en Update scene
+     * @internal 由 SceneManager 或 World 调用，用户不应直接调用
      */
     update(): void;
     /**
@@ -11498,18 +11506,9 @@ declare class SceneManager implements IService {
      */
     get api(): ECSFluentAPI | null;
     /**
-     * 更新场景
-     *
-     * 应该在每帧的游戏循环中调用。
-     * 会自动处理延迟场景切换。
-     *
-     * @example
-     * ```typescript
-     * function gameLoop(deltaTime: number) {
-     *     Core.update(deltaTime);
-     *     sceneManager.update();  // 每帧调用
-     * }
-     * ```
+     * @zh 更新场景
+     * @en Update scene
+     * @internal 由 Core.update() 调用，用户不应直接调用
      */
     update(): void;
     /**
@@ -11993,9 +11992,7 @@ declare class WorldManager implements IService {
     /**
      * @zh 更新所有活跃的World
      * @en Update all active Worlds
-     *
-     * @zh 应该在每帧的游戏循环中调用
-     * @en Should be called in each frame of game loop
+     * @internal 由 Core.update() 调用，用户不应直接调用
      */
     updateAll(): void;
     /**
@@ -13000,6 +12997,860 @@ declare function isHidden(entityTag: number): boolean;
  */
 declare function isLocked(entityTag: number): boolean;
 
+/**
+ * @zh 网络同步类型定义
+ * @en Network synchronization type definitions
+ */
+/**
+ * @zh 支持的同步数据类型
+ * @en Supported sync data types
+ */
+type SyncType = 'boolean' | 'int8' | 'uint8' | 'int16' | 'uint16' | 'int32' | 'uint32' | 'float32' | 'float64' | 'string';
+/**
+ * @zh 同步字段元数据
+ * @en Sync field metadata
+ */
+interface SyncFieldMetadata {
+    /**
+     * @zh 字段索引（用于二进制编码）
+     * @en Field index (for binary encoding)
+     */
+    index: number;
+    /**
+     * @zh 字段名称
+     * @en Field name
+     */
+    name: string;
+    /**
+     * @zh 字段类型
+     * @en Field type
+     */
+    type: SyncType;
+}
+/**
+ * @zh 组件同步元数据
+ * @en Component sync metadata
+ */
+interface SyncMetadata {
+    /**
+     * @zh 组件类型 ID
+     * @en Component type ID
+     */
+    typeId: string;
+    /**
+     * @zh 同步字段列表（按索引排序）
+     * @en Sync fields list (sorted by index)
+     */
+    fields: SyncFieldMetadata[];
+    /**
+     * @zh 字段名到索引的映射
+     * @en Field name to index mapping
+     */
+    fieldIndexMap: Map<string, number>;
+}
+/**
+ * @zh 同步操作类型
+ * @en Sync operation type
+ */
+declare enum SyncOperation {
+    /**
+     * @zh 完整快照
+     * @en Full snapshot
+     */
+    FULL = 0,
+    /**
+     * @zh 增量更新
+     * @en Delta update
+     */
+    DELTA = 1,
+    /**
+     * @zh 实体生成
+     * @en Entity spawn
+     */
+    SPAWN = 2,
+    /**
+     * @zh 实体销毁
+     * @en Entity despawn
+     */
+    DESPAWN = 3
+}
+/**
+ * @zh 各类型的字节大小
+ * @en Byte size for each type
+ */
+declare const TYPE_SIZES: Record<SyncType, number>;
+/**
+ * @zh 同步元数据的 Symbol 键
+ * @en Symbol key for sync metadata
+ */
+declare const SYNC_METADATA: unique symbol;
+/**
+ * @zh 变更追踪器的 Symbol 键
+ * @en Symbol key for change tracker
+ */
+declare const CHANGE_TRACKER: unique symbol;
+
+/**
+ * @zh 组件变更追踪器
+ * @en Component change tracker
+ *
+ * @zh 用于追踪 @sync 标记字段的变更，支持增量同步
+ * @en Tracks changes to @sync marked fields for delta synchronization
+ */
+declare class ChangeTracker {
+    /**
+     * @zh 脏字段索引集合
+     * @en Set of dirty field indices
+     */
+    private _dirtyFields;
+    /**
+     * @zh 是否有任何变更
+     * @en Whether there are any changes
+     */
+    private _hasChanges;
+    /**
+     * @zh 上次同步的时间戳
+     * @en Last sync timestamp
+     */
+    private _lastSyncTime;
+    /**
+     * @zh 标记字段为脏
+     * @en Mark field as dirty
+     *
+     * @param fieldIndex - @zh 字段索引 @en Field index
+     */
+    setDirty(fieldIndex: number): void;
+    /**
+     * @zh 检查是否有变更
+     * @en Check if there are any changes
+     */
+    hasChanges(): boolean;
+    /**
+     * @zh 检查特定字段是否脏
+     * @en Check if a specific field is dirty
+     *
+     * @param fieldIndex - @zh 字段索引 @en Field index
+     */
+    isDirty(fieldIndex: number): boolean;
+    /**
+     * @zh 获取所有脏字段索引
+     * @en Get all dirty field indices
+     */
+    getDirtyFields(): number[];
+    /**
+     * @zh 获取脏字段数量
+     * @en Get number of dirty fields
+     */
+    getDirtyCount(): number;
+    /**
+     * @zh 清除所有变更标记
+     * @en Clear all change marks
+     */
+    clear(): void;
+    /**
+     * @zh 清除特定字段的变更标记
+     * @en Clear change mark for a specific field
+     *
+     * @param fieldIndex - @zh 字段索引 @en Field index
+     */
+    clearField(fieldIndex: number): void;
+    /**
+     * @zh 获取上次同步时间
+     * @en Get last sync time
+     */
+    get lastSyncTime(): number;
+    /**
+     * @zh 标记所有字段为脏（用于首次同步）
+     * @en Mark all fields as dirty (for initial sync)
+     *
+     * @param fieldCount - @zh 字段数量 @en Field count
+     */
+    markAllDirty(fieldCount: number): void;
+    /**
+     * @zh 重置追踪器
+     * @en Reset tracker
+     */
+    reset(): void;
+}
+
+/**
+ * @zh 网络同步装饰器
+ * @en Network synchronization decorators
+ *
+ * @zh 提供 @sync 装饰器，用于标记需要网络同步的 Component 字段
+ * @en Provides @sync decorator to mark Component fields for network synchronization
+ */
+
+/**
+ * @zh 同步字段装饰器
+ * @en Sync field decorator
+ *
+ * @zh 标记 Component 字段为可网络同步。被标记的字段会自动追踪变更，
+ * 并在值修改时触发变更追踪器。
+ * @en Marks a Component field for network synchronization. Marked fields
+ * automatically track changes and trigger the change tracker on modification.
+ *
+ * @param type - @zh 字段的同步类型 @en Sync type of the field
+ *
+ * @example
+ * ```typescript
+ * import { Component, ECSComponent } from '@esengine/ecs-framework';
+ * import { sync } from '@esengine/ecs-framework';
+ *
+ * @ECSComponent('Player')
+ * class PlayerComponent extends Component {
+ *     @sync("string") name: string = "";
+ *     @sync("uint16") score: number = 0;
+ *     @sync("float32") x: number = 0;
+ *     @sync("float32") y: number = 0;
+ *
+ *     // 不带 @sync 的字段不会同步
+ *     // Fields without @sync will not be synchronized
+ *     localData: any;
+ * }
+ * ```
+ */
+declare function sync(type: SyncType): (target: any, propertyKey: string) => void;
+/**
+ * @zh 获取组件类的同步元数据
+ * @en Get sync metadata for a component class
+ *
+ * @param componentClass - @zh 组件类或组件实例 @en Component class or instance
+ * @returns @zh 同步元数据，如果不存在则返回 null @en Sync metadata, or null if not exists
+ */
+declare function getSyncMetadata(componentClass: any): SyncMetadata | null;
+/**
+ * @zh 检查组件是否有同步字段
+ * @en Check if a component has sync fields
+ *
+ * @param component - @zh 组件类或组件实例 @en Component class or instance
+ * @returns @zh 如果有同步字段返回 true @en Returns true if has sync fields
+ */
+declare function hasSyncFields(component: any): boolean;
+/**
+ * @zh 获取组件实例的变更追踪器
+ * @en Get change tracker of a component instance
+ *
+ * @param component - @zh 组件实例 @en Component instance
+ * @returns @zh 变更追踪器，如果不存在则返回 null @en Change tracker, or null if not exists
+ */
+declare function getChangeTracker(component: any): ChangeTracker | null;
+/**
+ * @zh 为组件实例初始化变更追踪器
+ * @en Initialize change tracker for a component instance
+ *
+ * @zh 这个函数应该在组件首次添加到实体时调用。
+ * 它会创建变更追踪器并标记所有字段为脏（用于首次同步）。
+ * @en This function should be called when a component is first added to an entity.
+ * It creates the change tracker and marks all fields as dirty (for initial sync).
+ *
+ * @param component - @zh 组件实例 @en Component instance
+ * @returns @zh 变更追踪器 @en Change tracker
+ */
+declare function initChangeTracker(component: any): ChangeTracker;
+/**
+ * @zh 清除组件实例的变更标记
+ * @en Clear change marks for a component instance
+ *
+ * @zh 通常在同步完成后调用，清除所有脏标记
+ * @en Usually called after sync is complete, clears all dirty marks
+ *
+ * @param component - @zh 组件实例 @en Component instance
+ */
+declare function clearChanges(component: any): void;
+/**
+ * @zh 检查组件是否有变更
+ * @en Check if a component has changes
+ *
+ * @param component - @zh 组件实例 @en Component instance
+ * @returns @zh 如果有变更返回 true @en Returns true if has changes
+ */
+declare function hasChanges(component: any): boolean;
+
+/**
+ * @zh 变长整数编解码
+ * @en Variable-length integer encoding/decoding
+ *
+ * @zh 使用 LEB128 编码方式，可变长度编码正整数。
+ * 小数值使用更少字节，大数值使用更多字节。
+ * @en Uses LEB128 encoding for variable-length integer encoding.
+ * Small values use fewer bytes, large values use more bytes.
+ *
+ * | 值范围 | 字节数 |
+ * |--------|--------|
+ * | 0-127 | 1 |
+ * | 128-16383 | 2 |
+ * | 16384-2097151 | 3 |
+ * | 2097152-268435455 | 4 |
+ * | 268435456+ | 5 |
+ */
+/**
+ * @zh 计算变长整数所需的字节数
+ * @en Calculate bytes needed for a varint
+ *
+ * @param value - @zh 整数值 @en Integer value
+ * @returns @zh 所需字节数 @en Bytes needed
+ */
+declare function varintSize(value: number): number;
+/**
+ * @zh 编码变长整数到字节数组
+ * @en Encode varint to byte array
+ *
+ * @param value - @zh 要编码的整数 @en Integer to encode
+ * @param buffer - @zh 目标缓冲区 @en Target buffer
+ * @param offset - @zh 写入偏移 @en Write offset
+ * @returns @zh 写入后的新偏移 @en New offset after writing
+ */
+declare function encodeVarint(value: number, buffer: Uint8Array, offset: number): number;
+/**
+ * @zh 从字节数组解码变长整数
+ * @en Decode varint from byte array
+ *
+ * @param buffer - @zh 源缓冲区 @en Source buffer
+ * @param offset - @zh 读取偏移 @en Read offset
+ * @returns @zh [解码值, 新偏移] @en [decoded value, new offset]
+ */
+declare function decodeVarint(buffer: Uint8Array, offset: number): [number, number];
+/**
+ * @zh 编码有符号整数（ZigZag 编码）
+ * @en Encode signed integer (ZigZag encoding)
+ *
+ * @zh ZigZag 编码将有符号整数映射到无符号整数：
+ * 0 → 0, -1 → 1, 1 → 2, -2 → 3, 2 → 4, ...
+ * 这样小的负数也能用较少字节表示。
+ * @en ZigZag encoding maps signed integers to unsigned:
+ * 0 → 0, -1 → 1, 1 → 2, -2 → 3, 2 → 4, ...
+ * This allows small negative numbers to use fewer bytes.
+ *
+ * @param value - @zh 有符号整数 @en Signed integer
+ * @returns @zh ZigZag 编码后的值 @en ZigZag encoded value
+ */
+declare function zigzagEncode(value: number): number;
+/**
+ * @zh 解码有符号整数（ZigZag 解码）
+ * @en Decode signed integer (ZigZag decoding)
+ *
+ * @param value - @zh ZigZag 编码的值 @en ZigZag encoded value
+ * @returns @zh 原始有符号整数 @en Original signed integer
+ */
+declare function zigzagDecode(value: number): number;
+/**
+ * @zh 编码有符号变长整数
+ * @en Encode signed varint
+ *
+ * @param value - @zh 有符号整数 @en Signed integer
+ * @param buffer - @zh 目标缓冲区 @en Target buffer
+ * @param offset - @zh 写入偏移 @en Write offset
+ * @returns @zh 写入后的新偏移 @en New offset after writing
+ */
+declare function encodeSignedVarint(value: number, buffer: Uint8Array, offset: number): number;
+/**
+ * @zh 解码有符号变长整数
+ * @en Decode signed varint
+ *
+ * @param buffer - @zh 源缓冲区 @en Source buffer
+ * @param offset - @zh 读取偏移 @en Read offset
+ * @returns @zh [解码值, 新偏移] @en [decoded value, new offset]
+ */
+declare function decodeSignedVarint(buffer: Uint8Array, offset: number): [number, number];
+
+/**
+ * @zh 二进制写入器
+ * @en Binary Writer
+ *
+ * @zh 提供高效的二进制数据写入功能，支持自动扩容
+ * @en Provides efficient binary data writing with auto-expansion
+ */
+/**
+ * @zh 二进制写入器
+ * @en Binary writer for encoding data
+ */
+declare class BinaryWriter {
+    /**
+     * @zh 内部缓冲区
+     * @en Internal buffer
+     */
+    private _buffer;
+    /**
+     * @zh DataView 用于写入数值
+     * @en DataView for writing numbers
+     */
+    private _view;
+    /**
+     * @zh 当前写入位置
+     * @en Current write position
+     */
+    private _offset;
+    /**
+     * @zh 创建二进制写入器
+     * @en Create binary writer
+     *
+     * @param initialCapacity - @zh 初始容量 @en Initial capacity
+     */
+    constructor(initialCapacity?: number);
+    /**
+     * @zh 获取当前写入位置
+     * @en Get current write position
+     */
+    get offset(): number;
+    /**
+     * @zh 获取写入的数据
+     * @en Get written data
+     *
+     * @returns @zh 包含写入数据的 Uint8Array @en Uint8Array containing written data
+     */
+    toUint8Array(): Uint8Array;
+    /**
+     * @zh 重置写入器（清空数据但保留缓冲区）
+     * @en Reset writer (clear data but keep buffer)
+     */
+    reset(): void;
+    /**
+     * @zh 确保有足够空间
+     * @en Ensure enough space
+     *
+     * @param size - @zh 需要的额外字节数 @en Extra bytes needed
+     */
+    private ensureCapacity;
+    /**
+     * @zh 写入单个字节
+     * @en Write single byte
+     */
+    writeUint8(value: number): void;
+    /**
+     * @zh 写入有符号字节
+     * @en Write signed byte
+     */
+    writeInt8(value: number): void;
+    /**
+     * @zh 写入布尔值
+     * @en Write boolean
+     */
+    writeBoolean(value: boolean): void;
+    /**
+     * @zh 写入 16 位无符号整数（小端序）
+     * @en Write 16-bit unsigned integer (little-endian)
+     */
+    writeUint16(value: number): void;
+    /**
+     * @zh 写入 16 位有符号整数（小端序）
+     * @en Write 16-bit signed integer (little-endian)
+     */
+    writeInt16(value: number): void;
+    /**
+     * @zh 写入 32 位无符号整数（小端序）
+     * @en Write 32-bit unsigned integer (little-endian)
+     */
+    writeUint32(value: number): void;
+    /**
+     * @zh 写入 32 位有符号整数（小端序）
+     * @en Write 32-bit signed integer (little-endian)
+     */
+    writeInt32(value: number): void;
+    /**
+     * @zh 写入 32 位浮点数（小端序）
+     * @en Write 32-bit float (little-endian)
+     */
+    writeFloat32(value: number): void;
+    /**
+     * @zh 写入 64 位浮点数（小端序）
+     * @en Write 64-bit float (little-endian)
+     */
+    writeFloat64(value: number): void;
+    /**
+     * @zh 写入变长整数
+     * @en Write variable-length integer
+     */
+    writeVarint(value: number): void;
+    /**
+     * @zh 写入字符串（UTF-8 编码，带长度前缀）
+     * @en Write string (UTF-8 encoded with length prefix)
+     */
+    writeString(value: string): void;
+    /**
+     * @zh 写入原始字节
+     * @en Write raw bytes
+     */
+    writeBytes(data: Uint8Array): void;
+    /**
+     * @zh 字符串转 UTF-8 字节（后备方案）
+     * @en String to UTF-8 bytes (fallback)
+     */
+    private stringToUtf8Bytes;
+}
+
+/**
+ * @zh 二进制读取器
+ * @en Binary Reader
+ *
+ * @zh 提供高效的二进制数据读取功能
+ * @en Provides efficient binary data reading
+ */
+/**
+ * @zh 二进制读取器
+ * @en Binary reader for decoding data
+ */
+declare class BinaryReader {
+    /**
+     * @zh 数据缓冲区
+     * @en Data buffer
+     */
+    private _buffer;
+    /**
+     * @zh DataView 用于读取数值
+     * @en DataView for reading numbers
+     */
+    private _view;
+    /**
+     * @zh 当前读取位置
+     * @en Current read position
+     */
+    private _offset;
+    /**
+     * @zh 创建二进制读取器
+     * @en Create binary reader
+     *
+     * @param buffer - @zh 要读取的数据 @en Data to read
+     */
+    constructor(buffer: Uint8Array);
+    /**
+     * @zh 获取当前读取位置
+     * @en Get current read position
+     */
+    get offset(): number;
+    /**
+     * @zh 设置读取位置
+     * @en Set read position
+     */
+    set offset(value: number);
+    /**
+     * @zh 获取剩余可读字节数
+     * @en Get remaining readable bytes
+     */
+    get remaining(): number;
+    /**
+     * @zh 检查是否有更多数据可读
+     * @en Check if there's more data to read
+     */
+    hasMore(): boolean;
+    /**
+     * @zh 读取单个字节
+     * @en Read single byte
+     */
+    readUint8(): number;
+    /**
+     * @zh 读取有符号字节
+     * @en Read signed byte
+     */
+    readInt8(): number;
+    /**
+     * @zh 读取布尔值
+     * @en Read boolean
+     */
+    readBoolean(): boolean;
+    /**
+     * @zh 读取 16 位无符号整数（小端序）
+     * @en Read 16-bit unsigned integer (little-endian)
+     */
+    readUint16(): number;
+    /**
+     * @zh 读取 16 位有符号整数（小端序）
+     * @en Read 16-bit signed integer (little-endian)
+     */
+    readInt16(): number;
+    /**
+     * @zh 读取 32 位无符号整数（小端序）
+     * @en Read 32-bit unsigned integer (little-endian)
+     */
+    readUint32(): number;
+    /**
+     * @zh 读取 32 位有符号整数（小端序）
+     * @en Read 32-bit signed integer (little-endian)
+     */
+    readInt32(): number;
+    /**
+     * @zh 读取 32 位浮点数（小端序）
+     * @en Read 32-bit float (little-endian)
+     */
+    readFloat32(): number;
+    /**
+     * @zh 读取 64 位浮点数（小端序）
+     * @en Read 64-bit float (little-endian)
+     */
+    readFloat64(): number;
+    /**
+     * @zh 读取变长整数
+     * @en Read variable-length integer
+     */
+    readVarint(): number;
+    /**
+     * @zh 读取字符串（UTF-8 编码，带长度前缀）
+     * @en Read string (UTF-8 encoded with length prefix)
+     */
+    readString(): string;
+    /**
+     * @zh 读取原始字节
+     * @en Read raw bytes
+     *
+     * @param length - @zh 要读取的字节数 @en Number of bytes to read
+     */
+    readBytes(length: number): Uint8Array;
+    /**
+     * @zh 查看下一个字节但不移动读取位置
+     * @en Peek next byte without advancing read position
+     */
+    peekUint8(): number;
+    /**
+     * @zh 跳过指定字节数
+     * @en Skip specified number of bytes
+     */
+    skip(count: number): void;
+    /**
+     * @zh 检查边界
+     * @en Check bounds
+     */
+    private checkBounds;
+    /**
+     * @zh UTF-8 字节转字符串（后备方案）
+     * @en UTF-8 bytes to string (fallback)
+     */
+    private utf8BytesToString;
+}
+
+/**
+ * @zh 组件状态编码器
+ * @en Component state encoder
+ *
+ * @zh 将 ECS Component 的 @sync 字段编码为二进制格式
+ * @en Encodes @sync fields of ECS Components to binary format
+ */
+
+/**
+ * @zh 编码组件的完整状态
+ * @en Encode full state of a component
+ *
+ * @zh 格式: [fieldCount: varint] ([fieldIndex: uint8] [value])...
+ * @en Format: [fieldCount: varint] ([fieldIndex: uint8] [value])...
+ *
+ * @param component - @zh 组件实例 @en Component instance
+ * @param metadata - @zh 组件同步元数据 @en Component sync metadata
+ * @param writer - @zh 二进制写入器 @en Binary writer
+ */
+declare function encodeComponentFull(component: Component, metadata: SyncMetadata, writer: BinaryWriter): void;
+/**
+ * @zh 编码组件的增量状态（只编码脏字段）
+ * @en Encode delta state of a component (only dirty fields)
+ *
+ * @zh 格式: [dirtyCount: varint] ([fieldIndex: uint8] [value])...
+ * @en Format: [dirtyCount: varint] ([fieldIndex: uint8] [value])...
+ *
+ * @param component - @zh 组件实例 @en Component instance
+ * @param metadata - @zh 组件同步元数据 @en Component sync metadata
+ * @param tracker - @zh 变更追踪器 @en Change tracker
+ * @param writer - @zh 二进制写入器 @en Binary writer
+ * @returns @zh 是否有数据编码 @en Whether any data was encoded
+ */
+declare function encodeComponentDelta(component: Component, metadata: SyncMetadata, tracker: ChangeTracker, writer: BinaryWriter): boolean;
+/**
+ * @zh 编码实体的所有同步组件
+ * @en Encode all sync components of an entity
+ *
+ * @zh 格式:
+ * [entityId: uint32]
+ * [componentCount: varint]
+ * ([typeIdLength: varint] [typeId: string] [componentData])...
+ *
+ * @en Format:
+ * [entityId: uint32]
+ * [componentCount: varint]
+ * ([typeIdLength: varint] [typeId: string] [componentData])...
+ *
+ * @param entity - @zh 实体 @en Entity
+ * @param writer - @zh 二进制写入器 @en Binary writer
+ * @param deltaOnly - @zh 只编码增量 @en Only encode delta
+ * @returns @zh 编码的组件数量 @en Number of components encoded
+ */
+declare function encodeEntity(entity: Entity, writer: BinaryWriter, deltaOnly?: boolean): number;
+/**
+ * @zh 编码状态快照（多个实体）
+ * @en Encode state snapshot (multiple entities)
+ *
+ * @zh 格式:
+ * [operation: uint8] (FULL=0, DELTA=1, SPAWN=2, DESPAWN=3)
+ * [entityCount: varint]
+ * (entityData)...
+ *
+ * @en Format:
+ * [operation: uint8] (FULL=0, DELTA=1, SPAWN=2, DESPAWN=3)
+ * [entityCount: varint]
+ * (entityData)...
+ *
+ * @param entities - @zh 要编码的实体数组 @en Entities to encode
+ * @param operation - @zh 同步操作类型 @en Sync operation type
+ * @returns @zh 编码后的二进制数据 @en Encoded binary data
+ */
+declare function encodeSnapshot(entities: Entity[], operation?: SyncOperation): Uint8Array;
+/**
+ * @zh 编码实体生成消息
+ * @en Encode entity spawn message
+ *
+ * @param entity - @zh 生成的实体 @en Spawned entity
+ * @param prefabType - @zh 预制体类型（可选）@en Prefab type (optional)
+ * @returns @zh 编码后的二进制数据 @en Encoded binary data
+ */
+declare function encodeSpawn(entity: Entity, prefabType?: string): Uint8Array;
+/**
+ * @zh 编码实体销毁消息
+ * @en Encode entity despawn message
+ *
+ * @param entityId - @zh 销毁的实体 ID @en Despawned entity ID
+ * @returns @zh 编码后的二进制数据 @en Encoded binary data
+ */
+declare function encodeDespawn(entityId: number): Uint8Array;
+/**
+ * @zh 编码批量实体销毁消息
+ * @en Encode batch entity despawn message
+ *
+ * @param entityIds - @zh 销毁的实体 ID 数组 @en Despawned entity IDs
+ * @returns @zh 编码后的二进制数据 @en Encoded binary data
+ */
+declare function encodeDespawnBatch(entityIds: number[]): Uint8Array;
+
+/**
+ * @zh 组件状态解码器
+ * @en Component state decoder
+ *
+ * @zh 从二进制格式解码并应用到 ECS Component
+ * @en Decodes binary format and applies to ECS Components
+ */
+
+/**
+ * @zh 解码并应用组件数据
+ * @en Decode and apply component data
+ *
+ * @param component - @zh 组件实例 @en Component instance
+ * @param metadata - @zh 组件同步元数据 @en Component sync metadata
+ * @param reader - @zh 二进制读取器 @en Binary reader
+ */
+declare function decodeComponent(component: Component, metadata: SyncMetadata, reader: BinaryReader): void;
+/**
+ * @zh 解码实体快照结果
+ * @en Decode entity snapshot result
+ */
+interface DecodeEntityResult {
+    /**
+     * @zh 实体 ID
+     * @en Entity ID
+     */
+    entityId: number;
+    /**
+     * @zh 是否为新实体
+     * @en Whether it's a new entity
+     */
+    isNew: boolean;
+    /**
+     * @zh 解码的组件类型列表
+     * @en List of decoded component types
+     */
+    componentTypes: string[];
+}
+/**
+ * @zh 解码并应用实体数据
+ * @en Decode and apply entity data
+ *
+ * @param scene - @zh 场景 @en Scene
+ * @param reader - @zh 二进制读取器 @en Binary reader
+ * @param entityMap - @zh 实体 ID 映射（可选）@en Entity ID mapping (optional)
+ * @returns @zh 解码结果 @en Decode result
+ */
+declare function decodeEntity(scene: Scene, reader: BinaryReader, entityMap?: Map<number, Entity>): DecodeEntityResult;
+/**
+ * @zh 解码快照结果
+ * @en Decode snapshot result
+ */
+interface DecodeSnapshotResult {
+    /**
+     * @zh 操作类型
+     * @en Operation type
+     */
+    operation: SyncOperation;
+    /**
+     * @zh 解码的实体列表
+     * @en List of decoded entities
+     */
+    entities: DecodeEntityResult[];
+}
+/**
+ * @zh 解码状态快照
+ * @en Decode state snapshot
+ *
+ * @param scene - @zh 场景 @en Scene
+ * @param data - @zh 二进制数据 @en Binary data
+ * @param entityMap - @zh 实体 ID 映射（可选）@en Entity ID mapping (optional)
+ * @returns @zh 解码结果 @en Decode result
+ */
+declare function decodeSnapshot(scene: Scene, data: Uint8Array, entityMap?: Map<number, Entity>): DecodeSnapshotResult;
+/**
+ * @zh 解码生成消息结果
+ * @en Decode spawn message result
+ */
+interface DecodeSpawnResult {
+    /**
+     * @zh 实体
+     * @en Entity
+     */
+    entity: Entity;
+    /**
+     * @zh 预制体类型
+     * @en Prefab type
+     */
+    prefabType: string;
+    /**
+     * @zh 解码的组件类型列表
+     * @en List of decoded component types
+     */
+    componentTypes: string[];
+}
+/**
+ * @zh 解码实体生成消息
+ * @en Decode entity spawn message
+ *
+ * @param scene - @zh 场景 @en Scene
+ * @param data - @zh 二进制数据 @en Binary data
+ * @param entityMap - @zh 实体 ID 映射（可选）@en Entity ID mapping (optional)
+ * @returns @zh 解码结果，如果不是 SPAWN 消息则返回 null @en Decode result, or null if not a SPAWN message
+ */
+declare function decodeSpawn(scene: Scene, data: Uint8Array, entityMap?: Map<number, Entity>): DecodeSpawnResult | null;
+/**
+ * @zh 解码销毁消息结果
+ * @en Decode despawn message result
+ */
+interface DecodeDespawnResult {
+    /**
+     * @zh 销毁的实体 ID 列表
+     * @en List of despawned entity IDs
+     */
+    entityIds: number[];
+}
+/**
+ * @zh 解码实体销毁消息
+ * @en Decode entity despawn message
+ *
+ * @param data - @zh 二进制数据 @en Binary data
+ * @returns @zh 解码结果，如果不是 DESPAWN 消息则返回 null @en Decode result, or null if not a DESPAWN message
+ */
+declare function decodeDespawn(data: Uint8Array): DecodeDespawnResult | null;
+/**
+ * @zh 处理销毁消息（从场景中移除实体）
+ * @en Process despawn message (remove entities from scene)
+ *
+ * @param scene - @zh 场景 @en Scene
+ * @param data - @zh 二进制数据 @en Binary data
+ * @param entityMap - @zh 实体 ID 映射（可选）@en Entity ID mapping (optional)
+ * @returns @zh 移除的实体 ID 列表 @en List of removed entity IDs
+ */
+declare function processDespawn(scene: Scene, data: Uint8Array, entityMap?: Map<number, Entity>): number[];
+
 type ITimer<TContext = unknown> = {
     context: TContext;
     /**
@@ -16261,5 +17112,5 @@ declare function getFullPlatformConfig(): Promise<any>;
 declare function supportsFeature(feature: 'worker' | 'shared-array-buffer' | 'transferable-objects' | 'module-worker'): boolean;
 declare function hasAdapter(): boolean;
 
-export { AdvancedProfilerCollector, After, AutoProfiler, Before, BinarySerializer, BitMask64Utils, Bits, COMPONENT_DEPENDENCIES, COMPONENT_EDITOR_OPTIONS, COMPONENT_TYPE_NAME, ChangeOperation, Colors, CommandBuffer, CommandType, CompiledQuery, Component, ComponentDataCollector, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSerializer, ComponentSparseSet, ComponentStorage, ConsoleLogger, Core, CycleDependencyError, DEFAULT_PROFILER_CONFIG, DEFAULT_STAGE_ORDER, DebugConfigService, DebugManager, DebugPlugin, DeepCopy, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EEntityLifecyclePolicy, EMPTY_GUID, ENTITY_REF_METADATA, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityHandleManager, EntityList, EntityProcessorList, EntityRef, EntitySerializer, EntitySystem, EntityTags, EpochManager, EventBus, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GEN_BITS, GEN_MASK, GlobalComponentRegistry, GlobalEventBus, GlobalManager, HierarchyComponent, HierarchySystem, INDEX_BITS, INDEX_MASK, IdentifierPool, IgnoreSerialization, InSet, IncrementalSerializer, InjectProperty, Injectable, Int16, Int32, Int8, IntervalSystem, LogLevel, Logger, LoggerManager, MAX_ENTITIES, MAX_GENERATION, Matcher, MigrationBuilder, NULL_HANDLE, NumberExtension, PREFAB_FORMAT_VERSION, PROPERTY_METADATA, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, PlatformDetector, PlatformManager, PlatformWorkerPool, PluginManager, PluginServiceRegistry, PluginState, Pool, PoolManager, PrefabInstanceComponent, PrefabSerializer, ProcessingSystem, Profile, ProfileCategory, ProfileClass, ProfilerSDK, Property, QuerySystem, ReactiveQuery, ReactiveQueryChangeType, ReferenceTracker, RuntimeModeService, RuntimeModeToken, SCHEDULING_METADATA, SERIALIZABLE_METADATA, SERIALIZE_FIELD, SERIALIZE_OPTIONS, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SceneManager, SceneSerializer, Serializable, SerializationContext, Serialize, SerializeArray, SerializeAsMap, SerializeAsSet, SerializeMap, SerializeSet, ServiceContainer, ServiceLifetime, SoAStorage, SparseSet, Stage, SystemDataCollector, SystemDependencyGraph, SystemScheduler, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, TypedEntityBuilder, TypedQueryBuilder, TypedQueryResult, Uint16, Uint32, Uint8, Uint8Clamped, Updatable, ValueSerializer, VersionMigrationManager, WebSocketManager, WorkerEntitySystem, World, WorldManager, addAndConfigure, addEntityTag, buildEntity, createECSAPI, createEditorModeService, createInstance, createLogger, createQuery, createServiceToken, createStandaloneModeService, genOf, generateGUID, getBasicWorkerConfig, getComponentDependencies, getComponentEditorOptions, getComponentInstanceEditorOptions, getComponentInstanceTypeName, getComponentTypeName, getComponents, getCurrentAdapter, getEntityRefMetadata, getEntityRefProperties, getFullPlatformConfig, getGlobalWithMiniGame, getOrAddComponent, getPerformanceWithMemory, getPropertyInjectMetadata, getPropertyMetadata, getSceneByEntityId, getSchedulingMetadata, getSerializationMetadata, getSystemInstanceMetadata, getSystemInstanceTypeName, getSystemMetadata, getSystemTypeName, getUpdatableMetadata, handleEquals, handleToString, hasAdapter, hasAnyComponent, hasComponents, hasECSComponentDecorator, hasEntityRef, hasEntityTag, hasPropertyMetadata, hasSchedulingMetadata, indexOf, injectProperties, isComponentArray, isComponentHiddenInInspector, isComponentInstanceHiddenInInspector, isComponentType, isEntityRefProperty, isFolder, isHidden, isLocked, isSerializable, isUpdatable, isValidGUID, isValidHandle, makeHandle, queryFor, queryForAll, registerInjectable, registerPlatformAdapter, removeEntityTag, requireComponent, resetLoggerColors, setGlobalLogLevel, setLoggerColors, setLoggerFactory, supportsFeature, tryGetComponent, updateComponent };
-export type { AnyComponentConstructor, AutoProfilerConfig, BitMask64Data, CallGraphNode, ComponentChange, ComponentConstructor, ComponentDebugInfo, ComponentEditorOptions, ComponentInstance, ComponentMigrationFunction, ComponentOptions, ComponentType, ComponentTypeMap, ComponentTypeName, ComponentTypeNames, ComponentTypeWithMetadata, DataOnly, DeepPartial, DeepReadonly, DeferredCommand, DeserializationStrategy, ECSDebugStats, EntityChange, EntityDebugInfo, EntityHandle, EntityRefMetadata, EntityRefRecord, EntityTagValue, EntityWithComponents, EnumOption, EventListenerConfig, EventStats, ExtractComponents, FieldSerializeOptions, IAdvancedProfilerData, IAlipayMiniGameAPI, IBaiduMiniGameAPI, IByteDanceMiniGameAPI, IChromeMemoryInfo, IComponent, IComponentDebugData, IComponentEventData, IComponentRegistry, IComponentTypeMetadata, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, IGlobalThisWithMiniGame, ILogger, IMiniGamePlatformAPI, IPerformanceDebugData, IPerformanceEventData, IPerformanceWithMemory, IPlatformAdapter, IPlugin, IPluginMetadata, IPoolable, IRuntimeMode, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, IService, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IUpdatable, IWeChatMiniGameAPI, IWorkerPoolStatus, IWorkerSystemConfig, IWorldConfig, IWorldManagerConfig, IncrementalSerializationFormat, IncrementalSerializationOptions, IncrementalSnapshot, InjectableMetadata, InstanceTypes, LoggerColorConfig, LoggerConfig, LongTaskInfo, MemorySnapshot, MigrationFunction, PartialComponent, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PlatformConfig, PlatformDetectionResult, PlatformWorker, PoolStats, PrefabComponentTypeEntry, PrefabCreateOptions, PrefabData, PrefabInstantiateOptions, PrefabMetadata, ProcessingMode, ProfileCounter, ProfileFrame, ProfileReport, ProfileSample, ProfileSampleStats, ProfilerConfig, PropertyAction, PropertyAssetType, PropertyControl, PropertyOptions, PropertyType, QueryResult$1 as QueryResult, ReactiveQueryChange, ReactiveQueryConfig, ReactiveQueryListener, ReadonlyComponent, RuntimeModeConfig, SampleHandle, SceneDataChange, SceneDebugInfo, SceneDeserializationOptions, SceneMigrationFunction, SceneSerializationOptions, SerializableComponent, SerializableFields, SerializableOptions, SerializableValue, SerializationFormat, SerializationMetadata, SerializedComponent, SerializedEntity, SerializedEntityRef, SerializedPrefabEntity, SerializedScene, ServiceIdentifier, ServiceToken, ServiceType, SharedArrayBufferProcessFunction, SupportedTypedArray, SystemDebugInfo, SystemDependencyInfo, SystemEntityType, SystemLifecycleHooks, SystemMetadata, SystemSchedulingMetadata, SystemStage, TypeDef as TypeHandler, TypeSafeBuilder, TypedEventHandler, TypedQueryCondition, TypedValue, UpdatableMetadata, ValidComponent, ValidComponentArray, WorkerCreationOptions, WorkerProcessFunction, WorkerSystemConfig };
+export { AdvancedProfilerCollector, After, AutoProfiler, Before, BinaryReader, BinarySerializer, BinaryWriter, BitMask64Utils, Bits, CHANGE_TRACKER, COMPONENT_DEPENDENCIES, COMPONENT_EDITOR_OPTIONS, COMPONENT_TYPE_NAME, ChangeOperation, ChangeTracker, Colors, CommandBuffer, CommandType, CompiledQuery, Component, ComponentDataCollector, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSerializer, ComponentSparseSet, ComponentStorage, ConsoleLogger, Core, CycleDependencyError, DEFAULT_PROFILER_CONFIG, DEFAULT_STAGE_ORDER, DebugConfigService, DebugManager, DebugPlugin, DeepCopy, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EEntityLifecyclePolicy, EMPTY_GUID, ENTITY_REF_METADATA, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityHandleManager, EntityList, EntityProcessorList, EntityRef, EntitySerializer, EntitySystem, EntityTags, EpochManager, EventBus, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GEN_BITS, GEN_MASK, GlobalComponentRegistry, GlobalEventBus, GlobalManager, HierarchyComponent, HierarchySystem, INDEX_BITS, INDEX_MASK, IdentifierPool, IgnoreSerialization, InSet, IncrementalSerializer, InjectProperty, Injectable, Int16, Int32, Int8, IntervalSystem, LogLevel, Logger, LoggerManager, MAX_ENTITIES, MAX_GENERATION, Matcher, MigrationBuilder, NULL_HANDLE, NumberExtension, PREFAB_FORMAT_VERSION, PROPERTY_METADATA, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, PlatformDetector, PlatformManager, PlatformWorkerPool, PluginManager, PluginServiceRegistry, PluginState, Pool, PoolManager, PrefabInstanceComponent, PrefabSerializer, ProcessingSystem, Profile, ProfileCategory, ProfileClass, ProfilerSDK, Property, QuerySystem, ReactiveQuery, ReactiveQueryChangeType, ReferenceTracker, RuntimeModeService, RuntimeModeToken, SCHEDULING_METADATA, SERIALIZABLE_METADATA, SERIALIZE_FIELD, SERIALIZE_OPTIONS, SYNC_METADATA, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SceneManager, SceneSerializer, Serializable, SerializationContext, Serialize, SerializeArray, SerializeAsMap, SerializeAsSet, SerializeMap, SerializeSet, ServiceContainer, ServiceLifetime, SoAStorage, SparseSet, Stage, SyncOperation, SystemDataCollector, SystemDependencyGraph, SystemScheduler, TYPE_SIZES, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, TypedEntityBuilder, TypedQueryBuilder, TypedQueryResult, Uint16, Uint32, Uint8, Uint8Clamped, Updatable, ValueSerializer, VersionMigrationManager, WebSocketManager, WorkerEntitySystem, World, WorldManager, addAndConfigure, addEntityTag, buildEntity, clearChanges, createECSAPI, createEditorModeService, createInstance, createLogger, createQuery, createServiceToken, createStandaloneModeService, decodeComponent, decodeDespawn, decodeEntity, decodeSignedVarint, decodeSnapshot, decodeSpawn, decodeVarint, encodeComponentDelta, encodeComponentFull, encodeDespawn, encodeDespawnBatch, encodeEntity, encodeSignedVarint, encodeSnapshot, encodeSpawn, encodeVarint, genOf, generateGUID, getBasicWorkerConfig, getChangeTracker, getComponentDependencies, getComponentEditorOptions, getComponentInstanceEditorOptions, getComponentInstanceTypeName, getComponentTypeName, getComponents, getCurrentAdapter, getEntityRefMetadata, getEntityRefProperties, getFullPlatformConfig, getGlobalWithMiniGame, getOrAddComponent, getPerformanceWithMemory, getPropertyInjectMetadata, getPropertyMetadata, getSceneByEntityId, getSchedulingMetadata, getSerializationMetadata, getSyncMetadata, getSystemInstanceMetadata, getSystemInstanceTypeName, getSystemMetadata, getSystemTypeName, getUpdatableMetadata, handleEquals, handleToString, hasAdapter, hasAnyComponent, hasChanges, hasComponents, hasECSComponentDecorator, hasEntityRef, hasEntityTag, hasPropertyMetadata, hasSchedulingMetadata, hasSyncFields, indexOf, initChangeTracker, injectProperties, isComponentArray, isComponentHiddenInInspector, isComponentInstanceHiddenInInspector, isComponentType, isEntityRefProperty, isFolder, isHidden, isLocked, isSerializable, isUpdatable, isValidGUID, isValidHandle, makeHandle, processDespawn, queryFor, queryForAll, registerInjectable, registerPlatformAdapter, removeEntityTag, requireComponent, resetLoggerColors, setGlobalLogLevel, setLoggerColors, setLoggerFactory, supportsFeature, sync, tryGetComponent, updateComponent, varintSize, zigzagDecode, zigzagEncode };
+export type { AnyComponentConstructor, AutoProfilerConfig, BitMask64Data, CallGraphNode, ComponentChange, ComponentConstructor, ComponentDebugInfo, ComponentEditorOptions, ComponentInstance, ComponentMigrationFunction, ComponentOptions, ComponentType, ComponentTypeMap, ComponentTypeName, ComponentTypeNames, ComponentTypeWithMetadata, DataOnly, DecodeDespawnResult, DecodeEntityResult, DecodeSnapshotResult, DecodeSpawnResult, DeepPartial, DeepReadonly, DeferredCommand, DeserializationStrategy, ECSDebugStats, EntityChange, EntityDebugInfo, EntityHandle, EntityRefMetadata, EntityRefRecord, EntityTagValue, EntityWithComponents, EnumOption, EventListenerConfig, EventStats, ExtractComponents, FieldSerializeOptions, IAdvancedProfilerData, IAlipayMiniGameAPI, IBaiduMiniGameAPI, IByteDanceMiniGameAPI, IChromeMemoryInfo, IComponent, IComponentDebugData, IComponentEventData, IComponentRegistry, IComponentTypeMetadata, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, IGlobalThisWithMiniGame, ILogger, IMiniGamePlatformAPI, IPerformanceDebugData, IPerformanceEventData, IPerformanceWithMemory, IPlatformAdapter, IPlugin, IPluginMetadata, IPoolable, IRuntimeMode, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, IService, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IUpdatable, IWeChatMiniGameAPI, IWorkerPoolStatus, IWorkerSystemConfig, IWorldConfig, IWorldManagerConfig, IncrementalSerializationFormat, IncrementalSerializationOptions, IncrementalSnapshot, InjectableMetadata, InstanceTypes, LoggerColorConfig, LoggerConfig, LongTaskInfo, MemorySnapshot, MigrationFunction, PartialComponent, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PlatformConfig, PlatformDetectionResult, PlatformWorker, PoolStats, PrefabComponentTypeEntry, PrefabCreateOptions, PrefabData, PrefabInstantiateOptions, PrefabMetadata, ProcessingMode, ProfileCounter, ProfileFrame, ProfileReport, ProfileSample, ProfileSampleStats, ProfilerConfig, PropertyAction, PropertyAssetType, PropertyControl, PropertyOptions, PropertyType, QueryResult$1 as QueryResult, ReactiveQueryChange, ReactiveQueryConfig, ReactiveQueryListener, ReadonlyComponent, RuntimeModeConfig, SampleHandle, SceneDataChange, SceneDebugInfo, SceneDeserializationOptions, SceneMigrationFunction, SceneSerializationOptions, SerializableComponent, SerializableFields, SerializableOptions, SerializableValue, SerializationFormat, SerializationMetadata, SerializedComponent, SerializedEntity, SerializedEntityRef, SerializedPrefabEntity, SerializedScene, ServiceIdentifier, ServiceToken, ServiceType, SharedArrayBufferProcessFunction, SupportedTypedArray, SyncFieldMetadata, SyncMetadata, SyncType, SystemDebugInfo, SystemDependencyInfo, SystemEntityType, SystemLifecycleHooks, SystemMetadata, SystemSchedulingMetadata, SystemStage, TypeDef as TypeHandler, TypeSafeBuilder, TypedEventHandler, TypedQueryCondition, TypedValue, UpdatableMetadata, ValidComponent, ValidComponentArray, WorkerCreationOptions, WorkerProcessFunction, WorkerSystemConfig };