《移动游戏产品的架构·网络、资源与热更新》5.1 状态同步与帧同步：客户端各做什么

// file: src/net/sync-roles.ts
// tier: L1
// verify: node --test test/net/sync-roles.test.ts

export type SyncMode = "state-sync" | "frame-sync";

export interface Duty {
  readonly area: string;
  readonly stateSync: string;
  readonly frameSync: string;
  readonly owner: "client" | "server" | "both";
}

export const CLIENT_DUTIES: readonly Duty[] = [
  {
    area: "输入采样",
    stateSync: "按本地帧采样，带序号与时间戳上行",
    frameSync: "按逻辑帧打包，进入待确认指令队列",
    owner: "client",
  },
  {
    area: "权威裁决",
    stateSync: "服务端计算移动、命中与伤害",
    frameSync: "各端按同一帧推进，服务端只收集与转发",
    owner: "server",
  },
  {
    area: "状态呈现",
    stateSync: "快照插值，短缺口用外推顶住",
    frameSync: "本地立即执行，等待他人的确认",
    owner: "client",
  },
  {
    area: "偏差纠正",
    stateSync: "以快照为准，平滑收敛到权威位置",
    frameSync: "周期性校验和比对，不一致就重同步",
    owner: "both",
  },
  {
    area: "随机与掉落",
    stateSync: "服务端生成，随快照一起下发",
    frameSync: "同一种子、同一序列，禁止本地取随机",
    owner: "server",
  },
];

export const MODE_NOTES: Readonly<Record<SyncMode, string>> = {
  "state-sync": "客户端负责采样、插值与表现，服务端负责裁决与广播快照",
  "frame-sync": "客户端负责按帧执行与校验和上报，服务端负责收集与转发指令",
};

export interface CadenceConfig {
  readonly serverHz: number;
  readonly inputHz: number;
  readonly snapshotBytes: number;
  readonly inputBytes: number;
}

export const ARK_CADENCE: CadenceConfig = {
  serverHz: 10,
  inputHz: 20,
  snapshotBytes: 350,
  inputBytes: 48,
};

export interface Traffic {
  readonly inputsPerSnapshot: number;
  readonly upBytesPerSec: number;
  readonly downBytesPerSec: number;
  readonly downUpRatio: number;
}

function assertPositive(value: number, name: string): void {
  if (!Number.isFinite(value) || value <= 0) {
    throw new RangeError(`${name} must be a positive finite number: ${value}`);
  }
}

export function trafficOf(config: CadenceConfig = ARK_CADENCE): Traffic {
  assertPositive(config.serverHz, "serverHz");
  assertPositive(config.inputHz, "inputHz");
  if (!Number.isFinite(config.snapshotBytes) || config.snapshotBytes < 0) {
    throw new RangeError(`snapshotBytes must be non-negative: ${config.snapshotBytes}`);
  }
  if (!Number.isFinite(config.inputBytes) || config.inputBytes < 0) {
    throw new RangeError(`inputBytes must be non-negative: ${config.inputBytes}`);
  }
  const upBytesPerSec = config.inputBytes * config.inputHz;
  const downBytesPerSec = config.snapshotBytes * config.serverHz;
  return {
    inputsPerSnapshot: config.inputHz / config.serverHz,
    upBytesPerSec,
    downBytesPerSec,
    downUpRatio: upBytesPerSec === 0 ? Number.POSITIVE_INFINITY : downBytesPerSec / upBytesPerSec,
  };
}

export function dutyFor(area: string): Duty | undefined {
  return CLIENT_DUTIES.find((duty) => duty.area === area);
}

export function clientOwnedAreas(): readonly string[] {
  return CLIENT_DUTIES.filter((duty) => duty.owner !== "server").map((duty) => duty.area);
}

export function planSnapshotBuffer(bufferMs: number, config: CadenceConfig = ARK_CADENCE): number {
  if (!Number.isFinite(bufferMs) || bufferMs < 0) {
    throw new RangeError(`bufferMs must be a non-negative finite number: ${bufferMs}`);
  }
  assertPositive(config.serverHz, "serverHz");
  const intervalMs = 1000 / config.serverHz;
  return Math.max(2, Math.ceil(bufferMs / intervalMs) + 1);
}

export function describeCadence(config: CadenceConfig = ARK_CADENCE): string {
  const traffic = trafficOf(config);
  return (
    `服务端 ${config.serverHz}Hz 快照、客户端 ${config.inputHz}Hz 输入：` +
    `每个快照对应 ${traffic.inputsPerSnapshot} 条输入，` +
    `上行 ${traffic.upBytesPerSec}B/s、下行 ${traffic.downBytesPerSec}B/s`
  );
}