《Cocos 游戏联机实战》1.1 网络分层、拓扑与权威边界

// assets/scripts/net/transport/transport.ts
export interface Transport {
  /** 发送一帧字节。实现负责在连接未就绪时自行缓冲或丢弃。 */
  send(payload: Uint8Array): void;
  /** 注册唯一的消息回调；同一时刻只允许一个监听者。 */
  onMessage(listener: (payload: Uint8Array) => void): void;
  /** 主动关闭连接；关闭后 send 应为空操作。 */
  close(): void;
}

// assets/scripts/net/transport/fake-transport.ts
import type { Transport } from './transport';

export interface FakeTransportOptions {
  latencyMs: number;
  jitterMs?: number;
  lossRate?: number;
  /** 单调时间来源，测试里换成假时钟 */
  now: () => number;
  /** 随机源，测试里换成确定性序列 */
  rand?: () => number;
}

interface InFlight {
  deliverAt: number;
  payload: Uint8Array;
}

export class FakeTransport implements Transport {
  readonly name: string;
  private readonly latencyMs: number;
  private readonly jitterMs: number;
  private readonly lossRate: number;
  private readonly now: () => number;
  private readonly rand: () => number;

  private peer: FakeTransport | null = null;
  private listener: ((payload: Uint8Array) => void) | null = null;
  private queue: InFlight[] = [];
  private closed = false;
  private sentCount = 0;
  private droppedCount = 0;

  constructor(name: string, options: FakeTransportOptions) {
    this.name = name;
    this.latencyMs = options.latencyMs;
    this.jitterMs = options.jitterMs ?? 0;
    this.lossRate = options.lossRate ?? 0;
    this.now = options.now;
    this.rand = options.rand ?? Math.random;
  }

  /** 把本端与对端接成一条双向链路 */
  connect(peer: FakeTransport): void {
    this.peer = peer;
  }

  send(payload: Uint8Array): void {
    if (this.closed || this.peer === null) return;
    this.sentCount += 1;
    if (this.rand() < this.lossRate) {
      this.droppedCount += 1;
      return;
    }
    const jitter = (this.rand() * 2 - 1) * this.jitterMs;
    const deliverAt = this.now() + this.latencyMs + jitter;
    this.queue.push({ deliverAt, payload: payload.slice() });
  }

  onMessage(listener: (payload: Uint8Array) => void): void {
    this.listener = listener;
  }

  close(): void {
    this.closed = true;
    this.queue = [];
  }

  /** 测试用：把当前时刻已到期的包投递给对端 */
  pump(): void {
    const t = this.now();
    const remain: InFlight[] = [];
    for (const item of this.queue) {
      if (item.deliverAt <= t) {
        this.peer?.deliver(item.payload);
      } else {
        remain.push(item);
      }
    }
    this.queue = remain;
  }

  private deliver(payload: Uint8Array): void {
    if (this.closed) return;
    this.listener?.(payload);
  }

  get stats(): { sent: number; dropped: number } {
    return { sent: this.sentCount, dropped: this.droppedCount };
  }
}

// assets/scripts/net/transport/fake-transport.test.ts
import { describe, expect, it } from 'vitest';
import { FakeTransport } from './fake-transport';

function fakeClock(start = 0) {
  let t = start;
  return { now: () => t, advance: (ms: number) => { t += ms; } };
}

describe('假传输层', () => {
  it('按注入的延迟投递，不早也不晚', () => {
    const clock = fakeClock();
    const a = new FakeTransport('a', { latencyMs: 50, now: clock.now });
    const b = new FakeTransport('b', { latencyMs: 50, now: clock.now });
    a.connect(b);
    b.connect(a);
    const got: Uint8Array[] = [];
    b.onMessage((p) => got.push(p));

    a.send(new Uint8Array([1, 2, 3]));
    clock.advance(49);
    a.pump();
    expect(got.length).toBe(0); // 差 1ms，还没到
    clock.advance(1);
    a.pump();
    expect(got.length).toBe(1);
    expect(Array.from(got[0])).toEqual([1, 2, 3]);
  });

  it('按注入的丢包率丢包', () => {
    const clock = fakeClock();
    const seq = [0.1, 0.9, 0.95, 0.05]; // 确定性随机序列
    let n = 0;
    const a = new FakeTransport('a', {
      latencyMs: 0,
      lossRate: 0.5,
      now: clock.now,
      rand: () => seq[n++],
    });
    const b = new FakeTransport('b', { latencyMs: 0, now: clock.now });
    a.connect(b);
    const got: Uint8Array[] = [];
    b.onMessage((p) => got.push(p));

    a.send(new Uint8Array([1])); // rand=0.1 < 0.5 → 丢
    a.send(new Uint8Array([2])); // rand=0.9 >= 0.5 → 过
    a.pump();
    expect(a.stats.dropped).toBe(1);
    expect(got.length).toBe(1);
    expect(got[0][0]).toBe(2);
  });
});

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

const { ccclass } = _decorator;

@ccclass('NetBootstrap')
export class NetBootstrap extends Component {
  private endpoint = '';

  start(): void {
    // 微信小游戏与原生强制走加密通道；桌面浏览器开发期可用 ws
    const mustSecure = sys.isNative || sys.platform === sys.Platform.WECHAT_GAME;
    this.endpoint = `${mustSecure ? 'wss' : 'ws'}://game.example.com/room`;
  }
}