更新序列化文档

docs/guide/index.md

@@ -19,6 +19,9 @@
 ### [事件系统 (Event)](./event-system.md)
 掌握类型安全的事件系统，实现组件间通信和系统协作。
 
+### [序列化系统 (Serialization)](./serialization.md)
+掌握场景、实体和组件的序列化方案，支持全量序列化和增量序列化，实现游戏存档、网络同步等功能。
+
 ### [时间和定时器 (Time)](./time-and-timers.md)
 学习时间管理和定时器系统，实现游戏逻辑的精确时间控制。
 

docs/guide/serialization.md

@@ -0,0 +1,775 @@
+# 序列化系统
+
+序列化系统提供了完整的场景、实体和组件数据持久化方案，支持全量序列化和增量序列化两种模式，适用于游戏存档、网络同步、场景编辑器、时间回溯等场景。
+
+## 基本概念
+
+序列化系统分为两个层次：
+
+- **全量序列化**：序列化完整的场景状态，包括所有实体、组件和场景数据
+- **增量序列化**：只序列化相对于基础快照的变更部分，大幅减少数据量
+
+### 支持的数据格式
+
+- **JSON格式**：人类可读，便于调试和编辑
+- **Binary格式**：使用MessagePack，体积更小，性能更高
+
+## 全量序列化
+
+### 基础用法
+
+#### 1. 标记可序列化组件
+
+使用 `@Serializable` 和 `@Serialize` 装饰器标记需要序列化的组件和字段：
+
+```typescript
+import { Component, ECSComponent, Serializable, Serialize } from '@esengine/ecs-framework';
+
+@ECSComponent('Player')
+@Serializable({ version: 1 })
+class PlayerComponent extends Component {
+  @Serialize()
+  public name: string = '';
+
+  @Serialize()
+  public level: number = 1;
+
+  @Serialize()
+  public experience: number = 0;
+
+  @Serialize()
+  public position: { x: number; y: number } = { x: 0, y: 0 };
+
+  // 不使用 @Serialize() 的字段不会被序列化
+  private tempData: any = null;
+}
+```
+
+#### 2. 序列化场景
+
+```typescript
+// JSON格式序列化
+const jsonData = scene.serialize({
+  format: 'json',
+  pretty: true  // 美化输出
+});
+
+// 保存到本地存储
+localStorage.setItem('gameSave', jsonData);
+
+// Binary格式序列化（更小的体积）
+const binaryData = scene.serialize({
+  format: 'binary'
+});
+
+// 保存为文件（Node.js环境）
+fs.writeFileSync('save.bin', binaryData);
+```
+
+#### 3. 反序列化场景
+
+```typescript
+// 从JSON恢复
+const saveData = localStorage.getItem('gameSave');
+if (saveData) {
+  scene.deserialize(saveData, {
+    strategy: 'replace'  // 替换当前场景内容
+  });
+}
+
+// 从Binary恢复
+const binaryData = fs.readFileSync('save.bin');
+scene.deserialize(binaryData, {
+  strategy: 'merge'  // 合并到现有场景
+});
+```
+
+### 序列化选项
+
+#### SerializationOptions
+
+```typescript
+interface SceneSerializationOptions {
+  // 指定要序列化的组件类型（可选）
+  components?: ComponentType[];
+
+  // 序列化格式：'json' 或 'binary'
+  format?: 'json' | 'binary';
+
+  // JSON美化输出
+  pretty?: boolean;
+
+  // 包含元数据
+  includeMetadata?: boolean;
+}
+```
+
+示例：
+
+```typescript
+// 只序列化特定组件类型
+const saveData = scene.serialize({
+  format: 'json',
+  components: [PlayerComponent, InventoryComponent],
+  pretty: true,
+  includeMetadata: true
+});
+```
+
+#### DeserializationOptions
+
+```typescript
+interface SceneDeserializationOptions {
+  // 反序列化策略
+  strategy?: 'merge' | 'replace';
+
+  // 组件类型注册表（可选，默认使用全局注册表）
+  componentRegistry?: Map<string, ComponentType>;
+}
+```
+
+### 高级装饰器
+
+#### 字段序列化选项
+
+```typescript
+@ECSComponent('Advanced')
+@Serializable({ version: 1 })
+class AdvancedComponent extends Component {
+  // 使用别名
+  @Serialize({ alias: 'playerName' })
+  public name: string = '';
+
+  // 自定义序列化器
+  @Serialize({
+    serializer: (value: Date) => value.toISOString(),
+    deserializer: (value: string) => new Date(value)
+  })
+  public createdAt: Date = new Date();
+
+  // 忽略序列化
+  @IgnoreSerialization()
+  public cachedData: any = null;
+}
+```
+
+#### 集合类型序列化
+
+```typescript
+@ECSComponent('Collections')
+@Serializable({ version: 1 })
+class CollectionsComponent extends Component {
+  // Map序列化
+  @SerializeAsMap()
+  public inventory: Map<string, number> = new Map();
+
+  // Set序列化
+  @SerializeAsSet()
+  public acquiredSkills: Set<string> = new Set();
+
+  constructor() {
+    super();
+    this.inventory.set('gold', 100);
+    this.inventory.set('silver', 50);
+    this.acquiredSkills.add('attack');
+    this.acquiredSkills.add('defense');
+  }
+}
+```
+
+### 场景自定义数据
+
+除了实体和组件，还可以序列化场景级别的配置数据：
+
+```typescript
+// 设置场景数据
+scene.sceneData.set('weather', 'rainy');
+scene.sceneData.set('difficulty', 'hard');
+scene.sceneData.set('checkpoint', { x: 100, y: 200 });
+
+// 序列化时会自动包含场景数据
+const saveData = scene.serialize({ format: 'json' });
+
+// 反序列化后场景数据会恢复
+scene.deserialize(saveData);
+console.log(scene.sceneData.get('weather')); // 'rainy'
+```
+
+## 增量序列化
+
+增量序列化只保存场景的变更部分，适用于网络同步、撤销/重做、时间回溯等需要频繁保存状态的场景。
+
+### 基础用法
+
+#### 1. 创建基础快照
+
+```typescript
+// 在需要开始记录变更前创建基础快照
+scene.createIncrementalSnapshot();
+```
+
+#### 2. 修改场景
+
+```typescript
+// 添加实体
+const enemy = scene.createEntity('Enemy');
+enemy.addComponent(new PositionComponent(100, 200));
+enemy.addComponent(new HealthComponent(50));
+
+// 修改组件
+const player = scene.findEntity('Player');
+const pos = player.getComponent(PositionComponent);
+pos.x = 300;
+pos.y = 400;
+
+// 删除组件
+player.removeComponentByType(BuffComponent);
+
+// 删除实体
+const oldEntity = scene.findEntity('ToDelete');
+oldEntity.destroy();
+
+// 修改场景数据
+scene.sceneData.set('score', 1000);
+```
+
+#### 3. 获取增量变更
+
+```typescript
+// 获取相对于基础快照的所有变更
+const incremental = scene.serializeIncremental();
+
+// 查看变更统计
+const stats = IncrementalSerializer.getIncrementalStats(incremental);
+console.log('总变更数:', stats.totalChanges);
+console.log('新增实体:', stats.addedEntities);
+console.log('删除实体:', stats.removedEntities);
+console.log('新增组件:', stats.addedComponents);
+console.log('更新组件:', stats.updatedComponents);
+```
+
+#### 4. 序列化增量数据
+
+```typescript
+// 转换为JSON字符串
+const json = IncrementalSerializer.serializeIncremental(incremental);
+
+// 发送到服务器或保存
+socket.send(json);
+// 或
+localStorage.setItem('changes', json);
+```
+
+#### 5. 应用增量变更
+
+```typescript
+// 在另一个场景应用变更
+const otherScene = new Scene();
+
+// 从JSON字符串应用
+otherScene.applyIncremental(json);
+
+// 或直接应用增量对象
+otherScene.applyIncremental(incremental);
+```
+
+### 增量快照管理
+
+#### 更新快照基准
+
+在应用增量变更后，可以更新快照基准：
+
+```typescript
+// 创建初始快照
+scene.createIncrementalSnapshot();
+
+// 第一次修改
+entity.addComponent(new VelocityComponent(5, 0));
+const incremental1 = scene.serializeIncremental();
+
+// 更新基准（将当前状态设为新的基准）
+scene.updateIncrementalSnapshot();
+
+// 第二次修改（增量将基于更新后的基准）
+entity.getComponent(VelocityComponent).dx = 10;
+const incremental2 = scene.serializeIncremental();
+```
+
+#### 清除快照
+
+```typescript
+// 释放快照占用的内存
+scene.clearIncrementalSnapshot();
+
+// 检查是否有快照
+if (scene.hasIncrementalSnapshot()) {
+  console.log('存在增量快照');
+}
+```
+
+### 增量序列化选项
+
+```typescript
+interface IncrementalSerializationOptions {
+  // 是否进行组件数据的深度对比
+  // 默认true，设为false可提升性能但可能漏掉组件内部字段变更
+  deepComponentComparison?: boolean;
+
+  // 是否跟踪场景数据变更
+  // 默认true
+  trackSceneData?: boolean;
+
+  // 是否压缩快照（使用JSON序列化）
+  // 默认false
+  compressSnapshot?: boolean;
+}
+
+// 使用选项
+scene.createIncrementalSnapshot({
+  deepComponentComparison: true,
+  trackSceneData: true
+});
+```
+
+### 增量数据结构
+
+增量快照包含以下变更类型：
+
+```typescript
+interface IncrementalSnapshot {
+  version: number;           // 快照版本号
+  timestamp: number;         // 时间戳
+  sceneName: string;         // 场景名称
+  baseVersion: number;       // 基础版本号
+  entityChanges: EntityChange[];      // 实体变更
+  componentChanges: ComponentChange[]; // 组件变更
+  sceneDataChanges: SceneDataChange[]; // 场景数据变更
+}
+
+// 变更操作类型
+enum ChangeOperation {
+  EntityAdded = 'entity_added',
+  EntityRemoved = 'entity_removed',
+  EntityUpdated = 'entity_updated',
+  ComponentAdded = 'component_added',
+  ComponentRemoved = 'component_removed',
+  ComponentUpdated = 'component_updated',
+  SceneDataUpdated = 'scene_data_updated'
+}
+```
+
+## 版本迁移
+
+当组件结构发生变化时，版本迁移系统可以自动升级旧版本的存档数据。
+
+### 注册迁移函数
+
+```typescript
+import { VersionMigrationManager } from '@esengine/ecs-framework';
+
+// 假设 PlayerComponent v1 有 hp 字段
+// v2 改为 health 和 maxHealth 字段
+
+// 注册从版本1到版本2的迁移
+VersionMigrationManager.registerComponentMigration(
+  'Player',
+  1,  // 从版本
+  2,  // 到版本
+  (data) => {
+    // 迁移逻辑
+    const newData = {
+      ...data,
+      health: data.hp,
+      maxHealth: data.hp,
+    };
+    delete newData.hp;
+    return newData;
+  }
+);
+```
+
+### 使用迁移构建器
+
+```typescript
+import { MigrationBuilder } from '@esengine/ecs-framework';
+
+new MigrationBuilder()
+  .forComponent('Player')
+  .fromVersionToVersion(2, 3)
+  .migrate((data) => {
+    // 从版本2迁移到版本3
+    data.experience = data.exp || 0;
+    delete data.exp;
+    return data;
+  });
+```
+
+### 场景级迁移
+
+```typescript
+// 注册场景级迁移
+VersionMigrationManager.registerSceneMigration(
+  1,  // 从版本
+  2,  // 到版本
+  (scene) => {
+    // 迁移场景结构
+    scene.metadata = {
+      ...scene.metadata,
+      migratedFrom: 1
+    };
+    return scene;
+  }
+);
+```
+
+### 检查迁移路径
+
+```typescript
+// 检查是否可以迁移
+const canMigrate = VersionMigrationManager.canMigrateComponent(
+  'Player',
+  1,  // 从版本
+  3   // 到版本
+);
+
+if (canMigrate) {
+  // 可以安全迁移
+  scene.deserialize(oldSaveData);
+}
+
+// 获取迁移路径
+const path = VersionMigrationManager.getComponentMigrationPath('Player');
+console.log('可用迁移版本:', path); // [1, 2, 3]
+```
+
+## 使用场景
+
+### 游戏存档系统
+
+```typescript
+class SaveSystem {
+  private static SAVE_KEY = 'game_save';
+
+  // 保存游戏
+  public static saveGame(scene: Scene): void {
+    const saveData = scene.serialize({
+      format: 'json',
+      pretty: false
+    });
+
+    localStorage.setItem(this.SAVE_KEY, saveData);
+    console.log('游戏已保存');
+  }
+
+  // 加载游戏
+  public static loadGame(scene: Scene): boolean {
+    const saveData = localStorage.getItem(this.SAVE_KEY);
+    if (saveData) {
+      scene.deserialize(saveData, {
+        strategy: 'replace'
+      });
+      console.log('游戏已加载');
+      return true;
+    }
+    return false;
+  }
+
+  // 检查是否有存档
+  public static hasSave(): boolean {
+    return localStorage.getItem(this.SAVE_KEY) !== null;
+  }
+}
+```
+
+### 网络同步
+
+```typescript
+class NetworkSync {
+  private baseSnapshot?: any;
+  private syncInterval: number = 100; // 100ms同步一次
+
+  constructor(private scene: Scene, private socket: WebSocket) {
+    this.setupSync();
+  }
+
+  private setupSync(): void {
+    // 创建基础快照
+    this.scene.createIncrementalSnapshot();
+
+    // 定期发送增量
+    setInterval(() => {
+      this.sendIncremental();
+    }, this.syncInterval);
+
+    // 接收远程增量
+    this.socket.onmessage = (event) => {
+      this.receiveIncremental(event.data);
+    };
+  }
+
+  private sendIncremental(): void {
+    const incremental = this.scene.serializeIncremental();
+    const stats = IncrementalSerializer.getIncrementalStats(incremental);
+
+    // 只在有变更时发送
+    if (stats.totalChanges > 0) {
+      const json = IncrementalSerializer.serializeIncremental(incremental);
+      this.socket.send(json);
+
+      // 更新基准
+      this.scene.updateIncrementalSnapshot();
+    }
+  }
+
+  private receiveIncremental(data: string): void {
+    const incremental = IncrementalSerializer.deserializeIncremental(data);
+    this.scene.applyIncremental(incremental);
+  }
+}
+```
+
+### 撤销/重做系统
+
+```typescript
+class UndoRedoSystem {
+  private history: IncrementalSnapshot[] = [];
+  private currentIndex: number = -1;
+  private maxHistory: number = 50;
+
+  constructor(private scene: Scene) {
+    // 创建初始快照
+    this.scene.createIncrementalSnapshot();
+    this.saveState('Initial');
+  }
+
+  // 保存当前状态
+  public saveState(label: string): void {
+    const incremental = this.scene.serializeIncremental();
+
+    // 删除当前位置之后的历史
+    this.history = this.history.slice(0, this.currentIndex + 1);
+
+    // 添加新状态
+    this.history.push(incremental);
+    this.currentIndex++;
+
+    // 限制历史记录数量
+    if (this.history.length > this.maxHistory) {
+      this.history.shift();
+      this.currentIndex--;
+    }
+
+    // 更新快照基准
+    this.scene.updateIncrementalSnapshot();
+  }
+
+  // 撤销
+  public undo(): boolean {
+    if (this.currentIndex > 0) {
+      this.currentIndex--;
+      const incremental = this.history[this.currentIndex];
+      this.scene.applyIncremental(incremental);
+      return true;
+    }
+    return false;
+  }
+
+  // 重做
+  public redo(): boolean {
+    if (this.currentIndex < this.history.length - 1) {
+      this.currentIndex++;
+      const incremental = this.history[this.currentIndex];
+      this.scene.applyIncremental(incremental);
+      return true;
+    }
+    return false;
+  }
+
+  public canUndo(): boolean {
+    return this.currentIndex > 0;
+  }
+
+  public canRedo(): boolean {
+    return this.currentIndex < this.history.length - 1;
+  }
+}
+```
+
+### 关卡编辑器
+
+```typescript
+class LevelEditor {
+  // 导出关卡
+  public exportLevel(scene: Scene, filename: string): void {
+    const levelData = scene.serialize({
+      format: 'json',
+      pretty: true,
+      includeMetadata: true
+    });
+
+    // 浏览器环境
+    const blob = new Blob([levelData], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+
+  // 导入关卡
+  public importLevel(scene: Scene, fileContent: string): void {
+    scene.deserialize(fileContent, {
+      strategy: 'replace'
+    });
+  }
+
+  // 验证关卡数据
+  public validateLevel(saveData: string): boolean {
+    const validation = SceneSerializer.validate(saveData);
+    if (!validation.valid) {
+      console.error('关卡数据无效:', validation.errors);
+      return false;
+    }
+    return true;
+  }
+
+  // 获取关卡信息（不完全反序列化）
+  public getLevelInfo(saveData: string): any {
+    const info = SceneSerializer.getInfo(saveData);
+    return info;
+  }
+}
+```
+
+## 性能优化建议
+
+### 1. 选择合适的格式
+
+- **开发阶段**：使用JSON格式，便于调试和查看
+- **生产环境**：使用Binary格式，减少30-50%的数据大小
+
+### 2. 按需序列化
+
+```typescript
+// 只序列化需要持久化的组件
+const saveData = scene.serialize({
+  format: 'binary',
+  components: [PlayerComponent, InventoryComponent, QuestComponent]
+});
+```
+
+### 3. 增量序列化优化
+
+```typescript
+// 对于高频同步，关闭深度对比以提升性能
+scene.createIncrementalSnapshot({
+  deepComponentComparison: false  // 只检测组件的添加/删除
+});
+```
+
+### 4. 批量操作
+
+```typescript
+// 批量修改后再序列化
+scene.entities.buffer.forEach(entity => {
+  // 批量修改
+});
+
+// 一次性序列化所有变更
+const incremental = scene.serializeIncremental();
+```
+
+## 最佳实践
+
+### 1. 明确序列化字段
+
+```typescript
+// 明确标记需要序列化的字段
+@ECSComponent('Player')
+@Serializable({ version: 1 })
+class PlayerComponent extends Component {
+  @Serialize()
+  public name: string = '';
+
+  @Serialize()
+  public level: number = 1;
+
+  // 运行时数据不序列化
+  private _cachedSprite: any = null;
+}
+```
+
+### 2. 使用版本控制
+
+```typescript
+// 为组件指定版本
+@Serializable({ version: 2 })
+class PlayerComponent extends Component {
+  // 版本2的字段
+}
+
+// 注册迁移函数确保兼容性
+VersionMigrationManager.registerComponentMigration('Player', 1, 2, migrateV1ToV2);
+```
+
+### 3. 避免循环引用
+
+```typescript
+// 不要在组件中直接引用其他实体
+@ECSComponent('Follower')
+@Serializable({ version: 1 })
+class FollowerComponent extends Component {
+  // 存储实体ID而不是实体引用
+  @Serialize()
+  public targetId: number = 0;
+
+  // 通过场景查找目标实体
+  public getTarget(scene: Scene): Entity | null {
+    return scene.entities.findEntityById(this.targetId);
+  }
+}
+```
+
+### 4. 压缩大数据
+
+```typescript
+// 对于大型数据结构，使用自定义序列化
+@ECSComponent('LargeData')
+@Serializable({ version: 1 })
+class LargeDataComponent extends Component {
+  @Serialize({
+    serializer: (data: LargeObject) => compressData(data),
+    deserializer: (data: CompressedData) => decompressData(data)
+  })
+  public data: LargeObject;
+}
+```
+
+## API参考
+
+### 全量序列化API
+
+- `scene.serialize(options?): string | Buffer` - 序列化场景
+- `scene.deserialize(data, options?)` - 反序列化场景
+- `SceneSerializer.validate(data)` - 验证序列化数据
+- `SceneSerializer.getInfo(data)` - 获取序列化数据信息
+
+### 增量序列化API
+
+- `scene.createIncrementalSnapshot(options?)` - 创建基础快照
+- `scene.serializeIncremental(options?)` - 获取增量变更
+- `scene.applyIncremental(incremental)` - 应用增量变更
+- `scene.updateIncrementalSnapshot(options?)` - 更新快照基准
+- `scene.clearIncrementalSnapshot()` - 清除快照
+- `scene.hasIncrementalSnapshot()` - 检查是否有快照
+- `IncrementalSerializer.getIncrementalStats(incremental)` - 获取统计信息
+
+### 版本迁移API
+
+- `VersionMigrationManager.registerComponentMigration()` - 注册组件迁移
+- `VersionMigrationManager.registerSceneMigration()` - 注册场景迁移
+- `VersionMigrationManager.canMigrateComponent()` - 检查是否可以迁移
+- `VersionMigrationManager.getComponentMigrationPath()` - 获取迁移路径
+
+序列化系统是构建完整游戏的重要基础设施，合理使用可以实现强大的功能，如存档系统、网络同步、关卡编辑器等。

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

@@ -1,213 +0,0 @@
-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);
-        });
-    });
-});