@esengine/ecs-framework 2.2.20 → 2.3.0

package/bin/ECS/Serialization/IncrementalSerializer.d.ts

@@ -0,0 +1,259 @@
+/**
+ * 增量序列化器
+ *
+ * 提供高性能的增量序列化支持，只序列化变更的数据
+ * 适用于网络同步、大场景存档、时间回溯等场景
+ */
+import type { IScene } from '../IScene';
+import { SerializedComponent } from './ComponentSerializer';
+import { SerializedEntity } from './EntitySerializer';
+import { ComponentType } from '../Core/ComponentStorage';
+/**
+ * 变更操作类型
+ */
+export 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"
+}
+/**
+ * 实体变更记录
+ */
+export interface EntityChange {
+    /** 操作类型 */
+    operation: ChangeOperation;
+    /** 实体ID */
+    entityId: number;
+    /** 实体名称（用于Added操作） */
+    entityName?: string;
+    /** 实体数据（用于Added/Updated操作） */
+    entityData?: Partial<SerializedEntity>;
+}
+/**
+ * 组件变更记录
+ */
+export interface ComponentChange {
+    /** 操作类型 */
+    operation: ChangeOperation;
+    /** 实体ID */
+    entityId: number;
+    /** 组件类型名称 */
+    componentType: string;
+    /** 组件数据（用于Added/Updated操作） */
+    componentData?: SerializedComponent;
+}
+/**
+ * 场景数据变更记录
+ */
+export interface SceneDataChange {
+    /** 操作类型 */
+    operation: ChangeOperation;
+    /** 变更的键 */
+    key: string;
+    /** 新值 */
+    value: any;
+    /** 是否删除 */
+    deleted?: boolean;
+}
+/**
+ * 增量序列化数据
+ */
+export 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>;
+}
+/**
+ * 增量序列化格式
+ */
+export type IncrementalSerializationFormat = 'json' | 'binary';
+/**
+ * 增量序列化选项
+ */
+export interface IncrementalSerializationOptions {
+    /**
+     * 是否包含组件数据的深度对比
+     * 默认true，设为false可提升性能但可能漏掉组件内部字段变更
+     */
+    deepComponentComparison?: boolean;
+    /**
+     * 是否跟踪场景数据变更
+     * 默认true
+     */
+    trackSceneData?: boolean;
+    /**
+     * 是否压缩快照（使用JSON序列化）
+     * 默认false，设为true可减少内存占用但增加CPU开销
+     */
+    compressSnapshot?: boolean;
+    /**
+     * 序列化格式
+     * - 'json': JSON格式
+     * - 'binary': 二进制格式
+     * 默认 'json'
+     */
+    format?: IncrementalSerializationFormat;
+    /**
+     * 是否美化JSON输出（仅在format='json'时有效）
+     * 默认false
+     */
+    pretty?: boolean;
+}
+/**
+ * 增量序列化器类
+ */
+export 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字符串或二进制Uint8Array）
+     *
+     * @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 | Uint8Array;
+    /**
+     * 反序列化增量快照
+     *
+     * @param data 序列化的数据（JSON字符串或二进制Uint8Array）
+     * @returns 增量快照
+     *
+     * @example
+     * ```typescript
+     * // 从JSON反序列化
+     * const snapshot = IncrementalSerializer.deserializeIncremental(jsonString);
+     *
+     * // 从二进制反序列化
+     * const snapshot = IncrementalSerializer.deserializeIncremental(buffer);
+     * ```
+     */
+    static deserializeIncremental(data: string | Uint8Array): IncrementalSnapshot;
+    /**
+     * 获取增量快照的统计信息
+     *
+     * @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;
+}
+export {};
+//# sourceMappingURL=IncrementalSerializer.d.ts.map

package/bin/ECS/Serialization/IncrementalSerializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IncrementalSerializer.d.ts","sourceRoot":"","sources":["../../../src/ECS/Serialization/IncrementalSerializer.ts"],"names":[],"mappings":"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"}