@esengine/network 2.2.0 → 3.0.0

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/index.d.ts

@@ -14,4 +14,6 @@ export type { IInputSnapshot, IPredictedState, IPredictor, ClientPredictionConfi
 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;AAM9E,YAAY,EACR,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACH,UAAU,EACV,oBAAoB,EACpB,0BAA0B,EAC7B,MAAM,cAAc,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esengine/network",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Network synchronization for multiplayer games",
   "esengine": {
     "plugin": true,
@@ -24,12 +24,21 @@
   "dependencies": {
     "@esengine/rpc": "1.1.1"
   },
+  "peerDependencies": {
+    "@esengine/ecs-framework": "2.5.0",
+    "@esengine/blueprint": "2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@esengine/blueprint": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "rimraf": "^5.0.5",
     "tsup": "^8.0.0",
     "typescript": "^5.3.3",
-    "@esengine/blueprint": "1.0.2",
-    "@esengine/ecs-framework": "2.4.4",
+    "@esengine/blueprint": "2.0.0",
+    "@esengine/ecs-framework": "2.5.0",
     "@esengine/build-config": "1.0.0"
   },
   "keywords": [