《游戏引擎实现原理》8.1 性能预算达标

// file: src/perf/budget.ts
// tier: L1
// verify: npx vitest run src/perf/budget.test.ts
//
// helio《微光岛》性能预算：预算表 + 逐项判定。
// B 基准层：超预算只标记 WARN，不抛错——性能随机器抖动，硬失败会误伤 CI。

/** 四个维度的预算上限（项目决策值，不是实测值）。 */
export interface Budget {
  readonly frameMs: number;
  readonly memoryMiB: number;
  readonly drawCalls: number;
  readonly bundleKiB: number;
}

export const BUDGET: Budget = {
  frameMs: 16.67, // 60Hz 一帧
  memoryMiB: 64, // 运行时场景常驻堆
  drawCalls: 1024, // 单帧绘制调用
  bundleKiB: 96, // 首包 gzip 后
};

export interface BudgetLine {
  readonly dim: string;
  readonly value: number;
  readonly budget: number;
}
export type Verdict = 'PASS' | 'WARN';
export interface BudgetResult extends BudgetLine {
  readonly verdict: Verdict;
}

/** 逐项判定：value <= budget 即 PASS，否则 WARN（软告警，不抛错）。 */
export function evaluate(lines: readonly BudgetLine[]): BudgetResult[] {
  return lines.map((l) => ({ ...l, verdict: l.value <= l.budget ? 'PASS' : 'WARN' }));
}

/** 最近邻百分位（与 FrameTimer.percentile 同口径）。 */
export function percentile(sorted: readonly number[], p: number): number {
  if (sorted.length === 0) return 0;
  return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))]!;
}

// file: src/perf/budget.test.ts
// tier: L1
// verify: npx vitest run src/perf/budget.test.ts
import { describe, it, expect } from 'vitest';
import { BUDGET, evaluate, percentile } from './budget.ts';

describe('budget', () => {
  it('value <= budget 判 PASS，超预算判 WARN', () => {
    const r = evaluate([
      { dim: 'frame', value: 3.6, budget: 16.67 },
      { dim: 'draws', value: 30000, budget: 1024 },
    ]);
    expect(r.map((x) => x.verdict)).toEqual(['PASS', 'WARN']);
  });

  it('B 层软告警：超预算也返回结果而不抛错', () => {
    expect(() => evaluate([{ dim: 'x', value: 999, budget: 1 }])).not.toThrow();
    expect(evaluate([{ dim: 'x', value: 999, budget: 1 }])[0]!.verdict).toBe('WARN');
  });

  it('percentile 取最近邻，越界收敛到末位，空数组返回 0', () => {
    expect(percentile([1, 2, 3, 4], 0.5)).toBe(3);
    expect(percentile([1, 2, 3, 4], 1)).toBe(4);
    expect(percentile([], 0.5)).toBe(0);
  });

  it('预算表四字段齐全', () => {
    expect(Object.keys(BUDGET).sort()).toEqual(['bundleKiB', 'drawCalls', 'frameMs', 'memoryMiB']);
  });
});

// file: tools/budget-gate.mjs
// tier: B
// verify: node --expose-gc tools/budget-gate.mjs
//
// helio《微光岛》性能预算门禁（B 基准层，软告警不硬失败）。
// 帧时间 / 内存 / 绘制调用 / 包体四个维度各自实测，与 BUDGET 逐项对照，输出表格。
import { gzipSync } from 'node:zlib';
import { build } from 'vite';
import { BUDGET, evaluate, percentile as pct } from '../src/perf/budget.ts';
import { Kernel, MoveSubsystem, TimeSubsystem } from '../src/core/kernel.ts';
import { makeScene } from '../src/render/app/render-profiling.ts';
import { assembleFrame } from '../src/render/app/renderer-assembly.ts';
import { lookAt, multiply, perspective } from '../src/render/culling/frustum.ts';
import { buildBatches, makeBatchItems, packBatchKey, summarize } from '../src/render/sort/batch.ts';
import { radixSortKeys } from '../src/render/sort/sort-key.ts';

const N = 30000, MESHES = 64, FRAMES = 300, WARMUP = 40;

// 1) 帧时间：逻辑 tick + 渲染装配，逐帧计时取分位。
function frame() {
  const vp = multiply(perspective((60 * Math.PI) / 180, 16 / 9, 0.1, 200), lookAt([0, 6, 24], [0, 0, 0], [0, 1, 0]));
  const scene = makeScene(N, 7, 30);
  const k = new Kernel({ frameArenaBytes: 32 * 1024, stepSeconds: 1 / 60, maxStepsPerFrame: 4 });
  k.register(new TimeSubsystem());
  k.register(new MoveSubsystem(k.world));
  for (let i = 0; i < 512; i++) k.world.spawn(`e${i}`, 0, 0, 0);
  k.boot();
  const ms = [];
  for (let i = 0; i < WARMUP + FRAMES; i++) {
    const t = performance.now();
    k.tick(1 / 60);
    assembleFrame(scene, vp, [0, 6, 24], 200);
    if (i >= WARMUP) ms.push(performance.now() - t);
  }
  k.shutdown();
  const s = [...ms].sort((a, b) => a - b);
  return { median: pct(s, 0.5), p95: pct(s, 0.95) };
}

// 2) 内存：持有一整个发布场景的堆增量（process.memoryUsage）。
function memory() {
  globalThis.gc?.();
  const before = process.memoryUsage().heapUsed;
  const scene = makeScene(N, 7, 30);
  const items = makeBatchItems(N, 21, MESHES, 0.08);
  const order = radixSortKeys(Uint32Array.from(items, packBatchKey), N);
  const after = process.memoryUsage().heapUsed;
  return { heapDeltaMiB: (after - before) / 1048576, sink: scene.length + order.length };
}

// 3) 绘制调用：合批后 vs 未合批基线。
function draws() {
  const items = makeBatchItems(N, 21, MESHES, 0.08);
  const order = radixSortKeys(Uint32Array.from(items, packBatchKey), N);
  return { batched: summarize(buildBatches(items, order)).drawCalls, naive: N };
}

// 4) 包体：与 tools/build-prod.mjs 同款 vite 生产配置（minify + 内容哈希）+ gzip。
async function bundle() {
  const r = await build({
    root: process.cwd(), logLevel: 'error',
    build: { write: false, minify: true, rollupOptions: {
      input: new URL('../src/apps/glimmer-isle-demo.ts', import.meta.url).pathname,
      output: { entryFileNames: 'assets/[name]-[hash].js', format: 'es' } } },
  });
  const chunks = (Array.isArray(r) ? r[0] : r).output.filter((c) => c.type === 'chunk');
  return chunks.reduce((a, c) => ({ raw: a.raw + Buffer.byteLength(c.code), gzip: a.gzip + gzipSync(Buffer.from(c.code)).byteLength }), { raw: 0, gzip: 0 });
}

const f = frame(), m = memory(), d = draws(), b = await bundle();
const rows = evaluate([
  { dim: '帧时间 p95', value: f.p95, budget: BUDGET.frameMs },
  { dim: '内存常驻', value: m.heapDeltaMiB, budget: BUDGET.memoryMiB },
  { dim: '绘制调用(合批)', value: d.batched, budget: BUDGET.drawCalls },
  { dim: '绘制调用(基线)', value: d.naive, budget: BUDGET.drawCalls },
  { dim: '首包 gzip', value: b.gzip / 1024, budget: BUDGET.bundleKiB },
]);
console.table(rows);
console.log(`frame median=${f.median.toFixed(2)}ms  bundle raw=${b.raw}B gzip=${b.gzip}B`);
console.log('=== budget-gate: 软告警，exit 0 ===');