《Cocos 游戏联机实战》3.3 带宽预算与压缩

// mini2d/net/bitpack.ts —— 纯 TS，无 cc 依赖
export class BitWriter {
  private readonly out: number[] = [];
  private acc = 0;      // 累积位：低 bitsUsed 位有效
  private bitsUsed = 0;

  /** 写入 value 的低 bits 位（0 <= bits <= 32） */
  writeBits(value: number, bits: number): void {
    let v = value >>> 0;
    let n = bits;
    while (n > 0) {
      const take = Math.min(n, 8 - this.bitsUsed);
      const mask = take === 8 ? 0xff : (1 << take) - 1;
      this.acc += (v & mask) * 2 ** this.bitsUsed;
      this.bitsUsed += take;
      v = Math.floor(v / 2 ** take);
      n -= take;
      while (this.bitsUsed >= 8) {
        this.out.push(this.acc & 0xff);
        this.acc = Math.floor(this.acc / 256);
        this.bitsUsed -= 8;
      }
    }
  }

  /** 写入一个 32 位整数（有符号按无符号重解释） */
  writeInt32(value: number): void {
    this.writeBits(value >>> 0, 32);
  }

  /** 收尾：不足一字节的部分补零后输出 */
  finish(): Uint8Array {
    if (this.bitsUsed > 0) {
      this.out.push(this.acc & 0xff);
      this.acc = 0;
      this.bitsUsed = 0;
    }
    return new Uint8Array(this.out);
  }
}

export class BitReader {
  private readonly data: Uint8Array;
  private pos = 0;
  private acc = 0;
  private bitsUsed = 0;

  constructor(data: Uint8Array) {
    this.data = data;
  }

  /** 读取 bits 位，返回无符号结果（0 <= bits <= 32） */
  readBits(bits: number): number {
    let result = 0;
    let filled = 0;
    let n = bits;
    while (n > 0) {
      if (this.bitsUsed === 0) {
        this.acc = this.pos < this.data.length ? this.data[this.pos] : 0;
        this.pos += 1;
        this.bitsUsed = 8;
      }
      const take = Math.min(n, this.bitsUsed);
      const mask = (1 << take) - 1;
      result += (this.acc & mask) * 2 ** filled;
      this.acc = this.acc >>> take;
      this.bitsUsed -= take;
      filled += take;
      n -= take;
    }
    return result;
  }

  readInt32(): number {
    return this.readBits(32) | 0;
  }
}

// mini2d/net/quantize.ts —— 纯 TS，无 cc 依赖

/** 把 [-range, range] 的浮点量化成 bits 位定点整数 */
export function quantize(value: number, range: number, bits: number): number {
  const levels = (1 << bits) - 1;
  const clamped = Math.max(-range, Math.min(range, value));
  const normalized = (clamped + range) / (2 * range); // 映射到 [0, 1]
  return Math.round(normalized * levels);
}

/** 量化码还原成浮点 */
export function dequantize(code: number, range: number, bits: number): number {
  const levels = (1 << bits) - 1;
  return (code / levels) * (2 * range) - range;
}

import { describe, expect, it } from 'vitest';
import { BitReader, BitWriter } from './bitpack';
import { dequantize, quantize } from './quantize';

describe('位打包', () => {
  it('写入后读出，值原样返回', () => {
    const w = new BitWriter();
    w.writeBits(5, 3);
    w.writeBits(300, 9);
    w.writeBits(1, 1);
    w.writeBits(4000000000, 32);
    const r = new BitReader(w.finish());
    expect(r.readBits(3)).toBe(5);
    expect(r.readBits(9)).toBe(300);
    expect(r.readBits(1)).toBe(1);
    expect(r.readBits(32)).toBe(4000000000);
  });

  it('打包体积远小于 JSON', () => {
    const entities = [
      { id: 1, x: 123.4, y: 56.7, vx: 3.2, vy: -1.1 },
      { id: 2, x: -200.5, y: 88.8, vx: 0.5, vy: 2.4 },
    ];
    const w = new BitWriter();
    for (const e of entities) {
      w.writeBits(e.id, 8);
      w.writeBits(quantize(e.x, 1000, 12), 12);
      w.writeBits(quantize(e.y, 1000, 12), 12);
      w.writeBits(quantize(e.vx, 20, 10), 10);
      w.writeBits(quantize(e.vy, 20, 10), 10);
    }
    const packed = w.finish().length;
    const json = new TextEncoder().encode(JSON.stringify(entities)).length;
    expect(packed).toBeLessThan(json);
    expect(packed).toBe(13); // 2 实体 × 52 位 = 104 位 = 13 字节
  });
});

describe('量化', () => {
  it('误差不超过一个步长', () => {
    const range = 1000;
    const bits = 12;
    const step = (2 * range) / ((1 << bits) - 1);
    for (const x of [-999.3, -12.7, 0, 250.5, 999.9]) {
      const back = dequantize(quantize(x, range, bits), range, bits);
      expect(Math.abs(back - x)).toBeLessThanOrEqual(step);
    }
  });
});

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

@ccclass('QuantizedView')
export class QuantizedView extends Component {
  /** 与协议约定一致：x / y 为 12 位、量程 ±1000 */
  private static readonly RANGE = 1000;
  private static readonly LEVELS = (1 << 12) - 1;

  /** 把 12 位量化码还原成逻辑坐标 */
  static decode(code: number): number {
    return (code / QuantizedView.LEVELS) * (2 * QuantizedView.RANGE) - QuantizedView.RANGE;
  }

  /** 用（插值后的）逻辑坐标驱动节点；表现层用浮点，不参与网络 */
  present(x: number, y: number): void {
    this.node.setPosition(x, y, 0);
  }
}