@esengine/network 2.1.1 → 3.0.0

package/dist/protocol.d.ts

@@ -10,11 +10,21 @@
  * @en Player input
  */
 export interface PlayerInput {
+    /**
+     * @zh 输入序列号（用于客户端预测）
+     * @en Input sequence number (for client prediction)
+     */
+    seq: number;
     /**
      * @zh 帧序号
      * @en Frame number
      */
     frame: number;
+    /**
+     * @zh 客户端时间戳
+     * @en Client timestamp
+     */
+    timestamp: number;
     /**
      * @zh 移动方向
      * @en Move direction
@@ -34,12 +44,42 @@ export interface PlayerInput {
  * @en Entity sync state
  */
 export interface EntitySyncState {
+    /**
+     * @zh 网络实体 ID
+     * @en Network entity ID
+     */
     netId: number;
+    /**
+     * @zh 位置
+     * @en Position
+     */
     pos?: {
         x: number;
         y: number;
     };
+    /**
+     * @zh 旋转角度
+     * @en Rotation angle
+     */
     rot?: number;
+    /**
+     * @zh 速度（用于外推）
+     * @en Velocity (for extrapolation)
+     */
+    vel?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * @zh 角速度
+     * @en Angular velocity
+     */
+    angVel?: number;
+    /**
+     * @zh 自定义数据
+     * @en Custom data
+     */
+    custom?: Record<string, unknown>;
 }
 /**
  * @zh 同步消息
@@ -51,6 +91,16 @@ export interface SyncData {
      * @en Server frame number
      */
     frame: number;
+    /**
+     * @zh 服务器时间戳（用于插值）
+     * @en Server timestamp (for interpolation)
+     */
+    timestamp: number;
+    /**
+     * @zh 已确认的输入序列号（用于客户端预测校正）
+     * @en Acknowledged input sequence (for client prediction reconciliation)
+     */
+    ackSeq?: number;
     /**
      * @zh 实体状态列表
      * @en Entity state list
@@ -78,6 +128,29 @@ export interface SpawnData {
 export interface DespawnData {
     netId: number;
 }
+/**
+ * @zh 完整状态快照（用于重连）
+ * @en Full state snapshot (for reconnection)
+ */
+export interface FullStateData {
+    /**
+     * @zh 服务器帧号
+     * @en Server frame number
+     */
+    frame: number;
+    /**
+     * @zh 服务器时间戳
+     * @en Server timestamp
+     */
+    timestamp: number;
+    /**
+     * @zh 所有实体状态
+     * @en All entity states
+     */
+    entities: Array<SpawnData & {
+        state?: EntitySyncState;
+    }>;
+}
 /**
  * @zh 加入房间请求
  * @en Join room request
@@ -94,6 +167,48 @@ export interface JoinResponse {
     playerId: number;
     roomId: string;
 }
+/**
+ * @zh 重连请求
+ * @en Reconnect request
+ */
+export interface ReconnectRequest {
+    /**
+     * @zh 之前的玩家 ID
+     * @en Previous player ID
+     */
+    playerId: number;
+    /**
+     * @zh 房间 ID
+     * @en Room ID
+     */
+    roomId: string;
+    /**
+     * @zh 重连令牌
+     * @en Reconnection token
+     */
+    token: string;
+}
+/**
+ * @zh 重连响应
+ * @en Reconnect response
+ */
+export interface ReconnectResponse {
+    /**
+     * @zh 是否成功
+     * @en Whether successful
+     */
+    success: boolean;
+    /**
+     * @zh 完整状态（成功时）
+     * @en Full state (when successful)
+     */
+    state?: FullStateData;
+    /**
+     * @zh 错误信息（失败时）
+     * @en Error message (when failed)
+     */
+    error?: string;
+}
 /**
  * @zh 默认游戏网络协议
  * @en Default game network protocol
@@ -128,6 +243,11 @@ export declare const gameProtocol: {
          * @en Leave room
          */
         leave: import("@esengine/rpc").ApiDef<void, void>;
+        /**
+         * @zh 重连
+         * @en Reconnect
+         */
+        reconnect: import("@esengine/rpc").ApiDef<ReconnectRequest, ReconnectResponse>;
     };
     msg: {
         /**
@@ -150,6 +270,11 @@ export declare const gameProtocol: {
          * @en Entity despawn
          */
         despawn: import("@esengine/rpc").MsgDef<DespawnData>;
+        /**
+         * @zh 完整状态快照
+         * @en Full state snapshot
+         */
+        fullState: import("@esengine/rpc").MsgDef<FullStateData>;
     };
 };
 /**

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAElC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACrB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAA;CAChB;AAMD;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,YAAY;;QAEjB;;;WAGG;;QAGH;;;WAGG;;;;QAIH;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;;CAGT,CAAA;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAA"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/sync/ComponentSync.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @zh 组件同步系统
+ * @en Component Sync System
+ *
+ * @zh 基于 @sync 装饰器的组件状态同步，与 ecs-framework 的 Sync 模块集成
+ * @en Component state synchronization based on @sync decorator, integrated with ecs-framework Sync module
+ */
+import { EntitySystem, type Entity, type DecodeSnapshotResult, type DecodeSpawnResult } from '@esengine/ecs-framework';
+/**
+ * @zh 组件同步事件类型
+ * @en Component sync event type
+ */
+export type ComponentSyncEventType = 'entitySpawned' | 'entityDespawned' | 'stateUpdated';
+/**
+ * @zh 组件同步事件
+ * @en Component sync event
+ */
+export interface ComponentSyncEvent {
+    type: ComponentSyncEventType;
+    entityId: number;
+    prefabType?: string;
+}
+/**
+ * @zh 组件同步事件监听器
+ * @en Component sync event listener
+ */
+export type ComponentSyncEventListener = (event: ComponentSyncEvent) => void;
+/**
+ * @zh 组件同步配置
+ * @en Component sync configuration
+ */
+export interface ComponentSyncConfig {
+    /**
+     * @zh 是否启用增量同步
+     * @en Whether to enable delta sync
+     */
+    enableDeltaSync: boolean;
+    /**
+     * @zh 同步间隔（毫秒）
+     * @en Sync interval in milliseconds
+     */
+    syncInterval: number;
+}
+/**
+ * @zh 组件同步系统
+ * @en Component sync system
+ *
+ * @zh 基于 @sync 装饰器自动同步组件状态
+ * @en Automatically syncs component state based on @sync decorator
+ *
+ * @example
+ * ```typescript
+ * // Server-side: broadcast state
+ * const syncSystem = scene.getSystem(ComponentSyncSystem);
+ * const data = syncSystem.encodeAllEntities(false); // delta
+ * broadcast(data);
+ *
+ * // Client-side: receive state
+ * const syncSystem = scene.getSystem(ComponentSyncSystem);
+ * syncSystem.applySnapshot(data);
+ * ```
+ */
+export declare class ComponentSyncSystem extends EntitySystem {
+    private readonly _config;
+    private readonly _syncEntityMap;
+    private readonly _syncListeners;
+    private _lastSyncTime;
+    private _isServer;
+    constructor(config?: Partial<ComponentSyncConfig>, isServer?: boolean);
+    /**
+     * @zh 设置是否为服务端模式
+     * @en Set whether in server mode
+     */
+    set isServer(value: boolean);
+    /**
+     * @zh 获取是否为服务端模式
+     * @en Get whether in server mode
+     */
+    get isServer(): boolean;
+    /**
+     * @zh 获取配置
+     * @en Get configuration
+     */
+    get config(): Readonly<ComponentSyncConfig>;
+    /**
+     * @zh 添加同步事件监听器
+     * @en Add sync event listener
+     */
+    addSyncListener(listener: ComponentSyncEventListener): void;
+    /**
+     * @zh 移除同步事件监听器
+     * @en Remove sync event listener
+     */
+    removeSyncListener(listener: ComponentSyncEventListener): void;
+    /**
+     * @zh 注册同步组件类型
+     * @en Register sync component type
+     *
+     * @zh 客户端需要调用此方法注册所有需要同步的组件类型
+     * @en Client needs to call this to register all component types to be synced
+     */
+    registerComponent<T extends new () => any>(componentClass: T): void;
+    /**
+     * @zh 编码所有实体状态
+     * @en Encode all entities state
+     *
+     * @param fullSync - @zh 是否完整同步（首次连接时使用）@en Whether to do full sync (for initial connection)
+     * @returns @zh 编码后的二进制数据 @en Encoded binary data
+     */
+    encodeAllEntities(fullSync?: boolean): Uint8Array;
+    /**
+     * @zh 编码有变更的实体
+     * @en Encode entities with changes
+     *
+     * @returns @zh 编码后的二进制数据，如果没有变更返回 null @en Encoded binary data, or null if no changes
+     */
+    encodeDelta(): Uint8Array | null;
+    /**
+     * @zh 编码实体生成消息
+     * @en Encode entity spawn message
+     */
+    encodeSpawn(entity: Entity, prefabType?: string): Uint8Array;
+    /**
+     * @zh 编码实体销毁消息
+     * @en Encode entity despawn message
+     */
+    encodeDespawn(entityId: number): Uint8Array;
+    /**
+     * @zh 应用状态快照
+     * @en Apply state snapshot
+     *
+     * @param data - @zh 二进制数据 @en Binary data
+     * @returns @zh 解码结果 @en Decode result
+     */
+    applySnapshot(data: Uint8Array): DecodeSnapshotResult;
+    /**
+     * @zh 应用实体生成消息
+     * @en Apply entity spawn message
+     *
+     * @param data - @zh 二进制数据 @en Binary data
+     * @returns @zh 解码结果，如果不是 SPAWN 消息返回 null @en Decode result, or null if not a SPAWN message
+     */
+    applySpawn(data: Uint8Array): DecodeSpawnResult | null;
+    /**
+     * @zh 应用实体销毁消息
+     * @en Apply entity despawn message
+     *
+     * @param data - @zh 二进制数据 @en Binary data
+     * @returns @zh 销毁的实体 ID 列表 @en List of despawned entity IDs
+     */
+    applyDespawn(data: Uint8Array): number[];
+    /**
+     * @zh 通过网络 ID 获取实体
+     * @en Get entity by network ID
+     */
+    getEntityById(entityId: number): Entity | undefined;
+    /**
+     * @zh 获取所有匹配的实体
+     * @en Get all matching entities
+     */
+    getMatchingEntities(): Entity[];
+    protected process(entities: readonly Entity[]): void;
+    private _hasChanges;
+    private _clearChangeTrackers;
+    private _emitEvent;
+    protected onDestroy(): void;
+}
+/**
+ * @zh 创建组件同步系统
+ * @en Create component sync system
+ */
+export declare function createComponentSyncSystem(config?: Partial<ComponentSyncConfig>, isServer?: boolean): ComponentSyncSystem;
+//# sourceMappingURL=ComponentSync.d.ts.map

package/dist/sync/ComponentSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentSync.d.ts","sourceRoot":"","sources":["../../src/sync/ComponentSync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACH,YAAY,EAEZ,KAAK,MAAM,EAeX,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACzB,MAAM,yBAAyB,CAAC;AAQjC;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAC5B,eAAe,GACf,iBAAiB,GACjB,cAAc,CAAC;AAErB;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACxB;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;IACjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8C;IAC7E,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,SAAS,CAAkB;gBAEvB,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,EAAE,QAAQ,GAAE,OAAe;IAM5E;;;OAGG;IACH,IAAW,QAAQ,CAAC,KAAK,EAAE,OAAO,EAEjC;IAED;;;OAGG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED;;;OAGG;IACH,IAAW,MAAM,IAAI,QAAQ,CAAC,mBAAmB,CAAC,CAEjD;IAED;;;OAGG;IACI,eAAe,CAAC,QAAQ,EAAE,0BAA0B,GAAG,IAAI;IAIlE;;;OAGG;IACI,kBAAkB,CAAC,QAAQ,EAAE,0BAA0B,GAAG,IAAI;IAIrE;;;;;;OAMG;IACI,iBAAiB,CAAC,CAAC,SAAS,UAAU,GAAG,EAAE,cAAc,EAAE,CAAC,GAAG,IAAI;IAW1E;;;;;;OAMG;IACI,iBAAiB,CAAC,QAAQ,GAAE,OAAe,GAAG,UAAU;IAc/D;;;;;OAKG;IACI,WAAW,IAAI,UAAU,GAAG,IAAI;IAcvC;;;OAGG;IACI,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU;IAInE;;;OAGG;IACI,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAQlD;;;;;;OAMG;IACI,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,oBAAoB;IAyB5D;;;;;;OAMG;IACI,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,GAAG,IAAI;IAkB7D;;;;;;OAMG;IACI,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE;IAqB/C;;;OAGG;IACI,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI1D;;;OAGG;IACI,mBAAmB,IAAI,MAAM,EAAE;cAQnB,OAAO,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAoB7D,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,UAAU;cAUC,SAAS,IAAI,IAAI;CAIvC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACrC,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,EACrC,QAAQ,GAAE,OAAe,GAC1B,mBAAmB,CAErB"}

package/dist/sync/StateDelta.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @zh 状态增量压缩
+ * @en State Delta Compression
+ *
+ * @zh 通过只发送变化的字段来减少网络带宽
+ * @en Reduces network bandwidth by only sending changed fields
+ */
+import type { SyncData } from '../protocol';
+/**
+ * @zh 增量类型标志
+ * @en Delta type flags
+ */
+export declare const DeltaFlags: {
+    readonly NONE: 0;
+    readonly POSITION: number;
+    readonly ROTATION: number;
+    readonly VELOCITY: number;
+    readonly ANGULAR_VELOCITY: number;
+    readonly CUSTOM: number;
+};
+/**
+ * @zh 增量状态（只包含变化的字段）
+ * @en Delta state (only contains changed fields)
+ */
+export interface EntityDeltaState {
+    /**
+     * @zh 网络标识
+     * @en Network identity
+     */
+    netId: number;
+    /**
+     * @zh 变化标志
+     * @en Change flags
+     */
+    flags: number;
+    /**
+     * @zh 位置（如果变化）
+     * @en Position (if changed)
+     */
+    pos?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * @zh 旋转（如果变化）
+     * @en Rotation (if changed)
+     */
+    rot?: number;
+    /**
+     * @zh 速度（如果变化）
+     * @en Velocity (if changed)
+     */
+    vel?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * @zh 角速度（如果变化）
+     * @en Angular velocity (if changed)
+     */
+    angVel?: number;
+    /**
+     * @zh 自定义数据（如果变化）
+     * @en Custom data (if changed)
+     */
+    custom?: Record<string, unknown>;
+}
+/**
+ * @zh 增量同步数据
+ * @en Delta sync data
+ */
+export interface DeltaSyncData {
+    /**
+     * @zh 帧号
+     * @en Frame number
+     */
+    frame: number;
+    /**
+     * @zh 时间戳
+     * @en Timestamp
+     */
+    timestamp: number;
+    /**
+     * @zh 已确认的输入序列号
+     * @en Acknowledged input sequence
+     */
+    ackSeq?: number;
+    /**
+     * @zh 增量实体状态
+     * @en Delta entity states
+     */
+    entities: EntityDeltaState[];
+    /**
+     * @zh 是否为完整快照
+     * @en Whether this is a full snapshot
+     */
+    isFullSnapshot?: boolean;
+}
+/**
+ * @zh 增量压缩配置
+ * @en Delta compression configuration
+ */
+export interface DeltaCompressionConfig {
+    /**
+     * @zh 位置变化阈值
+     * @en Position change threshold
+     */
+    positionThreshold: number;
+    /**
+     * @zh 旋转变化阈值（弧度）
+     * @en Rotation change threshold (radians)
+     */
+    rotationThreshold: number;
+    /**
+     * @zh 速度变化阈值
+     * @en Velocity change threshold
+     */
+    velocityThreshold: number;
+    /**
+     * @zh 强制完整快照间隔（帧数）
+     * @en Forced full snapshot interval (frames)
+     */
+    fullSnapshotInterval: number;
+}
+/**
+ * @zh 状态增量压缩器
+ * @en State delta compressor
+ *
+ * @zh 追踪实体状态变化，生成增量更新
+ * @en Tracks entity state changes and generates delta updates
+ */
+export declare class StateDeltaCompressor {
+    private readonly _config;
+    private readonly _lastStates;
+    private _frameCounter;
+    constructor(config?: Partial<DeltaCompressionConfig>);
+    /**
+     * @zh 获取配置
+     * @en Get configuration
+     */
+    get config(): Readonly<DeltaCompressionConfig>;
+    /**
+     * @zh 压缩同步数据为增量格式
+     * @en Compress sync data to delta format
+     */
+    compress(data: SyncData): DeltaSyncData;
+    /**
+     * @zh 解压增量数据为完整同步数据
+     * @en Decompress delta data to full sync data
+     */
+    decompress(data: DeltaSyncData): SyncData;
+    /**
+     * @zh 移除实体状态
+     * @en Remove entity state
+     */
+    removeEntity(netId: number): void;
+    /**
+     * @zh 清除所有状态
+     * @en Clear all states
+     */
+    clear(): void;
+    /**
+     * @zh 强制下一次发送完整快照
+     * @en Force next send to be a full snapshot
+     */
+    forceFullSnapshot(): void;
+    private _createFullDelta;
+    private _calculateDelta;
+    private _applyDelta;
+    private _customDataEqual;
+}
+/**
+ * @zh 创建状态增量压缩器
+ * @en Create state delta compressor
+ */
+export declare function createStateDeltaCompressor(config?: Partial<DeltaCompressionConfig>): StateDeltaCompressor;
+//# sourceMappingURL=StateDelta.d.ts.map

package/dist/sync/StateDelta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateDelta.d.ts","sourceRoot":"","sources":["../../src/sync/StateDelta.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAmB,QAAQ,EAAE,MAAM,aAAa,CAAA;AAM5D;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;CAOb,CAAA;AAEV;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,GAAG,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAE9B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,GAAG,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAE9B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAE5B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAA;IAEzB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAA;IAEzB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAA;IAEzB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAA;CAC/B;AAaD;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0C;IACtE,OAAO,CAAC,aAAa,CAAY;gBAErB,MAAM,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC;IAIpD;;;OAGG;IACH,IAAI,MAAM,IAAI,QAAQ,CAAC,sBAAsB,CAAC,CAE7C;IAED;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa;IAiCvC;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ;IAoBzC;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjC;;;OAGG;IACH,KAAK,IAAI,IAAI;IAKb;;;OAGG;IACH,iBAAiB,IAAI,IAAI;IAQzB,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,eAAe;IA2EvB,OAAO,CAAC,WAAW;IA8CnB,OAAO,CAAC,gBAAgB;CAkB3B;AAMD;;;GAGG;AACH,wBAAgB,0BAA0B,CACtC,MAAM,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GACzC,oBAAoB,CAEtB"}

package/dist/sync/index.d.ts

@@ -12,4 +12,8 @@ export { lerp, lerpAngle, smoothDamp } from './IInterpolator';
 export { TransformInterpolator, HermiteTransformInterpolator, createTransformInterpolator, createHermiteTransformInterpolator } from './TransformInterpolator';
 export type { IInputSnapshot, IPredictedState, IPredictor, ClientPredictionConfig } from './ClientPrediction';
 export { ClientPrediction, createClientPrediction } from './ClientPrediction';
+export type { EntityDeltaState, DeltaSyncData, DeltaCompressionConfig } from './StateDelta';
+export { DeltaFlags, StateDeltaCompressor, createStateDeltaCompressor } from './StateDelta';
+export type { ComponentSyncEventType, ComponentSyncEvent, ComponentSyncEventListener, ComponentSyncConfig } from './ComponentSync';
+export { ComponentSyncSystem, createComponentSyncSystem } from './ComponentSync';
 //# sourceMappingURL=index.d.ts.map

package/dist/sync/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,YAAY,EACR,cAAc,EACd,eAAe,EACf,2BAA2B,EAC3B,qBAAqB,EACrB,eAAe,EAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAMxE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,EACH,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,EAC3B,kCAAkC,EACrC,MAAM,yBAAyB,CAAC;AAMjC,YAAY,EACR,cAAc,EACd,eAAe,EACf,UAAU,EACV,sBAAsB,EACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,YAAY,EACR,cAAc,EACd,eAAe,EACf,2BAA2B,EAC3B,qBAAqB,EACrB,eAAe,EAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAMxE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,EACH,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,EAC3B,kCAAkC,EACrC,MAAM,yBAAyB,CAAC;AAMjC,YAAY,EACR,cAAc,EACd,eAAe,EACf,UAAU,EACV,sBAAsB,EACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAM9E,YAAY,EACR,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACH,UAAU,EACV,oBAAoB,EACpB,0BAA0B,EAC7B,MAAM,cAAc,CAAC;AAMtB,YAAY,EACR,sBAAsB,EACtB,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,EACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACH,mBAAmB,EACnB,yBAAyB,EAC5B,MAAM,iBAAiB,CAAC"}