CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

新增增量序列化

Browse Source
This commit is contained in:
YHH
2025-10-09 12:30:04 +08:00
parent 072e68cf43
commit fd1bbb0e00
7 changed files with 2075 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

438
examples/core-demos/src/demos/IncrementalSerializationDemo.ts Normal file
View File

@@ -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();
}
}

7
examples/core-demos/src/demos/index.ts
View File

@@ -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,
// 更多demos可以在这里添加
IncrementalSerializationDemo,
WorkerSystemDemo
];

141
packages/core/src/ECS/Scene.ts
View File

@@ -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;
}
}

677
packages/core/src/ECS/Serialization/IncrementalSerializer.ts Normal file
View File

@@ -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;
}
}

10
packages/core/src/ECS/Serialization/index.ts
View File

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

213
packages/core/tests/ArchetypeVsComponentIndex.comparison.test.ts Normal file
View File

@@ -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);
});
});
});

593
packages/core/tests/ECS/Serialization/IncrementalSerialization.test.ts Normal file
View File

@@ -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);
});
});
});