《Cocos 游戏联机实战》3.1 快照与增量同步

// mini2d/net/snapshot.ts —— 纯 TS，无 cc 依赖
export type EntityId = number;
export type FieldValue = number;

export interface EntityState {
  id: EntityId;
  fields: Record<string, FieldValue>;
}

/** 世界状态：实体 id -> 实体状态 */
export type WorldState = Map<EntityId, EntityState>;

export interface EntityDiff {
  id: EntityId;
  /** 本帧发生变化的字段；全量快照时包含全部字段 */
  changed: Record<string, FieldValue>;
}

export interface Snapshot {
  /** 服务端逻辑帧号 */
  frame: number;
  /** true = 全量基线；false = 相对 baseFrame 的增量 */
  full: boolean;
  /** 增量所基于的基线帧号；全量时为 -1 */
  baseFrame: number;
  /** 新增或更新的实体 */
  changed: EntityDiff[];
  /** 本帧被移除的实体 id */
  removed: EntityId[];
}

/** 生成一帧全量基线 */
export function captureFull(frame: number, world: WorldState): Snapshot {
  const changed: EntityDiff[] = [];
  for (const [id, ent] of world) {
    changed.push({ id, changed: { ...ent.fields } });
  }
  return { frame, full: true, baseFrame: -1, changed, removed: [] };
}

/** 相对 prev 生成增量：逐字段比对，只收变化项 */
export function makeDelta(
  baseFrame: number,
  frame: number,
  prev: WorldState,
  next: WorldState,
): Snapshot {
  const changed: EntityDiff[] = [];
  for (const [id, ent] of next) {
    const before = prev.get(id);
    if (!before) {
      changed.push({ id, changed: { ...ent.fields } }); // 新实体：全字段
      continue;
    }
    const fields: Record<string, FieldValue> = {};
    for (const key of Object.keys(ent.fields)) {
      if (before.fields[key] !== ent.fields[key]) {
        fields[key] = ent.fields[key];
      }
    }
    if (Object.keys(fields).length > 0) {
      changed.push({ id, changed: fields });
    }
  }
  const removed: EntityId[] = [];
  for (const id of prev.keys()) {
    if (!next.has(id)) {
      removed.push(id);
    }
  }
  return { frame, full: false, baseFrame, changed, removed };
}

/** 把快照（全量或增量）叠加到客户端本地状态上，返回新状态 */
export function applySnapshot(state: WorldState, snap: Snapshot): WorldState {
  const out: WorldState = new Map();
  for (const [id, ent] of state) {
    out.set(id, { id, fields: { ...ent.fields } });
  }
  for (const id of snap.removed) {
    out.delete(id);
  }
  for (const diff of snap.changed) {
    const existing = out.get(diff.id);
    const fields = existing ? { ...existing.fields } : {};
    for (const key of Object.keys(diff.changed)) {
      fields[key] = diff.changed[key];
    }
    out.set(diff.id, { id: diff.id, fields });
  }
  return out;
}

import { describe, expect, it } from 'vitest';
import { applySnapshot, captureFull, makeDelta, type WorldState } from './snapshot';

function world(entries: Array<[number, Record<string, number>]>): WorldState {
  const w: WorldState = new Map();
  for (const [id, fields] of entries) {
    w.set(id, { id, fields });
  }
  return w;
}

function normalize(w: WorldState): Array<[number, Record<string, number>]> {
  return [...w.entries()]
    .map(([id, e]) => [id, e.fields] as [number, Record<string, number>])
    .sort((p, q) => p[0] - q[0]);
}

describe('snapshot diff/patch', () => {
  it('应用增量 == 直接全量覆盖', () => {
    const a = world([[1, { x: 0, y: 0 }], [2, { x: 10, y: 10 }]]);
    const b = world([[1, { x: 3, y: 0 }], [2, { x: 10, y: 4 }], [3, { x: 0, y: 0 }]]);

    const delta = makeDelta(1, 2, a, b);
    const patched = applySnapshot(a, delta);
    const full = applySnapshot(a, captureFull(2, b));

    expect(normalize(patched)).toEqual(normalize(full));
    // 且只发了真正变化的字段
    expect(delta.changed.find((d) => d.id === 1)?.changed).toEqual({ x: 3 });
  });

  it('丢一个 diff 包后，下一帧全量基线能恢复', () => {
    const a = world([[1, { x: 0, y: 0 }]]);
    const b = world([[1, { x: 3, y: 0 }]]);

    const lost = makeDelta(1, 2, a, b); // 这个增量包在网络里丢了
    void lost;

    // 客户端仍停在 a；服务端下一轮下发第 3 帧全量基线
    const recovered = applySnapshot(a, captureFull(3, b));
    expect(recovered.get(1)?.fields.x).toBe(3);
  });
});

{
  "type": "snapshot",
  "frame": 1842,
  "full": false,
  "baseFrame": 1841,
  "entities": [
    { "id": 1, "fields": { "x": 320 } },
    { "id": 7, "fields": { "y": 96, "vy": -4 } }
  ],
  "removed": [9]
}

import { _decorator, Component, Node } from 'cc';
const { ccclass } = _decorator;

@ccclass('RemoteEntityView')
export class RemoteEntityView extends Component {
  /** 实体 id -> 场景节点，节点由对象池预先创建 */
  private readonly views = new Map<number, Node>();

  /** 注册一个可复用的节点 */
  bind(id: number, node: Node): void {
    this.views.set(id, node);
  }

  /** 实体离开视野或消失：停用并解绑 */
  unbind(id: number): void {
    const node = this.views.get(id);
    if (node) {
      node.active = false;
    }
    this.views.delete(id);
  }

  /** 把服务端下发的逻辑坐标写到节点上（x / y 为逻辑像素） */
  apply(id: number, x: number, y: number): void {
    const node = this.views.get(id);
    if (!node) {
      return; // 本地还没为这个 id 建节点：交给 3.2 的 AOI 补一次全量
    }
    node.setPosition(x, y, 0);
  }
}