《游戏引擎实现原理》2.3 时间缩放、暂停与慢动作

// file: src/core/time-service.ts
// tier: L1
// verify: npx vitest run src/core/time-service.test.ts
//
// helio 内核：时间服务。
// 把「真实时间」翻译成「游戏逻辑时间」——timeScale 缩放、paused 冻结。
// 关键约定：UI/菜单动画吃 unscaledDelta（不受暂停影响），逻辑吃 scaledDelta。

export interface TimeStep {
  /** 未缩放的真实 delta（秒）。UI、菜单、加载动画用它。 */
  unscaledDelta: number;
  /** 受 timeScale 与 paused 影响的逻辑 delta（秒）。游戏世界用它。 */
  scaledDelta: number;
}

export class TimeService {
  #timeScale = 1;
  #paused = false;
  #unscaledElapsed = 0;
  #scaledElapsed = 0;

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

  /** 设置缩放。0 表示冻结逻辑，1 为正常，0.25 为慢动作。 */
  set timeScale(value: number) {
    if (!(value >= 0)) {
      throw new RangeError(`timeScale 必须非负，收到 ${value}`);
    }
    this.#timeScale = value;
  }

  get paused(): boolean {
    return this.#paused;
  }

  set paused(value: boolean) {
    this.#paused = value;
  }

  /** 真实经过的总秒数（不受缩放/暂停影响）。 */
  get unscaledElapsed(): number {
    return this.#unscaledElapsed;
  }

  /** 逻辑经过的总秒数（缩放后、扣除暂停）。 */
  get scaledElapsed(): number {
    return this.#scaledElapsed;
  }

  /** 推进一帧。realDeltaSeconds 是真实经过的秒数。 */
  update(realDeltaSeconds: number): TimeStep {
    if (!(realDeltaSeconds >= 0)) {
      throw new RangeError(`realDeltaSeconds 必须非负，收到 ${realDeltaSeconds}`);
    }
    this.#unscaledElapsed += realDeltaSeconds;
    const scaledDelta = this.#paused ? 0 : realDeltaSeconds * this.#timeScale;
    this.#scaledElapsed += scaledDelta;
    return { unscaledDelta: realDeltaSeconds, scaledDelta };
  }
}

每帧：
  const { unscaledDelta, scaledDelta } = time.update(realDt);
  loop.advance(scaledDelta);        // 逻辑：暂停时自动为 0，一步都不跑
  uiAnimator.advance(unscaledDelta); // UI：永远按真实时间走

// file: src/core/time-service.test.ts
// tier: L1
// verify: npx vitest run src/core/time-service.test.ts
//
// 断言：慢动作按 1/timeScale 累积、暂停时逻辑冻结而 UI 照常、恢复后无缝续上。

import { describe, expect, it } from 'vitest';
import { FixedStepLoop } from './fixed-step-loop.ts';
import { TimeService } from './time-service.ts';

const STEP = 1 / 60;

describe('TimeService', () => {
  it('默认 1 倍速，缩放后逻辑 delta 正确', () => {
    const t = new TimeService();
    const s = t.update(0.016);
    expect(s.unscaledDelta).toBeCloseTo(0.016, 6);
    expect(s.scaledDelta).toBeCloseTo(0.016, 6);
  });

  it('慢动作 0.25 倍：逻辑时间按 1/4 累积', () => {
    const t = new TimeService();
    t.timeScale = 0.25;
    for (let i = 0; i < 60; i++) t.update(1 / 60);
    expect(t.unscaledElapsed).toBeCloseTo(1, 6);
    expect(t.scaledElapsed).toBeCloseTo(0.25, 6);
  });

  it('暂停时逻辑 delta 为 0，但真实时间照常累积', () => {
    const t = new TimeService();
    t.paused = true;
    const s = t.update(1 / 60);
    expect(s.scaledDelta).toBe(0);
    expect(s.unscaledDelta).toBeCloseTo(1 / 60, 6);
    expect(t.scaledElapsed).toBe(0);
    expect(t.unscaledElapsed).toBeCloseTo(1 / 60, 6);
  });

  it('负 delta 抛错', () => {
    const t = new TimeService();
    expect(() => t.update(-0.1)).toThrow(RangeError);
  });

  it('暂停：逻辑步为 0，UI 动画仍推进', () => {
    const t = new TimeService();
    const loop = new FixedStepLoop({ stepSeconds: STEP, maxStepsPerFrame: 5 });
    let logicSteps = 0;
    let uiProgress = 0; // UI 进度按 unscaledDelta 推进

    for (let i = 0; i < 60; i++) {
      const s = t.update(1 / 60);
      logicSteps += loop.advance(s.scaledDelta).steps;
      uiProgress += s.unscaledDelta;
    }
    expect(logicSteps).toBeGreaterThanOrEqual(59);

    const stepsBeforePause = logicSteps;
    const uiBeforePause = uiProgress;
    t.paused = true;
    for (let i = 0; i < 30; i++) {
      const s = t.update(1 / 60);
      logicSteps += loop.advance(s.scaledDelta).steps;
      uiProgress += s.unscaledDelta;
    }
    console.log('暂停前后 逻辑步:', stepsBeforePause, '→', logicSteps, '| UI 进度:', uiBeforePause.toFixed(3), '→', uiProgress.toFixed(3));
    expect(logicSteps).toBe(stepsBeforePause); // 逻辑完全冻结
    expect(uiProgress - uiBeforePause).toBeCloseTo(0.5, 6); // UI 前进 0.5 秒
  });

  it('恢复后逻辑时间从暂停点继续', () => {
    const t = new TimeService();
    for (let i = 0; i < 30; i++) t.update(1 / 60);
    const before = t.scaledElapsed;
    t.paused = true;
    for (let i = 0; i < 60; i++) t.update(1 / 60);
    expect(t.scaledElapsed).toBeCloseTo(before, 6);
    t.paused = false;
    for (let i = 0; i < 30; i++) t.update(1 / 60);
    expect(t.scaledElapsed - before).toBeCloseTo(0.5, 6);
  });
});

暂停前后 逻辑步: 60 → 60 | UI 进度: 1.000 → 1.500