《Cocos 游戏联机实战》1.2 协议选型与序列化

// assets/scripts/net/protocol/messages.ts

/** 消息类型编号，写入每条消息的第一个字节 */
export const MessageId = {
  INPUT: 1,
  SNAPSHOT: 2,
  ROOM_STATE: 3,
} as const;
export type MessageId = (typeof MessageId)[keyof typeof MessageId];

/** INPUT 的按键位标志，一个字节塞多个键 */
export const InputFlag = {
  LEFT: 1,
  RIGHT: 2,
  JUMP: 4,
  ITEM: 8,
} as const;
export type InputFlag = (typeof InputFlag)[keyof typeof InputFlag];

// assets/scripts/net/protocol/codec.ts
const encoder = new TextEncoder();
const decoder = new TextDecoder();

export class ByteWriter {
  private buf: Uint8Array;
  private view: DataView;
  private pos = 0;

  constructor(capacity = 256) {
    this.buf = new Uint8Array(capacity);
    this.view = new DataView(this.buf.buffer);
  }

  private ensure(extra: number): void {
    if (this.pos + extra <= this.buf.length) return;
    let cap = this.buf.length;
    while (cap < this.pos + extra) cap *= 2;
    const next = new Uint8Array(cap);
    next.set(this.buf.subarray(0, this.pos));
    this.buf = next;
    this.view = new DataView(next.buffer);
  }

  u8(v: number): this {
    this.ensure(1);
    this.view.setUint8(this.pos, v & 0xff);
    this.pos += 1;
    return this;
  }

  i16(v: number): this {
    this.ensure(2);
    this.view.setInt16(this.pos, v, true);
    this.pos += 2;
    return this;
  }

  u16(v: number): this {
    this.ensure(2);
    this.view.setUint16(this.pos, v, true);
    this.pos += 2;
    return this;
  }

  /** 16.16 定点数：低 16 位是小数，精度 1/65536，值域约 ±32767 */
  fixed(v: number): this {
    const raw = Math.round(v * 65536);
    this.ensure(4);
    this.view.setInt32(this.pos, raw, true);
    this.pos += 4;
    return this;
  }

  /** 变长无符号整数：每字节 7 位有效位，最高位为续位标志 */
  varint(v: number): this {
    let n = v >>> 0;
    for (;;) {
      const byte = n & 0x7f;
      n >>>= 7;
      if (n === 0) {
        this.u8(byte);
        break;
      }
      this.u8(byte | 0x80);
    }
    return this;
  }

  /** 长度前缀（varint）+ UTF-8 字节 */
  str(s: string): this {
    const bytes = encoder.encode(s);
    this.varint(bytes.length);
    this.ensure(bytes.length);
    this.buf.set(bytes, this.pos);
    this.pos += bytes.length;
    return this;
  }

  toBytes(): Uint8Array {
    return this.buf.slice(0, this.pos);
  }
}

// assets/scripts/net/protocol/codec.ts（续）
export class ByteReader {
  private view: DataView;
  private pos = 0;
  private readonly len: number;

  constructor(bytes: Uint8Array) {
    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
    this.len = bytes.byteLength;
  }

  u8(): number {
    const v = this.view.getUint8(this.pos);
    this.pos += 1;
    return v;
  }

  i16(): number {
    const v = this.view.getInt16(this.pos, true);
    this.pos += 2;
    return v;
  }

  u16(): number {
    const v = this.view.getUint16(this.pos, true);
    this.pos += 2;
    return v;
  }

  fixed(): number {
    const raw = this.view.getInt32(this.pos, true);
    this.pos += 4;
    return raw / 65536;
  }

  varint(): number {
    let shift = 0;
    let result = 0;
    for (;;) {
      const byte = this.view.getUint8(this.pos);
      this.pos += 1;
      result += (byte & 0x7f) * 2 ** shift;
      if ((byte & 0x80) === 0) break;
      shift += 7;
    }
    return result;
  }

  str(): string {
    const n = this.varint();
    const slice = new Uint8Array(this.view.buffer, this.view.byteOffset + this.pos, n);
    this.pos += n;
    return decoder.decode(slice);
  }

  get eof(): boolean {
    return this.pos >= this.len;
  }
}

// assets/scripts/net/protocol/codec.test.ts
import { describe, expect, it } from 'vitest';
import { ByteReader, ByteWriter } from './codec';

describe('编解码器', () => {
  it('基本类型往返一致', () => {
    const w = new ByteWriter(4); // 故意给小容量，触发扩容
    w.u8(255).i16(-300).u16(65535).fixed(1.5).fixed(-2.25).varint(300000).str('方块冲刺');

    const r = new ByteReader(w.toBytes());
    expect(r.u8()).toBe(255);
    expect(r.i16()).toBe(-300);
    expect(r.u16()).toBe(65535);
    expect(r.fixed()).toBeCloseTo(1.5, 5);
    expect(r.fixed()).toBeCloseTo(-2.25, 5);
    expect(r.varint()).toBe(300000);
    expect(r.str()).toBe('方块冲刺');
    expect(r.eof).toBe(true);
  });

  it('变长整数按值大小占字节', () => {
    const w = new ByteWriter();
    w.varint(1).varint(127).varint(128).varint(16383).varint(16384);
    // 1、127 各 1 字节；128、16383 各 2 字节；16384 要 3 字节
    expect(w.toBytes().length).toBe(1 + 1 + 2 + 2 + 3);
  });
});

import { _decorator, Component } from 'cc';

const { ccclass, property } = _decorator;

@ccclass('NetConfig')
export class NetConfig extends Component {
  @property({ tooltip: '协议版本，随每条消息头一起发送，服务端据此拒绝不兼容客户端' })
  protocolVersion = 1;

  @property({ tooltip: '逻辑帧率，客户端与服务端必须一致，否则快照对不上' })
  tickRate = 60;
}