《Cocos 游戏联机实战》1.3 时钟、延迟与抖动

// assets/scripts/net/session/clock-sync.ts

/** 一次往返采样的四个时间戳 */
export interface ClockSample {
  t0: number; // 客户端发出（本地单调 ms）
  t1: number; // 服务端收到（服务端时钟 ms）
  t2: number; // 服务端回复（服务端时钟 ms）
  t3: number; // 客户端收到回复（本地单调 ms）
}

const SMOOTH_ALPHA = 0.1; // 滑动平均系数，越小越平稳、越大越灵敏

export class ClockSync {
  private readonly localNow: () => number;
  private bestRtt = Number.POSITIVE_INFINITY;
  private bestOffset = 0;
  private smoothOffset = 0;
  private haveSmooth = false;
  private lastRtt = 0;
  private jitter = 0;
  private sampleCount = 0;

  constructor(localNow: () => number) {
    this.localNow = localNow;
  }

  /** 喂入一次四元组，更新偏移、RTT 与抖动估计 */
  addSample(s: ClockSample): void {
    const rtt = (s.t3 - s.t0) - (s.t2 - s.t1);
    const offset = ((s.t1 - s.t0) + (s.t2 - s.t3)) / 2;
    this.sampleCount += 1;

    // 最小 RTT 的样本路径最对称，作权威偏移
    if (rtt < this.bestRtt) {
      this.bestRtt = rtt;
      this.bestOffset = offset;
    }

    // 滑动平均给一个平稳的展示值
    if (!this.haveSmooth) {
      this.smoothOffset = offset;
      this.haveSmooth = true;
    } else {
      this.smoothOffset += SMOOTH_ALPHA * (offset - this.smoothOffset);
    }

    // 抖动：相邻 RTT 绝对差的滑动平均
    this.jitter += SMOOTH_ALPHA * (Math.abs(rtt - this.lastRtt) - this.jitter);
    this.lastRtt = rtt;
  }

  /** 本地单调时间 → 估计的服务端时间 */
  serverTime(localMs: number): number {
    return localMs + this.bestOffset;
  }

  /** 服务端时间 → 估计的本地单调时间（和解时会用到） */
  localTime(serverMs: number): number {
    return serverMs - this.bestOffset;
  }

  get offsetMs(): number {
    return this.bestOffset;
  }

  get smoothedOffsetMs(): number {
    return this.smoothOffset;
  }

  get rttMs(): number {
    return this.bestRtt === Number.POSITIVE_INFINITY ? 0 : this.bestRtt;
  }

  get jitterMs(): number {
    return this.jitter;
  }

  get count(): number {
    return this.sampleCount;
  }
}

// assets/scripts/net/session/clock-sync.test.ts
import { describe, expect, it } from 'vitest';
import { ClockSync, type ClockSample } from './clock-sync';

function makeSample(
  local: number,
  downMs: number,
  upMs: number,
  procMs: number,
  trueOffset: number,
): ClockSample {
  const t0 = local;
  const t1 = t0 + downMs + trueOffset; // 服务端钟 = 本地钟 + trueOffset
  const t2 = t1 + procMs;
  const t3 = t0 + downMs + procMs + upMs;
  return { t0, t1, t2, t3 };
}

describe('时钟同步', () => {
  it('对称路径下偏移收敛到真实值', () => {
    const sync = new ClockSync(() => 0);
    const trueOffset = 1000;
    const rtts = [120, 40, 80, 40, 60];
    let local = 0;
    for (const rtt of rtts) {
      const half = rtt / 2;
      sync.addSample(makeSample(local, half, half, 2, trueOffset));
      local += 200;
    }
    expect(sync.offsetMs).toBeCloseTo(trueOffset, 6);
  });

  it('RTT 取所有样本中的最小值', () => {
    const sync = new ClockSync(() => 0);
    sync.addSample(makeSample(0, 60, 60, 0, 500)); // rtt 120
    sync.addSample(makeSample(0, 20, 20, 0, 500)); // rtt 40 ← 最小
    sync.addSample(makeSample(0, 40, 40, 0, 500)); // rtt 80
    expect(sync.rttMs).toBeCloseTo(40, 6);
  });

  it('抖动随 RTT 波动累积', () => {
    const sync = new ClockSync(() => 0);
    sync.addSample(makeSample(0, 10, 10, 0, 0)); // rtt 20
    sync.addSample(makeSample(0, 60, 60, 0, 0)); // rtt 120，波动大
    expect(sync.jitterMs).toBeGreaterThan(0);
  });
});

import { _decorator, Component, game } from 'cc';

const { ccclass } = _decorator;

@ccclass('LocalClock')
export class LocalClock extends Component {
  /** 单调毫秒，作为 ClockSync 的本地时间来源 */
  now(): number {
    return game.totalTime;
  }
}