《Cocos 游戏开发入门》1.3 第一个可跑循环：requestAnimationFrame 与固定步长

function frame(now: number): void {
  // now 是 DOMHighResTimeStamp，单位毫秒，单调递增
  update(now);
  draw();
  requestAnimationFrame(frame); // 排下一帧
}
requestAnimationFrame(frame);   // 排第一帧

// src/core/loop.ts
export interface TimeSource {
  now(): number; // 单调递增的毫秒时间戳
}

export const realTime: TimeSource = {
  now: () => performance.now(),
};

export type StepFn = (dt: number) => void;

export interface LoopOptions {
  fixedStep?: number;   // 固定步长，单位秒
  maxSubSteps?: number; // 单帧最多补几步
}

export class Loop {
  readonly fixedStep: number;
  readonly maxSubSteps: number;

  private readonly time: TimeSource;
  private readonly step: StepFn;
  private accumulator = 0;      // 秒
  private lastMs: number | null = null;
  private running = false;
  private handle = 0;

  constructor(step: StepFn, time: TimeSource = realTime, options: LoopOptions = {}) {
    this.step = step;
    this.time = time;
    this.fixedStep = options.fixedStep ?? 1 / 60;
    this.maxSubSteps = options.maxSubSteps ?? 5;
  }

  /** 用时间源推进一次：测试与手动驱动调用。返回本帧实际执行的步数。 */
  advance(): number {
    return this.tick(this.time.now());
  }

  private tick(nowMs: number): number {
    if (this.lastMs === null) {
      this.lastMs = nowMs;      // 第一帧只对齐基准，不步进
      return 0;
    }
    const rawDt = (nowMs - this.lastMs) / 1000;
    this.lastMs = nowMs;

    // 钳制单帧上限，防止切标签页回来后的巨量 dt 灌爆物理
    const dt = Math.min(rawDt, this.fixedStep * this.maxSubSteps);
    this.accumulator += dt;

    let steps = 0;
    while (this.accumulator >= this.fixedStep && steps < this.maxSubSteps) {
      this.step(this.fixedStep);
      this.accumulator -= this.fixedStep;
      steps += 1;
    }

    // 已经补到上限还有剩余，说明真的追不上了，丢掉积压
    if (steps === this.maxSubSteps) this.accumulator = 0;
    return steps;
  }

  start(onFrame?: () => void): void {
    if (this.running) return;
    this.running = true;
    const frame = (now: number): void => {
      if (!this.running) return;
      this.tick(now);           // rAF 自带高精度时间戳，直接用它
      onFrame?.();
      this.handle = requestAnimationFrame(frame);
    };
    this.handle = requestAnimationFrame(frame);
  }

  stop(): void {
    this.running = false;
    if (this.handle) cancelAnimationFrame(this.handle);
    this.handle = 0;
  }
}

// src/core/clock.ts
import type { TimeSource } from './loop';

export class FakeTime implements TimeSource {
  private t: number;

  constructor(startMs = 0) {
    this.t = startMs;
  }

  now(): number {
    return this.t;
  }

  advance(ms: number): void {
    this.t += ms;
  }
}

import { describe, expect, it } from 'vitest';
import { Loop } from './loop';
import { FakeTime } from './clock';

function runSteps(deltas: number[], options = { maxSubSteps: 10 }): number {
  const time = new FakeTime();
  let steps = 0;
  const loop = new Loop(() => { steps += 1; }, time, options);
  loop.advance();            // 基准帧，不步进
  for (const ms of deltas) {
    time.advance(ms);
    loop.advance();
  }
  return steps;
}

describe('固定步长循环', () => {
  it('稳定 60fps 下，一秒约 60 步', () => {
    const steps = runSteps(Array.from({ length: 60 }, () => 1000 / 60));
    // 理论 60 步；浮点累加可能差 1 步，属正常
    expect(steps).toBeGreaterThanOrEqual(59);
    expect(steps).toBeLessThanOrEqual(60);
  });

  it('帧率在抖动，但总时长不变，步数几乎不变', () => {
    const uniform = runSteps(Array.from({ length: 60 }, () => 1000 / 60));
    const jitter = runSteps([110, 90, 130, 80, 120, 95, 105, 120, 65, 85]);

    expect(jitter).toBe(60);                        // 1 秒 / (1/60 秒)
    expect(Math.abs(jitter - uniform)).toBeLessThanOrEqual(1);
  });

  it('一帧卡 5 秒，也只补 maxSubSteps 步', () => {
    const time = new FakeTime();
    let steps = 0;
    const loop = new Loop(() => { steps += 1; }, time, { maxSubSteps: 5 });

    loop.advance();     // 基准帧
    time.advance(5000); // 卡了 5 秒

    expect(loop.advance()).toBe(5);
    expect(steps).toBe(5);
  });
});

// src/game.ts
import { Loop } from './core/loop';

export interface Player {
  x: number;
  y: number;
  vx: number; // 像素/秒
}

export class Game {
  readonly loop: Loop;
  readonly player: Player = { x: 0, y: 0, vx: 120 };

  constructor() {
    // 注意：传给 step 的是固定步长，不是原始 dt
    this.loop = new Loop((dt) => this.step(dt));
  }

  private step(dt: number): void {
    const p = this.player;
    p.x += p.vx * dt;      // 速度 × 固定步长
    if (p.x > 800) p.x = 0; // 跑出屏幕就回卷，方便肉眼观察
  }
}

import { Game } from './game';

const canvas = document.getElementById('stage') as HTMLCanvasElement;
const ctx = canvas.getContext('2d');
if (!ctx) throw new Error('拿不到 2D 上下文');

const game = new Game();

game.loop.start(() => {
  // onFrame：每帧渲染一次，画的是当前逻辑状态
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.fillStyle = '#4ea1ff';
  ctx.fillRect(game.player.x, canvas.height / 2 - 16, 32, 32);
});

import { _decorator, Component, director, game } from 'cc';

const { ccclass } = _decorator;

@ccclass('PlayerMove')
export class PlayerMove extends Component {
  private speed = 120; // 像素/秒

  // 引擎每帧回调，dt 是上一帧增量，单位：秒
  update(dt: number): void {
    const p = this.node.position;
    this.node.setPosition(p.x + this.speed * dt, p.y, p.z);
  }

  onLoad(): void {
    // 设定目标帧率；引擎内部据此驱动主循环
    game.frameRate = 60;
    console.log('director 已运行帧数：', director.getTotalFrames());
  }
}