《游戏引擎实现原理》10.2 定点数：为确定性模拟准备

// file: src/math/fixed-point.ts
// tier: L1
// verify: npx vitest run src/math/fixed-point.test.ts
//
// Q16.16 定点数：一个 int32 的低 16 位是小数、高 16 位是整数。
// 全部运算都是整数运算，同一输入在任何平台上逐位一致。

/** 小数位数。 */
export const FRAC_BITS = 16;
/** 缩放因子 2^16 = 65536，即「1.0」。 */
export const ONE = 1 << FRAC_BITS;
/** 能表示的最大值约为 32767.99998。 */
export const MAX = 0x7fffffff;

/** 浮点 -> 定点（四舍五入）。只在加载期使用。 */
export function fromFloat(x: number): number {
  return Math.round(x * ONE) | 0;
}

/** 定点 -> 浮点。只用于显示，绝不参与模拟。 */
export function toFloat(fx: number): number {
  return fx / ONE;
}

export function add(a: number, b: number): number {
  return (a + b) | 0;
}

export function sub(a: number, b: number): number {
  return (a - b) | 0;
}

/** 定点乘法：结果仍是 Q16.16。拆分高低位避免 a*b 溢出 2^53。 */
export function mul(a: number, b: number): number {
  const hi = a >> 16; // 整数部分（带符号）
  const lo = a & 0xffff; // 小数部分（0..65535）
  return (hi * b + Math.floor((lo * b) / ONE)) | 0;
}

/** 定点除法：b 为 Q16.16，结果仍是 Q16.16。 */
export function div(a: number, b: number): number {
  if (b === 0) throw new Error('fixed-point divide by zero');
  return Math.floor((a * ONE) / b) | 0;
}

a * b / 2^16 = (hi * 2^16 + lo) * b / 2^16 = hi * b + lo * b / 2^16

// file: src/math/fixed-point.test.ts
// tier: L1
// verify: npx vitest run src/math/fixed-point.test.ts

import { describe, expect, it } from 'vitest';
import { ONE, add, div, fromFloat, mul, sub, toFloat } from './fixed-point.ts';

/** 用 BigInt 做参考实现：floor((a*b)/2^16)。 */
function mulRef(a: number, b: number): number {
  const r = (BigInt(a) * BigInt(b)) >> 16n;
  return Number(BigInt.asIntN(32, r));
}

describe('Q16.16 编解码', () => {
  it('1.0 编码为 65536', () => {
    expect(fromFloat(1)).toBe(ONE);
    expect(fromFloat(0.5)).toBe(32768);
    expect(fromFloat(-2.5)).toBe(-163840);
  });

  it('往返一致', () => {
    expect(toFloat(fromFloat(3.25))).toBe(3.25);
  });
});

describe('定点四则', () => {
  it('加减是整数加减', () => {
    expect(toFloat(add(fromFloat(1.5), fromFloat(2.25)))).toBe(3.75);
    expect(toFloat(sub(fromFloat(1.5), fromFloat(2.25)))).toBe(-0.75);
  });

  it('乘法与 BigInt 参考实现一致', () => {
    for (const [x, y] of [[1.5, 2.25], [-3.0, 4.5], [0.1, 0.2], [100.0, 100.0]] as const) {
      expect(mul(fromFloat(x), fromFloat(y))).toBe(mulRef(fromFloat(x), fromFloat(y)));
    }
  });

  it('1.0 * 1.0 精确等于 1.0', () => {
    expect(mul(ONE, ONE)).toBe(ONE);
  });

  it('除法可还原', () => {
    expect(div(fromFloat(1), fromFloat(4))).toBe(fromFloat(0.25));
    expect(() => div(ONE, 0)).toThrow(/divide by zero/);
  });
});

// file: bench/fixed-point-sim.mjs
// tier: B
// verify: node bench/fixed-point-sim.mjs
//
// 同一段阻尼弹簧积分（p'' = -k*p），分别用 f64 / f32 / Q16.16 定点跑 10000 步。
// DT 取 1/64——二进制可精确表示，排除「dt 量化」这个干扰项，
// 让三种精度的差异只来自运算本身的舍入。
// 定点版本跑两遍（模拟两台不同机器），结果必须逐位相同。

const f = Math.fround;
const ONE = 65536;
const fromF = (x) => Math.round(x * ONE) | 0;
const toF = (fx) => fx / ONE;
const fmul = (a, b) => (((a >> 16) * b + Math.floor(((a & 0xffff) * b) / ONE)) | 0);

const STEPS = 10000;
const DT = 1 / 64;
const K = 10;

// width = 64 用双精度，width = 32 用 Math.fround 强制单精度。
function simFloat(width) {
  const r = width === 32 ? f : (x) => x;
  let p = r(0);
  let v = r(1);
  const dt = r(DT);
  const k = r(K);
  for (let i = 0; i < STEPS; i++) {
    const a = r(-k * p);
    v = r(v + r(a * dt));
    p = r(p + r(v * dt));
  }
  return { p, v };
}

function simFixed() {
  let p = fromF(0);
  let v = fromF(1);
  const dt = fromF(DT);
  const k = fromF(K);
  for (let i = 0; i < STEPS; i++) {
    const a = (-fmul(k, p)) | 0;
    v = (v + fmul(a, dt)) | 0;
    p = (p + fmul(v, dt)) | 0;
  }
  return { p, v };
}

const a = simFloat(64);
const b = simFloat(32);
const c1 = simFixed();
const c2 = simFixed();

console.log(`f64    p=${a.p}  v=${a.v}`);
console.log(`f32    p=${b.p}  v=${b.v}`);
console.log(`|f64-f32| p=${Math.abs(a.p - b.p)}`);
console.log(`fixed  p=${toF(c1.p)}  v=${toF(c1.v)}`);
console.log(`fixed 两次逐位相同 = ${c1.p === c2.p && c1.v === c2.v}`);
console.log(`|fixed-f64| p=${Math.abs(toF(c1.p) - a.p)}`);

f64    p=-0.25283521005441023  v=-0.620696788721661
f32    p=-0.25283491611480713  v=-0.6206955313682556
|f64-f32| p=2.939396031020891e-7
fixed  p=-0.2528839111328125  v=-0.6180572509765625
fixed 两次逐位相同 = true
|fixed-f64| p=0.000048701078402269005