新增增量序列化

examples/core-demos/src/demos/IncrementalSerializationDemo.ts

@@ -0,0 +1,438 @@
+import { DemoBase, DemoInfo } from './DemoBase';
+import {
+    Component,
+    ECSComponent,
+    EntitySystem,
+    Serializable,
+    Serialize,
+    IncrementalSerializer
+} from '@esengine/ecs-framework';
+
+// ===== 组件定义 =====
+@ECSComponent('IncDemo_Position')
+@Serializable({ version: 1, typeId: 'IncDemo_Position' })
+class PositionComponent extends Component {
+    @Serialize() x: number = 0;
+    @Serialize() y: number = 0;
+    constructor(x: number = 0, y: number = 0) {
+        super();
+        this.x = x;
+        this.y = y;
+    }
+}
+
+@ECSComponent('IncDemo_Velocity')
+@Serializable({ version: 1, typeId: 'IncDemo_Velocity' })
+class VelocityComponent extends Component {
+    @Serialize() vx: number = 0;
+    @Serialize() vy: number = 0;
+    constructor(vx: number = 0, vy: number = 0) {
+        super();
+        this.vx = vx;
+        this.vy = vy;
+    }
+}
+
+@ECSComponent('IncDemo_Renderable')
+@Serializable({ version: 1, typeId: 'IncDemo_Renderable' })
+class RenderableComponent extends Component {
+    @Serialize() color: string = '#ffffff';
+    @Serialize() radius: number = 10;
+    constructor(color: string = '#ffffff', radius: number = 10) {
+        super();
+        this.color = color;
+        this.radius = radius;
+    }
+}
+
+// ===== 系统定义 =====
+class MovementSystem extends EntitySystem {
+    update() {
+        if (!this.scene) return;
+        const entities = this.scene.entities.buffer;
+        for (const entity of entities) {
+            const pos = entity.getComponent(PositionComponent);
+            const vel = entity.getComponent(VelocityComponent);
+            if (pos && vel) {
+                pos.x += vel.vx;
+                pos.y += vel.vy;
+
+                if (pos.x < 0 || pos.x > 1200) vel.vx *= -1;
+                if (pos.y < 0 || pos.y > 600) vel.vy *= -1;
+            }
+        }
+    }
+}
+
+class RenderSystem extends EntitySystem {
+    private canvas: HTMLCanvasElement;
+    private ctx: CanvasRenderingContext2D;
+
+    constructor(canvas: HTMLCanvasElement) {
+        super();
+        this.canvas = canvas;
+        const ctx = canvas.getContext('2d');
+        if (!ctx) throw new Error('Failed to get canvas context');
+        this.ctx = ctx;
+    }
+
+    update() {
+        if (!this.scene) return;
+
+        this.ctx.fillStyle = '#0a0a15';
+        this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
+
+        const entities = this.scene.entities.buffer;
+        for (const entity of entities) {
+            const pos = entity.getComponent(PositionComponent);
+            const render = entity.getComponent(RenderableComponent);
+            if (pos && render) {
+                this.ctx.fillStyle = render.color;
+                this.ctx.beginPath();
+                this.ctx.arc(pos.x, pos.y, render.radius, 0, Math.PI * 2);
+                this.ctx.fill();
+
+                this.ctx.fillStyle = 'white';
+                this.ctx.font = '10px Arial';
+                this.ctx.textAlign = 'center';
+                this.ctx.fillText(entity.name, pos.x, pos.y - render.radius - 5);
+            }
+        }
+    }
+}
+
+export class IncrementalSerializationDemo extends DemoBase {
+    private renderSystem!: RenderSystem;
+    private incrementalHistory: any[] = [];
+    private autoSnapshotInterval: number | null = null;
+
+    getInfo(): DemoInfo {
+        return {
+            id: 'incremental-serialization',
+            name: '增量序列化',
+            description: '演示增量序列化功能，只保存场景变更而非完整状态，适用于网络同步和回放系统',
+            category: '核心功能',
+            icon: '🔄'
+        };
+    }
+
+    setup() {
+        // 创建控制面板
+        this.createControls();
+
+        // 添加系统
+        this.renderSystem = new RenderSystem(this.canvas);
+        this.scene.addEntityProcessor(new MovementSystem());
+        this.scene.addEntityProcessor(this.renderSystem);
+
+        // 创建初始实体
+        this.createInitialEntities();
+
+        // 创建基础快照
+        this.scene.createIncrementalSnapshot();
+        this.addToHistory('Initial State');
+    }
+
+    private createInitialEntities() {
+        // 创建玩家
+        const player = this.scene.createEntity('Player');
+        player.addComponent(new PositionComponent(600, 300));
+        player.addComponent(new VelocityComponent(2, 1.5));
+        player.addComponent(new RenderableComponent('#4a9eff', 15));
+
+        // 设置场景数据
+        this.scene.sceneData.set('gameTime', 0);
+        this.scene.sceneData.set('score', 0);
+    }
+
+    private createRandomEntity() {
+        const entity = this.scene.createEntity(`Entity_${Date.now()}`);
+        entity.addComponent(new PositionComponent(
+            Math.random() * this.canvas.width,
+            Math.random() * this.canvas.height
+        ));
+        entity.addComponent(new VelocityComponent(
+            (Math.random() - 0.5) * 3,
+            (Math.random() - 0.5) * 3
+        ));
+        const colors = ['#ff6b6b', '#4ecdc4', '#ffe66d', '#a8dadc', '#f1faee'];
+        entity.addComponent(new RenderableComponent(
+            colors[Math.floor(Math.random() * colors.length)],
+            5 + Math.random() * 10
+        ));
+    }
+
+    private addToHistory(label: string) {
+        const incremental = this.scene.serializeIncremental();
+        const stats = IncrementalSerializer.getIncrementalStats(incremental);
+
+        this.incrementalHistory.push({
+            label,
+            incremental,
+            stats,
+            timestamp: Date.now()
+        });
+
+        this.scene.updateIncrementalSnapshot();
+        this.updateHistoryPanel();
+        this.updateStats();
+    }
+
+    createControls() {
+        this.controlPanel.innerHTML = `
+            <div class="control-section">
+                <h4>实体控制</h4>
+                <div class="button-group">
+                    <button id="addEntity" class="secondary">添加随机实体</button>
+                    <button id="removeEntity" class="danger">删除最后一个实体</button>
+                    <button id="modifyEntity" class="secondary">修改实体数据</button>
+                </div>
+            </div>
+
+            <div class="control-section">
+                <h4>增量快照</h4>
+                <div class="button-group">
+                    <button id="captureSnapshot" class="success">捕获当前状态</button>
+                    <button id="clearHistory" class="danger">清空历史</button>
+                </div>
+                <div style="margin-top: 10px;">
+                    <label>
+                        <input type="checkbox" id="autoSnapshot">
+                        自动快照（每2秒）
+                    </label>
+                </div>
+            </div>
+
+            <div class="control-section">
+                <h4>场景数据控制</h4>
+                <div class="input-group">
+                    <label>游戏时间</label>
+                    <input type="number" id="gameTime" value="0" step="1">
+                </div>
+                <div class="input-group">
+                    <label>分数</label>
+                    <input type="number" id="score" value="0" step="10">
+                </div>
+                <button id="updateSceneData" class="secondary">更新场景数据</button>
+            </div>
+
+            <div class="stats-panel">
+                <div class="stat-item">
+                    <div class="stat-label">实体数量</div>
+                    <div class="stat-value" id="entityCount">0</div>
+                </div>
+                <div class="stat-item">
+                    <div class="stat-label">历史记录</div>
+                    <div class="stat-value" id="historyCount">0</div>
+                </div>
+                <div class="stat-item">
+                    <div class="stat-label">最后快照大小</div>
+                    <div class="stat-value" id="snapshotSize">0B</div>
+                </div>
+                <div class="stat-item">
+                    <div class="stat-label">总变更数</div>
+                    <div class="stat-value" id="totalChanges">0</div>
+                </div>
+            </div>
+
+            <div class="control-section">
+                <h4>增量历史 <small style="color: #8892b0;">(点击快照查看详情)</small></h4>
+                <div style="max-height: 300px; overflow-y: auto; background: rgba(0,0,0,0.3); padding: 10px; border-radius: 6px;" id="historyPanel">
+                    暂无历史记录
+                </div>
+            </div>
+
+            <div class="control-section">
+                <h4>快照详情</h4>
+                <div style="max-height: 200px; overflow-y: auto; background: rgba(0,0,0,0.3); padding: 10px; border-radius: 6px; font-family: monospace; font-size: 11px; color: #8892b0;" id="snapshotDetails">
+                    点击历史记录查看详情...
+                </div>
+            </div>
+        `;
+
+        this.bindEvents();
+        this.updateStats();
+    }
+
+    private bindEvents() {
+        document.getElementById('addEntity')!.addEventListener('click', () => {
+            this.createRandomEntity();
+            this.addToHistory('添加实体');
+            this.showToast('添加了一个随机实体');
+        });
+
+        document.getElementById('removeEntity')!.addEventListener('click', () => {
+            const entities = this.scene.entities.buffer;
+            if (entities.length > 1) {
+                const lastEntity = entities[entities.length - 1];
+                lastEntity.destroy();
+                this.addToHistory('删除实体');
+                this.showToast('删除了最后一个实体');
+            } else {
+                this.showToast('至少保留一个实体', '⚠️');
+            }
+        });
+
+        document.getElementById('modifyEntity')!.addEventListener('click', () => {
+            const entities = this.scene.entities.buffer;
+            if (entities.length > 0) {
+                const randomEntity = entities[Math.floor(Math.random() * entities.length)];
+                const pos = randomEntity.getComponent(PositionComponent);
+                if (pos) {
+                    pos.x = Math.random() * this.canvas.width;
+                    pos.y = Math.random() * this.canvas.height;
+                }
+                this.addToHistory('修改实体位置');
+                this.showToast(`修改了 ${randomEntity.name} 的位置`);
+            }
+        });
+
+        document.getElementById('captureSnapshot')!.addEventListener('click', () => {
+            this.addToHistory('手动快照');
+            this.showToast('已捕获当前状态', '📸');
+        });
+
+        document.getElementById('clearHistory')!.addEventListener('click', () => {
+            this.incrementalHistory = [];
+            this.scene.createIncrementalSnapshot();
+            this.addToHistory('清空后重新开始');
+            this.showToast('历史记录已清空');
+        });
+
+        document.getElementById('autoSnapshot')!.addEventListener('change', (e) => {
+            const checkbox = e.target as HTMLInputElement;
+            if (checkbox.checked) {
+                this.autoSnapshotInterval = window.setInterval(() => {
+                    this.addToHistory('自动快照');
+                }, 2000);
+                this.showToast('自动快照已启用', '⏱️');
+            } else {
+                if (this.autoSnapshotInterval !== null) {
+                    clearInterval(this.autoSnapshotInterval);
+                    this.autoSnapshotInterval = null;
+                }
+                this.showToast('自动快照已禁用');
+            }
+        });
+
+        document.getElementById('updateSceneData')!.addEventListener('click', () => {
+            const gameTime = parseInt((document.getElementById('gameTime') as HTMLInputElement).value);
+            const score = parseInt((document.getElementById('score') as HTMLInputElement).value);
+
+            this.scene.sceneData.set('gameTime', gameTime);
+            this.scene.sceneData.set('score', score);
+
+            this.addToHistory('更新场景数据');
+            this.showToast('场景数据已更新');
+        });
+    }
+
+    private updateHistoryPanel() {
+        const panel = document.getElementById('historyPanel')!;
+
+        if (this.incrementalHistory.length === 0) {
+            panel.innerHTML = '暂无历史记录';
+            return;
+        }
+
+        panel.innerHTML = this.incrementalHistory.map((item, index) => {
+            const isLatest = index === this.incrementalHistory.length - 1;
+            const time = new Date(item.timestamp).toLocaleTimeString();
+
+            return `
+                <div class="history-item" data-index="${index}" style="
+                    padding: 8px;
+                    margin: 4px 0;
+                    background: ${isLatest ? 'rgba(74, 158, 255, 0.2)' : 'rgba(136, 146, 176, 0.1)'};
+                    border-left: 3px solid ${isLatest ? '#4a9eff' : '#8892b0'};
+                    border-radius: 4px;
+                    cursor: pointer;
+                    transition: background 0.2s;
+                ">
+                    <div style="display: flex; justify-content: space-between; align-items: center;">
+                        <div>
+                            <strong>${item.label}</strong>
+                            ${isLatest ? '<span style="color: #4a9eff; margin-left: 8px;">●</span>' : ''}
+                        </div>
+                        <small style="color: #8892b0;">${time}</small>
+                    </div>
+                    <div style="font-size: 11px; color: #8892b0; margin-top: 4px;">
+                        实体: +${item.stats.addedEntities} -${item.stats.removedEntities} ~${item.stats.updatedEntities} |
+                        组件: +${item.stats.addedComponents} -${item.stats.removedComponents} ~${item.stats.updatedComponents} |
+                        总变更: ${item.stats.totalChanges}
+                    </div>
+                </div>
+            `;
+        }).join('');
+
+        // 绑定点击事件
+        panel.querySelectorAll('.history-item').forEach(item => {
+            item.addEventListener('click', () => {
+                const index = parseInt(item.getAttribute('data-index')!);
+                this.showSnapshotDetails(index);
+            });
+        });
+
+        // 自动滚动到底部
+        panel.scrollTop = panel.scrollHeight;
+    }
+
+    private showSnapshotDetails(index: number) {
+        const item = this.incrementalHistory[index];
+        const detailsPanel = document.getElementById('snapshotDetails')!;
+
+        const details = {
+            版本: item.incremental.version,
+            基础版本: item.incremental.baseVersion,
+            时间戳: new Date(item.incremental.timestamp).toLocaleString(),
+            场景名称: item.incremental.sceneName,
+            统计: item.stats,
+            实体变更: item.incremental.entityChanges.map((c: any) => ({
+                操作: c.operation,
+                实体ID: c.entityId,
+                实体名称: c.entityName
+            })),
+            组件变更: item.incremental.componentChanges.map((c: any) => ({
+                操作: c.operation,
+                实体ID: c.entityId,
+                组件类型: c.componentType
+            })),
+            场景数据变更: item.incremental.sceneDataChanges.map((c: any) => ({
+                键: c.key,
+                值: c.value,
+                已删除: c.deleted
+            }))
+        };
+
+        detailsPanel.textContent = JSON.stringify(details, null, 2);
+    }
+
+    private updateStats() {
+        document.getElementById('entityCount')!.textContent = this.scene.entities.count.toString();
+        document.getElementById('historyCount')!.textContent = this.incrementalHistory.length.toString();
+
+        if (this.incrementalHistory.length > 0) {
+            const lastItem = this.incrementalHistory[this.incrementalHistory.length - 1];
+            const size = IncrementalSerializer.getIncrementalSize(lastItem.incremental);
+            document.getElementById('snapshotSize')!.textContent = this.formatBytes(size);
+            document.getElementById('totalChanges')!.textContent = lastItem.stats.totalChanges.toString();
+        }
+    }
+
+    private formatBytes(bytes: number): string {
+        if (bytes < 1024) return `${bytes}B`;
+        if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    }
+
+    protected render() {
+        // RenderSystem会处理渲染
+    }
+
+    public destroy() {
+        if (this.autoSnapshotInterval !== null) {
+            clearInterval(this.autoSnapshotInterval);
+        }
+        super.destroy();
+    }
+}

examples/core-demos/src/demos/index.ts

@@ -1,12 +1,13 @@
 import { DemoBase } from './DemoBase';
 import { SerializationDemo } from './SerializationDemo';
+import { IncrementalSerializationDemo } from './IncrementalSerializationDemo';
 import { WorkerSystemDemo } from './WorkerSystemDemo';
 
-export { DemoBase, SerializationDemo, WorkerSystemDemo };
+export { DemoBase, SerializationDemo, IncrementalSerializationDemo, WorkerSystemDemo };
 
 // Demo注册表
 export const DEMO_REGISTRY: typeof DemoBase[] = [
     SerializationDemo,
-    WorkerSystemDemo,
+    IncrementalSerializationDemo,
-    // 更多demos可以在这里添加
+    WorkerSystemDemo
 ];

packages/core/src/ECS/Scene.ts

@@ -3,7 +3,7 @@ import { EntityList } from './Utils/EntityList';
 import { EntityProcessorList } from './Utils/EntityProcessorList';
 import { IdentifierPool } from './Utils/IdentifierPool';
 import { EntitySystem } from './Systems/EntitySystem';
-import { ComponentStorageManager } from './Core/ComponentStorage';
+import { ComponentStorageManager, ComponentRegistry } from './Core/ComponentStorage';
 import { QuerySystem } from './Core/QuerySystem';
 import { TypeSafeEventSystem } from './Core/EventSystem';
 import { EventBus } from './Core/EventBus';
@@ -11,6 +11,7 @@ import { IScene, ISceneConfig } from './IScene';
 import { getComponentInstanceTypeName, getSystemInstanceTypeName } from './Decorators';
 import { TypedQueryBuilder } from './Core/Query/TypedQuery';
 import { SceneSerializer, SceneSerializationOptions, SceneDeserializationOptions } from './Serialization/SceneSerializer';
+import { IncrementalSerializer, IncrementalSnapshot, IncrementalSerializationOptions } from './Serialization/IncrementalSerializer';
 
 /**
  * 游戏场景默认实现类
@@ -548,4 +549,142 @@ export class Scene implements IScene {
     public deserialize(saveData: string | Buffer, options?: SceneDeserializationOptions): void {
         SceneSerializer.deserialize(this, saveData, options);
     }
+
+    // ==================== 增量序列化 API ====================
+
+    /** 增量序列化的基础快照 */
+    private _incrementalBaseSnapshot?: any;
+
+    /**
+     * 创建增量序列化的基础快照
+     *
+     * 在需要进行增量序列化前，先调用此方法创建基础快照
+     *
+     * @param options 序列化选项
+     *
+     * @example
+     * ```typescript
+     * // 创建基础快照
+     * scene.createIncrementalSnapshot();
+     *
+     * // 进行一些修改...
+     * entity.addComponent(new PositionComponent(100, 200));
+     *
+     * // 计算增量变更
+     * const incremental = scene.serializeIncremental();
+     * ```
+     */
+    public createIncrementalSnapshot(options?: IncrementalSerializationOptions): void {
+        this._incrementalBaseSnapshot = IncrementalSerializer.createSnapshot(this, options);
+    }
+
+    /**
+     * 增量序列化场景
+     *
+     * 只序列化相对于基础快照的变更部分
+     *
+     * @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);
+     * ```
+     */
+    public serializeIncremental(options?: IncrementalSerializationOptions): IncrementalSnapshot {
+        if (!this._incrementalBaseSnapshot) {
+            throw new Error('必须先调用 createIncrementalSnapshot() 创建基础快照');
+        }
+
+        return IncrementalSerializer.computeIncremental(
+            this,
+            this._incrementalBaseSnapshot,
+            options
+        );
+    }
+
+    /**
+     * 应用增量变更到场景
+     *
+     * @param incremental 增量快照数据（JSON字符串或对象）
+     * @param componentRegistry 组件类型注册表（可选，默认使用全局注册表）
+     *
+     * @example
+     * ```typescript
+     * // 应用增量变更
+     * scene.applyIncremental(incrementalSnapshot);
+     *
+     * // 或从JSON字符串应用
+     * const incremental = IncrementalSerializer.deserializeIncremental(jsonString);
+     * scene.applyIncremental(incremental);
+     * ```
+     */
+    public applyIncremental(
+        incremental: IncrementalSnapshot | string,
+        componentRegistry?: Map<string, any>
+    ): void {
+        const snapshot = typeof incremental === 'string'
+            ? IncrementalSerializer.deserializeIncremental(incremental)
+            : incremental;
+
+        const registry = componentRegistry || ComponentRegistry.getAllComponentNames() as Map<string, any>;
+
+        IncrementalSerializer.applyIncremental(this, snapshot, registry);
+    }
+
+    /**
+     * 更新增量快照基准
+     *
+     * 将当前场景状态设为新的增量序列化基准
+     *
+     * @param options 序列化选项
+     *
+     * @example
+     * ```typescript
+     * // 创建初始快照
+     * scene.createIncrementalSnapshot();
+     *
+     * // 进行一些修改并序列化
+     * const incremental1 = scene.serializeIncremental();
+     *
+     * // 更新基准，之后的增量将基于当前状态
+     * scene.updateIncrementalSnapshot();
+     *
+     * // 继续修改
+     * const incremental2 = scene.serializeIncremental();
+     * ```
+     */
+    public updateIncrementalSnapshot(options?: IncrementalSerializationOptions): void {
+        this.createIncrementalSnapshot(options);
+    }
+
+    /**
+     * 清除增量快照
+     *
+     * 释放快照占用的内存
+     */
+    public clearIncrementalSnapshot(): void {
+        this._incrementalBaseSnapshot = undefined;
+    }
+
+    /**
+     * 检查是否有增量快照
+     *
+     * @returns 如果已创建增量快照返回true
+     */
+    public hasIncrementalSnapshot(): boolean {
+        return this._incrementalBaseSnapshot !== undefined;
+    }
 }

packages/core/src/ECS/Serialization/IncrementalSerializer.ts

@@ -0,0 +1,677 @@
+/**
+ * 增量序列化器
+ *
+ * 提供高性能的增量序列化支持，只序列化变更的数据
+ * 适用于网络同步、大场景存档、时间回溯等场景
+ */
+
+import type { IScene } from '../IScene';
+import { Entity } from '../Entity';
+import { Component } from '../Component';
+import { ComponentSerializer, SerializedComponent } from './ComponentSerializer';
+import { SerializedEntity } from './EntitySerializer';
+import { ComponentType } from '../Core/ComponentStorage';
+
+/**
+ * 变更操作类型
+ */
+export 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>>;  // 使用JSON字符串存储组件数据
+    /** 场景自定义数据 */
+    sceneData: Map<string, string>;  // 使用JSON字符串存储场景数据
+}
+
+/**
+ * 增量序列化选项
+ */
+export interface IncrementalSerializationOptions {
+    /**
+     * 是否包含组件数据的深度对比
+     * 默认true，设为false可提升性能但可能漏掉组件内部字段变更
+     */
+    deepComponentComparison?: boolean;
+
+    /**
+     * 是否跟踪场景数据变更
+     * 默认true
+     */
+    trackSceneData?: boolean;
+
+    /**
+     * 是否压缩快照（使用JSON序列化）
+     * 默认false，设为true可减少内存占用但增加CPU开销
+     */
+    compressSnapshot?: boolean;
+}
+
+/**
+ * 增量序列化器类
+ */
+export class IncrementalSerializer {
+    /** 当前快照版本号 */
+    private static snapshotVersion = 0;
+
+    /**
+     * 创建场景快照
+     *
+     * @param scene 要快照的场景
+     * @param options 序列化选项
+     * @returns 场景快照对象
+     */
+    public static createSnapshot(
+        scene: IScene,
+        options?: IncrementalSerializationOptions
+    ): SceneSnapshot {
+        const opts = {
+            deepComponentComparison: true,
+            trackSceneData: true,
+            compressSnapshot: false,
+            ...options
+        };
+
+        const snapshot: SceneSnapshot = {
+            version: ++this.snapshotVersion,
+            entityIds: new Set(),
+            entities: new Map(),
+            components: new Map(),
+            sceneData: new Map()
+        };
+
+        // 快照所有实体
+        for (const entity of scene.entities.buffer) {
+            snapshot.entityIds.add(entity.id);
+
+            // 存储实体基本信息
+            snapshot.entities.set(entity.id, {
+                name: entity.name,
+                tag: entity.tag,
+                active: entity.active,
+                enabled: entity.enabled,
+                updateOrder: entity.updateOrder,
+                parentId: entity.parent?.id
+            });
+
+            // 快照组件
+            if (opts.deepComponentComparison) {
+                const componentMap = new Map<string, string>();
+
+                for (const component of entity.components) {
+                    const serialized = ComponentSerializer.serialize(component);
+                    if (serialized) {
+                        // 使用JSON字符串存储，便于后续对比
+                        componentMap.set(
+                            serialized.type,
+                            JSON.stringify(serialized.data)
+                        );
+                    }
+                }
+
+                if (componentMap.size > 0) {
+                    snapshot.components.set(entity.id, componentMap);
+                }
+            }
+        }
+
+        // 快照场景数据
+        if (opts.trackSceneData) {
+            for (const [key, value] of scene.sceneData) {
+                snapshot.sceneData.set(key, JSON.stringify(value));
+            }
+        }
+
+        return snapshot;
+    }
+
+    /**
+     * 计算增量变更
+     *
+     * @param scene 当前场景
+     * @param baseSnapshot 基础快照
+     * @param options 序列化选项
+     * @returns 增量快照
+     */
+    public static computeIncremental(
+        scene: IScene,
+        baseSnapshot: SceneSnapshot,
+        options?: IncrementalSerializationOptions
+    ): IncrementalSnapshot {
+        const opts = {
+            deepComponentComparison: true,
+            trackSceneData: true,
+            ...options
+        };
+
+        const incremental: IncrementalSnapshot = {
+            version: ++this.snapshotVersion,
+            timestamp: Date.now(),
+            sceneName: scene.name,
+            baseVersion: baseSnapshot.version,
+            entityChanges: [],
+            componentChanges: [],
+            sceneDataChanges: []
+        };
+
+        const currentEntityIds = new Set<number>();
+
+        // 检测实体变更
+        for (const entity of scene.entities.buffer) {
+            currentEntityIds.add(entity.id);
+
+            if (!baseSnapshot.entityIds.has(entity.id)) {
+                // 新增实体
+                incremental.entityChanges.push({
+                    operation: ChangeOperation.EntityAdded,
+                    entityId: entity.id,
+                    entityName: entity.name,
+                    entityData: {
+                        id: entity.id,
+                        name: entity.name,
+                        tag: entity.tag,
+                        active: entity.active,
+                        enabled: entity.enabled,
+                        updateOrder: entity.updateOrder,
+                        parentId: entity.parent?.id,
+                        components: [],
+                        children: []
+                    }
+                });
+
+                // 新增实体的所有组件都是新增
+                for (const component of entity.components) {
+                    const serialized = ComponentSerializer.serialize(component);
+                    if (serialized) {
+                        incremental.componentChanges.push({
+                            operation: ChangeOperation.ComponentAdded,
+                            entityId: entity.id,
+                            componentType: serialized.type,
+                            componentData: serialized
+                        });
+                    }
+                }
+            } else {
+                // 检查实体属性变更
+                const oldData = baseSnapshot.entities.get(entity.id)!;
+                const entityChanged =
+                    oldData.name !== entity.name ||
+                    oldData.tag !== entity.tag ||
+                    oldData.active !== entity.active ||
+                    oldData.enabled !== entity.enabled ||
+                    oldData.updateOrder !== entity.updateOrder ||
+                    oldData.parentId !== entity.parent?.id;
+
+                if (entityChanged) {
+                    incremental.entityChanges.push({
+                        operation: ChangeOperation.EntityUpdated,
+                        entityId: entity.id,
+                        entityData: {
+                            name: entity.name,
+                            tag: entity.tag,
+                            active: entity.active,
+                            enabled: entity.enabled,
+                            updateOrder: entity.updateOrder,
+                            parentId: entity.parent?.id
+                        }
+                    });
+                }
+
+                // 检查组件变更
+                if (opts.deepComponentComparison) {
+                    this.detectComponentChanges(
+                        entity,
+                        baseSnapshot,
+                        incremental.componentChanges
+                    );
+                }
+            }
+        }
+
+        // 检测删除的实体
+        for (const oldEntityId of baseSnapshot.entityIds) {
+            if (!currentEntityIds.has(oldEntityId)) {
+                incremental.entityChanges.push({
+                    operation: ChangeOperation.EntityRemoved,
+                    entityId: oldEntityId
+                });
+            }
+        }
+
+        // 检测场景数据变更
+        if (opts.trackSceneData) {
+            this.detectSceneDataChanges(
+                scene,
+                baseSnapshot,
+                incremental.sceneDataChanges
+            );
+        }
+
+        return incremental;
+    }
+
+    /**
+     * 检测组件变更
+     */
+    private static detectComponentChanges(
+        entity: Entity,
+        baseSnapshot: SceneSnapshot,
+        componentChanges: ComponentChange[]
+    ): void {
+        const oldComponents = baseSnapshot.components.get(entity.id);
+        const currentComponents = new Map<string, SerializedComponent>();
+
+        // 收集当前组件
+        for (const component of entity.components) {
+            const serialized = ComponentSerializer.serialize(component);
+            if (serialized) {
+                currentComponents.set(serialized.type, serialized);
+            }
+        }
+
+        // 检测新增和更新的组件
+        for (const [type, serialized] of currentComponents) {
+            const currentData = JSON.stringify(serialized.data);
+
+            if (!oldComponents || !oldComponents.has(type)) {
+                // 新增组件
+                componentChanges.push({
+                    operation: ChangeOperation.ComponentAdded,
+                    entityId: entity.id,
+                    componentType: type,
+                    componentData: serialized
+                });
+            } else if (oldComponents.get(type) !== currentData) {
+                // 组件数据变更
+                componentChanges.push({
+                    operation: ChangeOperation.ComponentUpdated,
+                    entityId: entity.id,
+                    componentType: type,
+                    componentData: serialized
+                });
+            }
+        }
+
+        // 检测删除的组件
+        if (oldComponents) {
+            for (const oldType of oldComponents.keys()) {
+                if (!currentComponents.has(oldType)) {
+                    componentChanges.push({
+                        operation: ChangeOperation.ComponentRemoved,
+                        entityId: entity.id,
+                        componentType: oldType
+                    });
+                }
+            }
+        }
+    }
+
+    /**
+     * 检测场景数据变更
+     */
+    private static detectSceneDataChanges(
+        scene: IScene,
+        baseSnapshot: SceneSnapshot,
+        sceneDataChanges: SceneDataChange[]
+    ): void {
+        const currentKeys = new Set<string>();
+
+        // 检测新增和更新的场景数据
+        for (const [key, value] of scene.sceneData) {
+            currentKeys.add(key);
+            const currentValue = JSON.stringify(value);
+            const oldValue = baseSnapshot.sceneData.get(key);
+
+            if (!oldValue || oldValue !== currentValue) {
+                sceneDataChanges.push({
+                    operation: ChangeOperation.SceneDataUpdated,
+                    key,
+                    value
+                });
+            }
+        }
+
+        // 检测删除的场景数据
+        for (const oldKey of baseSnapshot.sceneData.keys()) {
+            if (!currentKeys.has(oldKey)) {
+                sceneDataChanges.push({
+                    operation: ChangeOperation.SceneDataUpdated,
+                    key: oldKey,
+                    value: undefined,
+                    deleted: true
+                });
+            }
+        }
+    }
+
+    /**
+     * 应用增量变更到场景
+     *
+     * @param scene 目标场景
+     * @param incremental 增量快照
+     * @param componentRegistry 组件类型注册表
+     */
+    public static applyIncremental(
+        scene: IScene,
+        incremental: IncrementalSnapshot,
+        componentRegistry: Map<string, ComponentType>
+    ): void {
+        // 应用实体变更
+        for (const change of incremental.entityChanges) {
+            switch (change.operation) {
+                case ChangeOperation.EntityAdded:
+                    this.applyEntityAdded(scene, change);
+                    break;
+                case ChangeOperation.EntityRemoved:
+                    this.applyEntityRemoved(scene, change);
+                    break;
+                case ChangeOperation.EntityUpdated:
+                    this.applyEntityUpdated(scene, change);
+                    break;
+            }
+        }
+
+        // 应用组件变更
+        for (const change of incremental.componentChanges) {
+            switch (change.operation) {
+                case ChangeOperation.ComponentAdded:
+                    this.applyComponentAdded(scene, change, componentRegistry);
+                    break;
+                case ChangeOperation.ComponentRemoved:
+                    this.applyComponentRemoved(scene, change, componentRegistry);
+                    break;
+                case ChangeOperation.ComponentUpdated:
+                    this.applyComponentUpdated(scene, change, componentRegistry);
+                    break;
+            }
+        }
+
+        // 应用场景数据变更
+        for (const change of incremental.sceneDataChanges) {
+            if (change.deleted) {
+                scene.sceneData.delete(change.key);
+            } else {
+                scene.sceneData.set(change.key, change.value);
+            }
+        }
+    }
+
+    private static applyEntityAdded(scene: IScene, change: EntityChange): void {
+        if (!change.entityData) return;
+
+        const entity = new Entity(change.entityName || 'Entity', change.entityId);
+        entity.tag = change.entityData.tag || 0;
+        entity.active = change.entityData.active ?? true;
+        entity.enabled = change.entityData.enabled ?? true;
+        entity.updateOrder = change.entityData.updateOrder || 0;
+
+        scene.addEntity(entity);
+    }
+
+    private static applyEntityRemoved(scene: IScene, change: EntityChange): void {
+        const entity = scene.entities.findEntityById(change.entityId);
+        if (entity) {
+            entity.destroy();
+        }
+    }
+
+    private static applyEntityUpdated(scene: IScene, change: EntityChange): void {
+        if (!change.entityData) return;
+
+        const entity = scene.entities.findEntityById(change.entityId);
+        if (!entity) return;
+
+        if (change.entityData.name !== undefined) entity.name = change.entityData.name;
+        if (change.entityData.tag !== undefined) entity.tag = change.entityData.tag;
+        if (change.entityData.active !== undefined) entity.active = change.entityData.active;
+        if (change.entityData.enabled !== undefined) entity.enabled = change.entityData.enabled;
+        if (change.entityData.updateOrder !== undefined) entity.updateOrder = change.entityData.updateOrder;
+
+        if (change.entityData.parentId !== undefined) {
+            const newParent = scene.entities.findEntityById(change.entityData.parentId);
+            if (newParent && entity.parent !== newParent) {
+                if (entity.parent) {
+                    entity.parent.removeChild(entity);
+                }
+                newParent.addChild(entity);
+            }
+        } else if (entity.parent) {
+            entity.parent.removeChild(entity);
+        }
+    }
+
+    private static applyComponentAdded(
+        scene: IScene,
+        change: ComponentChange,
+        componentRegistry: Map<string, ComponentType>
+    ): void {
+        if (!change.componentData) return;
+
+        const entity = scene.entities.findEntityById(change.entityId);
+        if (!entity) return;
+
+        const component = ComponentSerializer.deserialize(change.componentData, componentRegistry);
+        if (component) {
+            entity.addComponent(component);
+        }
+    }
+
+    private static applyComponentRemoved(
+        scene: IScene,
+        change: ComponentChange,
+        componentRegistry: Map<string, ComponentType>
+    ): void {
+        const entity = scene.entities.findEntityById(change.entityId);
+        if (!entity) return;
+
+        const componentClass = componentRegistry.get(change.componentType);
+        if (!componentClass) return;
+
+        entity.removeComponentByType(componentClass);
+    }
+
+    private static applyComponentUpdated(
+        scene: IScene,
+        change: ComponentChange,
+        componentRegistry: Map<string, ComponentType>
+    ): void {
+        if (!change.componentData) return;
+
+        const entity = scene.entities.findEntityById(change.entityId);
+        if (!entity) return;
+
+        const componentClass = componentRegistry.get(change.componentType);
+        if (!componentClass) return;
+
+        entity.removeComponentByType(componentClass);
+
+        const component = ComponentSerializer.deserialize(change.componentData, componentRegistry);
+        if (component) {
+            entity.addComponent(component);
+        }
+    }
+
+    /**
+     * 序列化增量快照为JSON
+     *
+     * @param incremental 增量快照
+     * @param pretty 是否美化输出
+     * @returns JSON字符串
+     */
+    public static serializeIncremental(
+        incremental: IncrementalSnapshot,
+        pretty: boolean = false
+    ): string {
+        return pretty
+            ? JSON.stringify(incremental, null, 2)
+            : JSON.stringify(incremental);
+    }
+
+    /**
+     * 从JSON反序列化增量快照
+     *
+     * @param json JSON字符串
+     * @returns 增量快照
+     */
+    public static deserializeIncremental(json: string): IncrementalSnapshot {
+        return JSON.parse(json);
+    }
+
+    /**
+     * 计算增量快照的大小（字节）
+     *
+     * @param incremental 增量快照
+     * @returns 字节数
+     */
+    public static getIncrementalSize(incremental: IncrementalSnapshot): number {
+        const json = this.serializeIncremental(incremental);
+        return new Blob([json]).size;
+    }
+
+    /**
+     * 获取增量快照的统计信息
+     *
+     * @param incremental 增量快照
+     * @returns 统计信息
+     */
+    public static getIncrementalStats(incremental: IncrementalSnapshot): {
+        totalChanges: number;
+        entityChanges: number;
+        componentChanges: number;
+        sceneDataChanges: number;
+        addedEntities: number;
+        removedEntities: number;
+        updatedEntities: number;
+        addedComponents: number;
+        removedComponents: number;
+        updatedComponents: number;
+    } {
+        return {
+            totalChanges:
+                incremental.entityChanges.length +
+                incremental.componentChanges.length +
+                incremental.sceneDataChanges.length,
+            entityChanges: incremental.entityChanges.length,
+            componentChanges: incremental.componentChanges.length,
+            sceneDataChanges: incremental.sceneDataChanges.length,
+            addedEntities: incremental.entityChanges.filter(
+                c => c.operation === ChangeOperation.EntityAdded
+            ).length,
+            removedEntities: incremental.entityChanges.filter(
+                c => c.operation === ChangeOperation.EntityRemoved
+            ).length,
+            updatedEntities: incremental.entityChanges.filter(
+                c => c.operation === ChangeOperation.EntityUpdated
+            ).length,
+            addedComponents: incremental.componentChanges.filter(
+                c => c.operation === ChangeOperation.ComponentAdded
+            ).length,
+            removedComponents: incremental.componentChanges.filter(
+                c => c.operation === ChangeOperation.ComponentRemoved
+            ).length,
+            updatedComponents: incremental.componentChanges.filter(
+                c => c.operation === ChangeOperation.ComponentUpdated
+            ).length
+        };
+    }
+
+    /**
+     * 重置快照版本号（用于测试）
+     */
+    public static resetVersion(): void {
+        this.snapshotVersion = 0;
+    }
+}

packages/core/src/ECS/Serialization/index.ts

@@ -49,3 +49,13 @@ export type {
     ComponentMigrationFunction,
     SceneMigrationFunction
 } from './VersionMigration';
+
+// 增量序列化
+export { IncrementalSerializer, ChangeOperation } from './IncrementalSerializer';
+export type {
+    IncrementalSnapshot,
+    IncrementalSerializationOptions,
+    EntityChange,
+    ComponentChange,
+    SceneDataChange
+} from './IncrementalSerializer';

packages/core/tests/ArchetypeVsComponentIndex.comparison.test.ts

@@ -0,0 +1,213 @@
+import { ArchetypeSystem } from '../src/ECS/Core/ArchetypeSystem';
+import { ComponentIndexManager } from '../src/ECS/Core/ComponentIndex';
+import { Entity } from '../src/ECS/Entity';
+import { Component } from '../src/ECS/Component';
+
+class PositionComponent extends Component {
+    public x: number;
+    public y: number;
+
+    constructor(...args: unknown[]) {
+        super();
+        const [x = 0, y = 0] = args as [number?, number?];
+        this.x = x;
+        this.y = y;
+    }
+}
+
+class VelocityComponent extends Component {
+    public vx: number;
+    public vy: number;
+
+    constructor(...args: unknown[]) {
+        super();
+        const [vx = 0, vy = 0] = args as [number?, number?];
+        this.vx = vx;
+        this.vy = vy;
+    }
+}
+
+class HealthComponent extends Component {
+    public hp: number;
+
+    constructor(...args: unknown[]) {
+        super();
+        const [hp = 100] = args as [number?];
+        this.hp = hp;
+    }
+}
+
+describe('ArchetypeSystem vs ComponentIndexManager 对比测试', () => {
+    let archetypeSystem: ArchetypeSystem;
+    let componentIndexManager: ComponentIndexManager;
+    let entities: Entity[];
+
+    beforeEach(() => {
+        archetypeSystem = new ArchetypeSystem();
+        componentIndexManager = new ComponentIndexManager();
+        entities = [];
+    });
+
+    describe('功能等价性验证', () => {
+        test('单组件查询应该返回相同结果', () => {
+            // 创建测试实体
+            for (let i = 0; i < 100; i++) {
+                const entity = new Entity(`Entity${i}`, i);
+                entity.addComponent(new PositionComponent(i, i));
+
+                if (i % 2 === 0) {
+                    entity.addComponent(new VelocityComponent(1, 1));
+                }
+
+                entities.push(entity);
+                archetypeSystem.addEntity(entity);
+                componentIndexManager.addEntity(entity);
+            }
+
+            // 使用 ArchetypeSystem 查询
+            const archetypeEntities = archetypeSystem.getEntitiesByComponent(PositionComponent);
+
+            // 使用 ComponentIndexManager 查询
+            const indexEntities = Array.from(componentIndexManager.query(PositionComponent));
+
+            // 应该返回相同数量
+            expect(archetypeEntities.length).toBe(indexEntities.length);
+            expect(archetypeEntities.length).toBe(100);
+
+            // 应该包含相同的实体
+            const archetypeIds = new Set(archetypeEntities.map(e => e.id));
+            const indexIds = new Set(indexEntities.map(e => e.id));
+
+            expect(archetypeIds).toEqual(indexIds);
+        });
+
+        test('多组件 AND 查询应该返回相同结果', () => {
+            // 创建测试实体
+            for (let i = 0; i < 100; i++) {
+                const entity = new Entity(`Entity${i}`, i);
+                entity.addComponent(new PositionComponent(i, i));
+
+                if (i % 2 === 0) {
+                    entity.addComponent(new VelocityComponent(1, 1));
+                }
+
+                if (i % 3 === 0) {
+                    entity.addComponent(new HealthComponent(100));
+                }
+
+                entities.push(entity);
+                archetypeSystem.addEntity(entity);
+                componentIndexManager.addEntity(entity);
+            }
+
+            // ArchetypeSystem 查询
+            const archetypeResult = archetypeSystem.queryArchetypes([PositionComponent, VelocityComponent], 'AND');
+            const archetypeEntities: Entity[] = [];
+            for (const archetype of archetypeResult.archetypes) {
+                for (const entity of archetype.entities) {
+                    archetypeEntities.push(entity);
+                }
+            }
+
+            // ComponentIndexManager 查询
+            const indexEntities = Array.from(componentIndexManager.queryMultiple([PositionComponent, VelocityComponent], 'AND'));
+
+            // 验证结果
+            expect(archetypeEntities.length).toBe(indexEntities.length);
+            expect(archetypeEntities.length).toBe(50); // i % 2 === 0
+
+            const archetypeIds = new Set(archetypeEntities.map(e => e.id));
+            const indexIds = new Set(indexEntities.map(e => e.id));
+            expect(archetypeIds).toEqual(indexIds);
+        });
+
+        test('多组件 OR 查询应该返回相同结果', () => {
+            // 创建测试实体
+            for (let i = 0; i < 100; i++) {
+                const entity = new Entity(`Entity${i}`, i);
+
+                if (i % 2 === 0) {
+                    entity.addComponent(new PositionComponent(i, i));
+                }
+
+                if (i % 3 === 0) {
+                    entity.addComponent(new VelocityComponent(1, 1));
+                }
+
+                entities.push(entity);
+                archetypeSystem.addEntity(entity);
+                componentIndexManager.addEntity(entity);
+            }
+
+            // ArchetypeSystem 查询
+            const archetypeResult = archetypeSystem.queryArchetypes([PositionComponent, VelocityComponent], 'OR');
+            const archetypeEntities: Entity[] = [];
+            for (const archetype of archetypeResult.archetypes) {
+                for (const entity of archetype.entities) {
+                    archetypeEntities.push(entity);
+                }
+            }
+
+            // ComponentIndexManager 查询
+            const indexEntities = Array.from(componentIndexManager.queryMultiple([PositionComponent, VelocityComponent], 'OR'));
+
+            // 验证结果 - 有 Position 或 Velocity 的实体
+            expect(archetypeEntities.length).toBe(indexEntities.length);
+
+            const archetypeIds = new Set(archetypeEntities.map(e => e.id));
+            const indexIds = new Set(indexEntities.map(e => e.id));
+            expect(archetypeIds).toEqual(indexIds);
+        });
+
+        test('空查询应该返回空结果', () => {
+            // 创建一些实体但不添加 HealthComponent
+            for (let i = 0; i < 10; i++) {
+                const entity = new Entity(`Entity${i}`, i);
+                entity.addComponent(new PositionComponent(i, i));
+                archetypeSystem.addEntity(entity);
+                componentIndexManager.addEntity(entity);
+            }
+
+            // 查询不存在的组件
+            const archetypeEntities = archetypeSystem.getEntitiesByComponent(HealthComponent);
+            const indexEntities = Array.from(componentIndexManager.query(HealthComponent));
+
+            expect(archetypeEntities.length).toBe(0);
+            expect(indexEntities.length).toBe(0);
+        });
+    });
+
+    describe('性能对比', () => {
+        test('单组件查询性能对比', () => {
+            // 准备大量数据
+            for (let i = 0; i < 1000; i++) {
+                const entity = new Entity(`Entity${i}`, i);
+                entity.addComponent(new PositionComponent(i, i));
+                archetypeSystem.addEntity(entity);
+                componentIndexManager.addEntity(entity);
+            }
+
+            // ArchetypeSystem 性能测试
+            const archetypeStart = performance.now();
+            for (let i = 0; i < 100; i++) {
+                archetypeSystem.getEntitiesByComponent(PositionComponent);
+            }
+            const archetypeDuration = performance.now() - archetypeStart;
+
+            // ComponentIndexManager 性能测试
+            const indexStart = performance.now();
+            for (let i = 0; i < 100; i++) {
+                componentIndexManager.query(PositionComponent);
+            }
+            const indexDuration = performance.now() - indexStart;
+
+            console.log(`ArchetypeSystem: ${archetypeDuration.toFixed(2)}ms`);
+            console.log(`ComponentIndexManager: ${indexDuration.toFixed(2)}ms`);
+            console.log(`Ratio: ${(archetypeDuration / indexDuration).toFixed(2)}x`);
+
+            // 两者应该都很快
+            expect(archetypeDuration).toBeLessThan(100);
+            expect(indexDuration).toBeLessThan(100);
+        });
+    });
+});

packages/core/tests/ECS/Serialization/IncrementalSerialization.test.ts

@@ -0,0 +1,593 @@
+/**
+ * 增量序列化系统测试
+ */
+
+import { Component } from '../../../src/ECS/Component';
+import { Scene } from '../../../src/ECS/Scene';
+import { Entity } from '../../../src/ECS/Entity';
+import {
+    Serializable,
+    Serialize,
+    IncrementalSerializer,
+    ChangeOperation
+} from '../../../src/ECS/Serialization';
+import { ECSComponent } from '../../../src/ECS/Decorators';
+import { ComponentRegistry } from '../../../src/ECS/Core/ComponentStorage';
+
+// 测试组件定义
+@ECSComponent('IncTest_Position')
+@Serializable({ version: 1 })
+class PositionComponent extends Component {
+    @Serialize()
+    public x: number = 0;
+
+    @Serialize()
+    public y: number = 0;
+
+    constructor(x: number = 0, y: number = 0) {
+        super();
+        this.x = x;
+        this.y = y;
+    }
+}
+
+@ECSComponent('IncTest_Velocity')
+@Serializable({ version: 1 })
+class VelocityComponent extends Component {
+    @Serialize()
+    public dx: number = 0;
+
+    @Serialize()
+    public dy: number = 0;
+}
+
+@ECSComponent('IncTest_Health')
+@Serializable({ version: 1 })
+class HealthComponent extends Component {
+    @Serialize()
+    public current: number = 100;
+
+    @Serialize()
+    public max: number = 100;
+}
+
+describe('Incremental Serialization System', () => {
+    let scene: Scene;
+
+    beforeEach(() => {
+        IncrementalSerializer.resetVersion();
+        ComponentRegistry.reset();
+
+        // 重新注册测试组件
+        ComponentRegistry.register(PositionComponent);
+        ComponentRegistry.register(VelocityComponent);
+        ComponentRegistry.register(HealthComponent);
+
+        scene = new Scene({ name: 'IncrementalTestScene' });
+    });
+
+    afterEach(() => {
+        scene.end();
+    });
+
+    describe('Scene Snapshot', () => {
+        it('应该创建场景快照', () => {
+            const entity1 = scene.createEntity('Entity1');
+            entity1.addComponent(new PositionComponent(10, 20));
+
+            const entity2 = scene.createEntity('Entity2');
+            entity2.addComponent(new VelocityComponent());
+
+            scene.createIncrementalSnapshot();
+
+            expect(scene.hasIncrementalSnapshot()).toBe(true);
+        });
+
+        it('应该在快照中包含所有实体', () => {
+            const entity1 = scene.createEntity('Entity1');
+            entity1.addComponent(new PositionComponent(10, 20));
+
+            const entity2 = scene.createEntity('Entity2');
+            entity2.addComponent(new VelocityComponent());
+
+            const snapshot = IncrementalSerializer.createSnapshot(scene);
+
+            expect(snapshot.entityIds.size).toBe(2);
+            expect(snapshot.entityIds.has(entity1.id)).toBe(true);
+            expect(snapshot.entityIds.has(entity2.id)).toBe(true);
+        });
+
+        it('应该在快照中包含实体基本信息', () => {
+            const entity = scene.createEntity('TestEntity');
+            entity.tag = 42;
+            entity.active = false;
+            entity.enabled = false;
+            entity.updateOrder = 5;
+
+            const snapshot = IncrementalSerializer.createSnapshot(scene);
+
+            const entityData = snapshot.entities.get(entity.id);
+            expect(entityData).toBeDefined();
+            expect(entityData!.name).toBe('TestEntity');
+            expect(entityData!.tag).toBe(42);
+            expect(entityData!.active).toBe(false);
+            expect(entityData!.enabled).toBe(false);
+            expect(entityData!.updateOrder).toBe(5);
+        });
+
+        it('应该在快照中包含组件数据', () => {
+            const entity = scene.createEntity('Entity');
+            entity.addComponent(new PositionComponent(100, 200));
+
+            const snapshot = IncrementalSerializer.createSnapshot(scene, {
+                deepComponentComparison: true
+            });
+
+            const components = snapshot.components.get(entity.id);
+            expect(components).toBeDefined();
+            expect(components!.has('IncTest_Position')).toBe(true);
+        });
+    });
+
+    describe('Entity Changes Detection', () => {
+        it('应该检测新增的实体', () => {
+            scene.createIncrementalSnapshot();
+
+            const newEntity = scene.createEntity('NewEntity');
+            newEntity.addComponent(new PositionComponent(50, 100));
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.entityChanges.length).toBe(1);
+            expect(incremental.entityChanges[0].operation).toBe(ChangeOperation.EntityAdded);
+            expect(incremental.entityChanges[0].entityId).toBe(newEntity.id);
+            expect(incremental.entityChanges[0].entityName).toBe('NewEntity');
+        });
+
+        it('应该检测删除的实体', () => {
+            const entity = scene.createEntity('ToDelete');
+            scene.createIncrementalSnapshot();
+
+            entity.destroy();
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.entityChanges.length).toBe(1);
+            expect(incremental.entityChanges[0].operation).toBe(ChangeOperation.EntityRemoved);
+            expect(incremental.entityChanges[0].entityId).toBe(entity.id);
+        });
+
+        it('应该检测实体属性变更', () => {
+            const entity = scene.createEntity('Entity');
+            scene.createIncrementalSnapshot();
+
+            entity.name = 'UpdatedName';
+            entity.tag = 99;
+            entity.active = false;
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.entityChanges.length).toBe(1);
+            expect(incremental.entityChanges[0].operation).toBe(ChangeOperation.EntityUpdated);
+            expect(incremental.entityChanges[0].entityData!.name).toBe('UpdatedName');
+            expect(incremental.entityChanges[0].entityData!.tag).toBe(99);
+            expect(incremental.entityChanges[0].entityData!.active).toBe(false);
+        });
+    });
+
+    describe('Component Changes Detection', () => {
+        it('应该检测新增的组件', () => {
+            const entity = scene.createEntity('Entity');
+            scene.createIncrementalSnapshot();
+
+            entity.addComponent(new PositionComponent(10, 20));
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.componentChanges.length).toBe(1);
+            expect(incremental.componentChanges[0].operation).toBe(ChangeOperation.ComponentAdded);
+            expect(incremental.componentChanges[0].entityId).toBe(entity.id);
+            expect(incremental.componentChanges[0].componentType).toBe('IncTest_Position');
+        });
+
+        it('应该检测删除的组件', () => {
+            const entity = scene.createEntity('Entity');
+            entity.addComponent(new PositionComponent(10, 20));
+            scene.createIncrementalSnapshot();
+
+            entity.removeComponentByType(PositionComponent);
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.componentChanges.length).toBe(1);
+            expect(incremental.componentChanges[0].operation).toBe(ChangeOperation.ComponentRemoved);
+            expect(incremental.componentChanges[0].componentType).toBe('IncTest_Position');
+        });
+
+        it('应该检测组件数据变更', () => {
+            const entity = scene.createEntity('Entity');
+            const pos = new PositionComponent(10, 20);
+            entity.addComponent(pos);
+            scene.createIncrementalSnapshot();
+
+            pos.x = 100;
+            pos.y = 200;
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.componentChanges.length).toBe(1);
+            expect(incremental.componentChanges[0].operation).toBe(ChangeOperation.ComponentUpdated);
+            expect(incremental.componentChanges[0].componentData!.data.x).toBe(100);
+            expect(incremental.componentChanges[0].componentData!.data.y).toBe(200);
+        });
+
+        it('应该检测多个组件变更', () => {
+            const entity = scene.createEntity('Entity');
+            entity.addComponent(new PositionComponent(10, 20));
+            scene.createIncrementalSnapshot();
+
+            entity.addComponent(new VelocityComponent());
+            entity.addComponent(new HealthComponent());
+            entity.removeComponentByType(PositionComponent);
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.componentChanges.length).toBe(3);
+        });
+    });
+
+    describe('Scene Data Changes Detection', () => {
+        it('应该检测新增的场景数据', () => {
+            scene.createIncrementalSnapshot();
+
+            scene.sceneData.set('weather', 'sunny');
+            scene.sceneData.set('time', 12.5);
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.sceneDataChanges.length).toBe(2);
+        });
+
+        it('应该检测更新的场景数据', () => {
+            scene.sceneData.set('weather', 'sunny');
+            scene.createIncrementalSnapshot();
+
+            scene.sceneData.set('weather', 'rainy');
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.sceneDataChanges.length).toBe(1);
+            expect(incremental.sceneDataChanges[0].key).toBe('weather');
+            expect(incremental.sceneDataChanges[0].value).toBe('rainy');
+        });
+
+        it('应该检测删除的场景数据', () => {
+            scene.sceneData.set('temp', 'value');
+            scene.createIncrementalSnapshot();
+
+            scene.sceneData.delete('temp');
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.sceneDataChanges.length).toBe(1);
+            expect(incremental.sceneDataChanges[0].deleted).toBe(true);
+        });
+    });
+
+    describe('Apply Incremental Changes', () => {
+        it('应该应用实体添加变更', () => {
+            const scene1 = new Scene({ name: 'Scene1' });
+            scene1.createIncrementalSnapshot();
+
+            const newEntity = scene1.createEntity('NewEntity');
+            newEntity.addComponent(new PositionComponent(50, 100));
+
+            const incremental = scene1.serializeIncremental();
+
+            const scene2 = new Scene({ name: 'Scene2' });
+            scene2.applyIncremental(incremental);
+
+            expect(scene2.entities.count).toBe(1);
+            const entity = scene2.findEntity('NewEntity');
+            expect(entity).not.toBeNull();
+            expect(entity!.hasComponent(PositionComponent)).toBe(true);
+
+            scene1.end();
+            scene2.end();
+        });
+
+        it('应该应用实体删除变更', () => {
+            const scene1 = new Scene({ name: 'Scene1' });
+            const entity = scene1.createEntity('ToDelete');
+            scene1.createIncrementalSnapshot();
+
+            entity.destroy();
+            const incremental = scene1.serializeIncremental();
+
+            const scene2 = new Scene({ name: 'Scene2' });
+            const entity2 = scene2.createEntity('ToDelete');
+            Object.defineProperty(entity2, 'id', { value: entity.id, writable: true });
+
+            scene2.applyIncremental(incremental);
+
+            expect(scene2.entities.count).toBe(0);
+
+            scene1.end();
+            scene2.end();
+        });
+
+        it('应该应用实体属性更新', () => {
+            const scene1 = new Scene({ name: 'Scene1' });
+            const entity1 = scene1.createEntity('Entity');
+            scene1.createIncrementalSnapshot();
+
+            entity1.name = 'UpdatedName';
+            entity1.tag = 42;
+            entity1.active = false;
+
+            const incremental = scene1.serializeIncremental();
+
+            const scene2 = new Scene({ name: 'Scene2' });
+            const entity2 = scene2.createEntity('Entity');
+            Object.defineProperty(entity2, 'id', { value: entity1.id, writable: true });
+
+            scene2.applyIncremental(incremental);
+
+            expect(entity2.name).toBe('UpdatedName');
+            expect(entity2.tag).toBe(42);
+            expect(entity2.active).toBe(false);
+
+            scene1.end();
+            scene2.end();
+        });
+
+        it('应该应用组件添加变更', () => {
+            const scene1 = new Scene({ name: 'Scene1' });
+            const entity1 = scene1.createEntity('Entity');
+            scene1.createIncrementalSnapshot();
+
+            entity1.addComponent(new PositionComponent(100, 200));
+
+            const incremental = scene1.serializeIncremental();
+
+            const scene2 = new Scene({ name: 'Scene2' });
+            const entity2 = scene2.createEntity('Entity');
+            Object.defineProperty(entity2, 'id', { value: entity1.id, writable: true });
+
+            scene2.applyIncremental(incremental);
+
+            expect(entity2.hasComponent(PositionComponent)).toBe(true);
+            const pos = entity2.getComponent(PositionComponent);
+            expect(pos!.x).toBe(100);
+            expect(pos!.y).toBe(200);
+
+            scene1.end();
+            scene2.end();
+        });
+
+        it('应该应用组件删除变更', () => {
+            const scene1 = new Scene({ name: 'Scene1' });
+            const entity1 = scene1.createEntity('Entity');
+            entity1.addComponent(new PositionComponent(10, 20));
+            scene1.createIncrementalSnapshot();
+
+            entity1.removeComponentByType(PositionComponent);
+
+            const incremental = scene1.serializeIncremental();
+
+            const scene2 = new Scene({ name: 'Scene2' });
+            const entity2 = scene2.createEntity('Entity');
+            Object.defineProperty(entity2, 'id', { value: entity1.id, writable: true });
+            entity2.addComponent(new PositionComponent(10, 20));
+
+            scene2.applyIncremental(incremental);
+
+            expect(entity2.hasComponent(PositionComponent)).toBe(false);
+
+            scene1.end();
+            scene2.end();
+        });
+
+        it('应该应用组件数据更新', () => {
+            const scene1 = new Scene({ name: 'Scene1' });
+            const entity1 = scene1.createEntity('Entity');
+            const pos1 = new PositionComponent(10, 20);
+            entity1.addComponent(pos1);
+            scene1.createIncrementalSnapshot();
+
+            pos1.x = 100;
+            pos1.y = 200;
+
+            const incremental = scene1.serializeIncremental();
+
+            const scene2 = new Scene({ name: 'Scene2' });
+            const entity2 = scene2.createEntity('Entity');
+            Object.defineProperty(entity2, 'id', { value: entity1.id, writable: true });
+            entity2.addComponent(new PositionComponent(10, 20));
+
+            scene2.applyIncremental(incremental);
+
+            const pos2 = entity2.getComponent(PositionComponent);
+            expect(pos2!.x).toBe(100);
+            expect(pos2!.y).toBe(200);
+
+            scene1.end();
+            scene2.end();
+        });
+
+        it('应该应用场景数据变更', () => {
+            const scene1 = new Scene({ name: 'Scene1' });
+            scene1.createIncrementalSnapshot();
+
+            scene1.sceneData.set('weather', 'sunny');
+            scene1.sceneData.set('time', 12.5);
+
+            const incremental = scene1.serializeIncremental();
+
+            const scene2 = new Scene({ name: 'Scene2' });
+            scene2.applyIncremental(incremental);
+
+            expect(scene2.sceneData.get('weather')).toBe('sunny');
+            expect(scene2.sceneData.get('time')).toBe(12.5);
+
+            scene1.end();
+            scene2.end();
+        });
+    });
+
+    describe('Incremental Serialization', () => {
+        it('应该序列化和反序列化增量快照', () => {
+            scene.createIncrementalSnapshot();
+
+            const entity = scene.createEntity('Entity');
+            entity.addComponent(new PositionComponent(50, 100));
+
+            const incremental = scene.serializeIncremental();
+            const json = IncrementalSerializer.serializeIncremental(incremental);
+
+            expect(typeof json).toBe('string');
+
+            const deserialized = IncrementalSerializer.deserializeIncremental(json);
+            expect(deserialized.version).toBe(incremental.version);
+            expect(deserialized.entityChanges.length).toBe(incremental.entityChanges.length);
+        });
+
+        it('应该美化JSON输出', () => {
+            scene.createIncrementalSnapshot();
+            const entity = scene.createEntity('Entity');
+            entity.addComponent(new PositionComponent(10, 20));
+
+            const incremental = scene.serializeIncremental();
+            const prettyJson = IncrementalSerializer.serializeIncremental(incremental, true);
+
+            expect(prettyJson).toContain('\n');
+            expect(prettyJson).toContain('  ');
+        });
+    });
+
+    describe('Snapshot Management', () => {
+        it('应该更新增量快照基准', () => {
+            const entity = scene.createEntity('Entity');
+            scene.createIncrementalSnapshot();
+
+            entity.addComponent(new PositionComponent(10, 20));
+            const incremental1 = scene.serializeIncremental();
+
+            scene.updateIncrementalSnapshot();
+
+            const pos = entity.getComponent(PositionComponent)!;
+            pos.x = 100;
+
+            const incremental2 = scene.serializeIncremental();
+
+            // incremental2应该只包含Position的更新，不包含添加
+            expect(incremental1.componentChanges.length).toBe(1);
+            expect(incremental2.componentChanges.length).toBe(1);
+            expect(incremental2.componentChanges[0].operation).toBe(ChangeOperation.ComponentUpdated);
+        });
+
+        it('应该清除增量快照', () => {
+            scene.createIncrementalSnapshot();
+            expect(scene.hasIncrementalSnapshot()).toBe(true);
+
+            scene.clearIncrementalSnapshot();
+            expect(scene.hasIncrementalSnapshot()).toBe(false);
+        });
+
+        it('应该在没有快照时抛出错误', () => {
+            expect(() => {
+                scene.serializeIncremental();
+            }).toThrow('必须先调用 createIncrementalSnapshot() 创建基础快照');
+        });
+    });
+
+    describe('Statistics and Utilities', () => {
+        it('应该计算增量快照大小', () => {
+            scene.createIncrementalSnapshot();
+            const entity = scene.createEntity('Entity');
+            entity.addComponent(new PositionComponent(10, 20));
+
+            const incremental = scene.serializeIncremental();
+            const size = IncrementalSerializer.getIncrementalSize(incremental);
+
+            expect(size).toBeGreaterThan(0);
+        });
+
+        it('应该提供增量快照统计信息', () => {
+            const entity1 = scene.createEntity('Entity1');
+            entity1.addComponent(new PositionComponent(10, 20));
+            scene.createIncrementalSnapshot();
+
+            const entity2 = scene.createEntity('Entity2');
+            entity2.addComponent(new VelocityComponent());
+            entity1.destroy();
+
+            const incremental = scene.serializeIncremental();
+            const stats = IncrementalSerializer.getIncrementalStats(incremental);
+
+            expect(stats.addedEntities).toBe(1);
+            expect(stats.removedEntities).toBe(1);
+            expect(stats.addedComponents).toBe(1);
+            expect(stats.totalChanges).toBeGreaterThan(0);
+        });
+    });
+
+    describe('Performance and Edge Cases', () => {
+        it('应该处理大量实体变更', () => {
+            scene.createIncrementalSnapshot();
+
+            for (let i = 0; i < 100; i++) {
+                const entity = scene.createEntity(`Entity_${i}`);
+                entity.addComponent(new PositionComponent(i, i * 2));
+            }
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.entityChanges.length).toBe(100);
+            expect(incremental.componentChanges.length).toBe(100);
+        });
+
+        it('应该处理空变更', () => {
+            scene.createIncrementalSnapshot();
+
+            const incremental = scene.serializeIncremental();
+
+            expect(incremental.entityChanges.length).toBe(0);
+            expect(incremental.componentChanges.length).toBe(0);
+            expect(incremental.sceneDataChanges.length).toBe(0);
+        });
+
+        it('应该处理复杂嵌套场景数据', () => {
+            scene.createIncrementalSnapshot();
+
+            scene.sceneData.set('config', {
+                nested: {
+                    deep: {
+                        value: 42
+                    }
+                },
+                array: [1, 2, 3]
+            });
+
+            const incremental = scene.serializeIncremental();
+            const scene2 = new Scene({ name: 'Scene2' });
+            scene2.applyIncremental(incremental);
+
+            const config = scene2.sceneData.get('config');
+            expect(config.nested.deep.value).toBe(42);
+            expect(config.array).toEqual([1, 2, 3]);
+
+            scene2.end();
+        });
+
+        it('应该正确处理快照版本号', () => {
+            IncrementalSerializer.resetVersion();
+
+            const snapshot1 = IncrementalSerializer.createSnapshot(scene);
+            expect(snapshot1.version).toBe(1);
+
+            const snapshot2 = IncrementalSerializer.createSnapshot(scene);
+            expect(snapshot2.version).toBe(2);
+        });
+    });
+});