《游戏引擎实现原理》2.1 帧、时间与帧预算

 0ms      4ms      6ms           12ms   13ms            16.67ms  ← 预算线
 ├────────┼────────┼──────────────┼──────┼────────────────┤
 │ logic  │ submit │     gpu      │present│     idle       │
 │ 逻辑   │  提交  │   GPU 执行    │ 呈现  │     空闲        │
 └────────┴────────┴──────────────┴──────┴────────────────┘
   4.0ms    2.0ms      6.0ms        1.0ms      3.67ms

// file: src/core/clock.ts
// tier: L1
// verify: npx vitest run src/core/frame-timer.test.ts
//
// helio 内核：时钟抽象。
// 引擎里所有「时间」都必须从 Clock 取，绝不直接读 performance.now()——
// 只有这样测试才能注入假时钟，把几分钟的模拟压缩到几毫秒跑完。

/** 单调递增的毫秒时钟。真实实现包 performance.now()，测试用 FakeClock。 */
export interface Clock {
  nowMs(): number;
}

/** 假时钟：测试与确定性回放用。 */
export class FakeClock implements Clock {
  #nowMs: number;

  constructor(startMs = 0) {
    this.#nowMs = startMs;
  }

  nowMs(): number {
    return this.#nowMs;
  }

  /** 推进时钟。负值直接抛错，避免测试里把方向写反却静默通过。 */
  advance(deltaMs: number): void {
    if (!(deltaMs >= 0)) {
      throw new RangeError(`FakeClock.advance 需要非负毫秒，收到 ${deltaMs}`);
    }
    this.#nowMs += deltaMs;
  }
}

// file: src/core/frame-timer.ts
// tier: L1
// verify: npx vitest run src/core/frame-timer.test.ts
//
// helio 内核：帧计时器。
// 用一个环形缓冲记录最近 N 帧的耗时，给出平均 / 峰值 / 百分位 / FPS。
// 注入 Clock 后完全不依赖真实 rAF，可在 Node 里把帧分布一次跑出来。

import type { Clock } from './clock.ts';

/** 一帧的四个阶段耗时（毫秒）。这是「帧预算」被谁吃掉的账本。 */
export interface FramePhases {
  /** 游戏逻辑：输入、ECS 系统、物理、动画求值。 */
  logic: number;
  /** 提交：构建命令缓冲、把绘制命令压给图形 API（CPU 侧）。 */
  submit: number;
  /** GPU：上一帧命令在 GPU 上执行的时间（异步，通常落后一帧）。 */
  gpu: number;
  /** 呈现：交换链 present 与垂直同步等待。 */
  present: number;
}

/** 一帧总耗时（毫秒）。 */
export function frameTotalMs(phases: FramePhases): number {
  return phases.logic + phases.submit + phases.gpu + phases.present;
}

/** 是否落在预算内（默认 60Hz 的 16.67ms）。 */
export function withinBudget(phases: FramePhases, budgetMs = 1000 / 60): boolean {
  return frameTotalMs(phases) <= budgetMs;
}

export interface FrameStats {
  lastMs: number;
  avgMs: number;
  p95Ms: number;
  maxMs: number;
  fps: number;
  samples: number;
}

export class FrameTimer {
  readonly #clock: Clock;
  readonly #windowMs: number[];
  #cursor = 0;
  #count = 0;
  #frameStartMs = 0;
  #running = false;
  #lastMs = 0;

  constructor(clock: Clock, windowSize = 120) {
    if (!Number.isInteger(windowSize) || windowSize <= 0) {
      throw new RangeError(`windowSize 必须是正整数，收到 ${windowSize}`);
    }
    this.#clock = clock;
    this.#windowMs = new Array<number>(windowSize).fill(0);
  }

  /** 标记一帧开始。 */
  begin(): void {
    this.#frameStartMs = this.#clock.nowMs();
    this.#running = true;
  }

  /** 标记一帧结束，记录耗时（毫秒）并返回它。 */
  end(): number {
    if (!this.#running) {
      throw new Error('FrameTimer.end 之前必须先 begin');
    }
    const duration = this.#clock.nowMs() - this.#frameStartMs;
    this.#running = false;
    this.#windowMs[this.#cursor] = duration;
    this.#cursor = (this.#cursor + 1) % this.#windowMs.length;
    if (this.#count < this.#windowMs.length) this.#count++;
    this.#lastMs = duration;
    return duration;
  }

  get lastMs(): number {
    return this.#lastMs;
  }

  get sampleCount(): number {
    return this.#count;
  }

  /** 滑窗平均耗时（毫秒）。 */
  avgMs(): number {
    if (this.#count === 0) return 0;
    let sum = 0;
    for (let i = 0; i < this.#count; i++) sum += this.#windowMs[i];
    return sum / this.#count;
  }

  maxMs(): number {
    let max = 0;
    for (let i = 0; i < this.#count; i++) {
      if (this.#windowMs[i] > max) max = this.#windowMs[i];
    }
    return max;
  }

  /** 第 p 百分位耗时（p ∈ [0,1]），最近邻法，够用且不分配额外内存。 */
  percentile(p: number): number {
    if (this.#count === 0) return 0;
    const sorted = this.#windowMs.slice(0, this.#count).sort((a, b) => a - b);
    const idx = Math.min(this.#count - 1, Math.floor(p * this.#count));
    return sorted[idx];
  }

  /** 滑窗平均 FPS。 */
  fps(): number {
    const avg = this.avgMs();
    return avg > 0 ? 1000 / avg : 0;
  }

  stats(): FrameStats {
    return {
      lastMs: this.lastMs,
      avgMs: this.avgMs(),
      p95Ms: this.percentile(0.95),
      maxMs: this.maxMs(),
      fps: this.fps(),
      samples: this.#count,
    };
  }

  /** 帧耗时直方图：宽度 bucketMs 的桶计数，用于看长尾。 */
  histogram(bucketMs: number): number[] {
    if (!(bucketMs > 0)) {
      throw new RangeError(`bucketMs 必须为正，收到 ${bucketMs}`);
    }
    const buckets: number[] = [];
    for (let i = 0; i < this.#count; i++) {
      const b = Math.floor(this.#windowMs[i] / bucketMs);
      buckets[b] = (buckets[b] ?? 0) + 1;
    }
    return buckets;
  }
}

samples=300 avg=17.12 p95=18.12 max=36.57 fps=58.4
  [14-16ms) 78
  [16-18ms) 194
  [18-20ms) 22
  [34-36ms) 2
  [36-38ms) 4