《Cocos 游戏开发高级编程》7.3 性能剖析与优化闭环

// 来源：@cocos/creator-types@3.8.8, engine/cc.d.ts（IProfilerState）
frame: ICounterOption;
fps: ICounterOption;
draws: ICounterOption;
instances: ICounterOption;
tricount: ICounterOption;
logic: ICounterOption;
physics: ICounterOption;
render: ICounterOption;
present: ICounterOption;
textureMemory: ICounterOption;
bufferMemory: ICounterOption;

// 来源：@cocos/creator-types@3.8.8, engine/cc.d.ts（Profiler 类）
isShowingStats(): boolean;
hideStats(): void;
showStats(): void;

// mini2d/perf/frame-sampler.ts —— 纯 TS，无任何 cc 依赖
export class FrameSampler {
  private readonly capacity: number;
  private readonly samples: number[];
  private cursor = 0;
  private count = 0;
  private total = 0;

  constructor(capacity = 300) {
    this.capacity = capacity;
    this.samples = new Array<number>(capacity).fill(0);
  }

  push(frameMs: number): void {
    if (this.count === this.capacity) {
      this.total -= this.samples[this.cursor];
    } else {
      this.count += 1;
    }
    this.samples[this.cursor] = frameMs;
    this.total += frameMs;
    this.cursor = (this.cursor + 1) % this.capacity;
  }

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

  get average(): number {
    return this.count === 0 ? 0 : this.total / this.count;
  }

  /** 最近秩分位数：p=95 表示 95% 的帧不超过该值 */
  percentile(p: number): number {
    if (this.count === 0) {
      return 0;
    }
    const sorted = this.samples.slice(0, this.count).sort((a, b) => a - b);
    const rank = Math.ceil((p / 100) * this.count) - 1;
    const idx = Math.min(this.count - 1, Math.max(0, rank));
    return sorted[idx];
  }

  /** 超过预算的帧占比，0~1 */
  overBudgetRatio(budgetMs: number): number {
    if (this.count === 0) {
      return 0;
    }
    let over = 0;
    for (let i = 0; i < this.count; i += 1) {
      if (this.samples[i] > budgetMs) {
        over += 1;
      }
    }
    return over / this.count;
  }
}

import { describe, expect, it } from 'vitest';
import { FrameSampler } from './frame-sampler';

describe('FrameSampler', () => {
  it('环形窗口只保留最近 N 帧', () => {
    const s = new FrameSampler(3);
    s.push(10);
    s.push(20);
    s.push(30);
    s.push(40); // 挤掉最早的 10
    expect(s.length).toBe(3);
    expect(s.average).toBeCloseTo((20 + 30 + 40) / 3);
  });

  it('p95 反映长尾，均值看不出来', () => {
    const s = new FrameSampler(100);
    for (let i = 0; i < 90; i += 1) {
      s.push(16);
    }
    for (let i = 0; i < 10; i += 1) {
      s.push(50);
    }
    expect(s.percentile(50)).toBe(16);
    expect(s.percentile(95)).toBe(50);
    expect(s.average).toBeLessThan(20);
    expect(s.overBudgetRatio(33.3)).toBeCloseTo(0.1);
  });
});

import { director, Director } from 'cc';

let lastBeforeUpdate = 0;
let updateCostMs = 0;

director.on(Director.EVENT_BEFORE_UPDATE, () => {
  lastBeforeUpdate = performance.now();
});

director.on(Director.EVENT_AFTER_UPDATE, () => {
  updateCostMs = performance.now() - lastBeforeUpdate;
});

export function getUpdateCostMs(): number {
  return updateCostMs;
}

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

@ccclass('PerfGate')
export class PerfGate extends Component {
  @property
  budgetMs = 16.7;
  @property
  sampleCount = 300;

  private samples: number[] = [];

  update(): void {
    const stats = profiler.stats;
    if (!stats) return;

    this.samples.push(stats.frame.counter.value);
    if (this.samples.length < this.sampleCount) return;

    const p95 = this.percentile(this.samples, 95);
    if (p95 > this.budgetMs) {
      console.warn(`[perf] p95=${p95.toFixed(2)}ms over budget ${this.budgetMs}ms`);
    }
    this.samples.length = 0;
  }

  private percentile(values: number[], p: number): number {
    const sorted = values.slice().sort((a, b) => a - b);
    const rank = Math.ceil((p / 100) * sorted.length) - 1;
    const idx = Math.min(sorted.length - 1, Math.max(0, rank));
    return sorted[idx];
  }
}