@driftengine/core 3.61.0

package/src/cinematic/script.ts

@@ -0,0 +1,231 @@
+import type { ShotParams } from '../render/cinematicCamera.ts';
+
+/**
+ * A cinematic, as data: when the camera cuts, and what is on screen when.
+ *
+ * A sequence is a *file*, not a function. That is the whole point of the split
+ * — a new season, a new trailer or a different cut of the same footage must be
+ * a data change, and the moment one of them needs a branch in TypeScript the
+ * boundary has moved to the wrong place.
+ *
+ * Which means data is where the mistakes will be, and this module is where they
+ * are caught. Everything a timeline can get wrong — two lines up at once, an
+ * entry written above the one it plays after, a keyframe past the end of the
+ * shot it belongs to — is rejected the moment the script is loaded, by name and
+ * by index. The alternative is a cinematic that silently drops its fourth line,
+ * which nobody notices until a player asks what it said.
+ *
+ * Nothing here knows what is being narrated. A shot is a placement, a line is a
+ * string with a window and a `look` the presentation layer resolves.
+ */
+
+/** One camera placement inside a shot. Times are from the shot's own start. */
+export interface CameraKeyframe {
+  readonly atSec: number;
+  readonly camera: ShotParams;
+}
+
+/**
+ * A cut, at `atSec`.
+ *
+ * A shot is either a fixed placement or a list of keyframes moved through while
+ * it holds. Keyframes are a *move*, never a second cut: they may not change the
+ * kind of shot, because that is a cut and belongs on the timeline where an
+ * editor can see it.
+ */
+export interface CinematicShot {
+  readonly atSec: number;
+  readonly camera: ShotParams | readonly CameraKeyframe[];
+}
+
+export interface CinematicLine {
+  readonly atSec: number;
+  readonly holdSec: number;
+  readonly text: string;
+  /** A presentation key — 'story', 'rule'. The player never resolves it. */
+  readonly look: string;
+}
+
+export interface CinematicScript {
+  readonly durationSec: number;
+  /** In play order. May be empty: a sequence of lines over live gameplay. */
+  readonly shots: readonly CinematicShot[];
+  /** In play order, non-overlapping. */
+  readonly lines: readonly CinematicLine[];
+}
+
+const SHOT_KINDS: readonly string[] = ['chase', 'lowWide', 'orbit', 'flyby', 'overhead', 'lookAt'];
+
+/**
+ * Validate a script and hand it back, so a data module fails on import:
+ *
+ * ```ts
+ * export const SEASON_ONE = defineCinematic('season1', { ... });
+ * ```
+ *
+ * Loud at load is the only useful moment. A malformed timeline cannot be
+ * repaired at runtime and must not be played half-right.
+ */
+export function defineCinematic(name: string, script: CinematicScript): CinematicScript {
+  validateCinematic(name, script);
+  return script;
+}
+
+/** Throws on the first thing wrong, naming the entry and both times. */
+export function validateCinematic(name: string, script: CinematicScript): void {
+  const fail = (message: string): never => {
+    throw new Error(`cinematic "${name}": ${message}`);
+  };
+
+  const duration = script.durationSec;
+  if (!Number.isFinite(duration) || duration <= 0) {
+    fail(`runs for ${duration}s, which is not a length`);
+  }
+
+  validateShots(script, duration, fail);
+  validateLines(script, duration, fail);
+}
+
+function validateShots(
+  script: CinematicScript,
+  duration: number,
+  fail: (message: string) => never,
+): void {
+  const shots = script.shots;
+  for (let i = 0; i < shots.length; i++) {
+    const shot = shots[i];
+    if (!Number.isFinite(shot.atSec) || shot.atSec < 0) {
+      fail(`shot ${i} cuts at ${shot.atSec}s`);
+    }
+    if (i === 0 && shot.atSec !== 0) {
+      fail(`shot 0 cuts at ${shot.atSec}s — the camera has nowhere to be before it`);
+    }
+    if (i > 0 && shot.atSec <= shots[i - 1].atSec) {
+      fail(
+        `shot ${i} cuts at ${shot.atSec}s, at or before shot ${i - 1} at ` +
+          `${shots[i - 1].atSec}s — shots must be written in the order they play`,
+      );
+    }
+    if (shot.atSec >= duration) {
+      fail(`shot ${i} cuts at ${shot.atSec}s, after the script ends at ${duration}s`);
+    }
+    // How long this shot holds — what a keyframe inside it has to fit within.
+    const span = (i + 1 < shots.length ? shots[i + 1].atSec : duration) - shot.atSec;
+    validateCamera(shot.camera, span, i, fail);
+  }
+}
+
+function validateCamera(
+  camera: ShotParams | readonly CameraKeyframe[],
+  spanSec: number,
+  index: number,
+  fail: (message: string) => never,
+): void {
+  if ('kind' in camera) {
+    validateShotParams(camera, `shot ${index}`, fail);
+    return;
+  }
+
+  if (camera.length === 0) fail(`shot ${index} is keyframed but has no keyframes`);
+  const first = camera[0];
+  if (first.atSec !== 0) {
+    fail(`shot ${index} keyframe 0 is at ${first.atSec}s — a move must start where the cut lands`);
+  }
+
+  for (let i = 0; i < camera.length; i++) {
+    const frame = camera[i];
+    const where = `shot ${index} keyframe ${i}`;
+    if (!Number.isFinite(frame.atSec) || frame.atSec < 0) fail(`${where} is at ${frame.atSec}s`);
+    if (i > 0 && frame.atSec <= camera[i - 1].atSec) {
+      fail(
+        `${where} is at ${frame.atSec}s, at or before keyframe ${i - 1} at ` +
+          `${camera[i - 1].atSec}s — keyframes must be written in the order they play`,
+      );
+    }
+    if (frame.atSec > spanSec) {
+      fail(`${where} is at ${frame.atSec}s but the shot holds ${spanSec}s — it would never play`);
+    }
+    if (frame.camera.kind !== first.camera.kind) {
+      fail(
+        `${where} changes the shot from ${first.camera.kind} to ${frame.camera.kind} — ` +
+          'a change of kind is a cut, and cuts belong on the timeline',
+      );
+    }
+    /*
+     * An optional parameter has to be on every keyframe of a shot or none of
+     * them. Interpolating toward a missing anchor would send the shot to the
+     * world origin, which reads as the camera being thrown rather than as a
+     * mistake in the data.
+     */
+    if ((frame.camera.anchor === undefined) !== (first.camera.anchor === undefined)) {
+      fail(`${where} adds or drops an anchor mid-move`);
+    }
+    if ((frame.camera.orbitRate === undefined) !== (first.camera.orbitRate === undefined)) {
+      fail(`${where} adds or drops an orbit rate mid-move`);
+    }
+    validateShotParams(frame.camera, where, fail);
+  }
+}
+
+function validateShotParams(
+  shot: ShotParams,
+  where: string,
+  fail: (message: string) => never,
+): void {
+  if (!SHOT_KINDS.includes(shot.kind))
+    fail(`${where} is a "${shot.kind}" shot, which is not a shot`);
+  for (const [label, value] of [
+    ['distance', shot.distance],
+    ['height', shot.height],
+    ['fovDeg', shot.fovDeg],
+  ] as const) {
+    if (!Number.isFinite(value)) fail(`${where} has ${label} ${value}`);
+  }
+  if (shot.orbitRate !== undefined && !Number.isFinite(shot.orbitRate)) {
+    fail(`${where} has orbitRate ${shot.orbitRate}`);
+  }
+  const anchor = shot.anchor;
+  if (anchor !== undefined && (anchor.length !== 3 || !anchor.every(Number.isFinite))) {
+    fail(`${where} has an anchor that is not three finite numbers`);
+  }
+}
+
+function validateLines(
+  script: CinematicScript,
+  duration: number,
+  fail: (message: string) => never,
+): void {
+  const lines = script.lines;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.text.length === 0) fail(`line ${i} has nothing to say`);
+    if (line.look.length === 0) fail(`line ${i} ("${line.text}") has no look`);
+    if (!Number.isFinite(line.atSec) || line.atSec < 0) {
+      fail(`line ${i} ("${line.text}") opens at ${line.atSec}s`);
+    }
+    if (!Number.isFinite(line.holdSec) || line.holdSec <= 0) {
+      fail(`line ${i} ("${line.text}") holds for ${line.holdSec}s`);
+    }
+    if (i > 0) {
+      const previous = lines[i - 1];
+      if (line.atSec <= previous.atSec) {
+        fail(
+          `line ${i} ("${line.text}") opens at ${line.atSec}s, at or before line ${i - 1} at ` +
+            `${previous.atSec}s — lines must be written in the order they play`,
+        );
+      }
+      if (line.atSec < previous.atSec + previous.holdSec) {
+        fail(
+          `line ${i} ("${line.text}") opens at ${line.atSec}s while line ${i - 1} is still up ` +
+            `until ${previous.atSec + previous.holdSec}s — two lines at once is unreadable`,
+        );
+      }
+    }
+    if (line.atSec + line.holdSec > duration) {
+      fail(
+        `line ${i} ("${line.text}") is still up at ${line.atSec + line.holdSec}s, ` +
+          `after the script ends at ${duration}s`,
+      );
+    }
+  }
+}

package/src/core/bootGate.ts

@@ -0,0 +1,49 @@
+/**
+ * The one bit of state the fixed loop and the engine badge have to share.
+ *
+ * **The problem it solves.** The badge holds the screen for a few seconds after the game's first
+ * frame reaches it — deliberately, because the badge is a hold and not merely a cover. Without a
+ * gate the game is *running* for that whole time behind an opaque black plate: an intro animation
+ * plays to nobody, a music cue starts and is three seconds in by the time anyone hears it, and a
+ * countdown is already counting. Every one of those is content the player paid for and did not
+ * get.
+ *
+ * So the loop freezes on the frame it just drew, and resumes when the plate is gone.
+ *
+ * **Why a module-level holder rather than a parameter.** `createRenderer` mounts the badge and
+ * `startLoop` runs the loop, and a consumer calls them separately with nothing passed between —
+ * threading a handle through would make this a thing every game has to wire, which is the whole
+ * failure the default-on badge exists to avoid. There is exactly one screen, so there is exactly
+ * one badge, and a singleton is the honest shape for it rather than a convenience.
+ *
+ * **`ui/` writes it and `core/` reads it**, which is why the state lives here rather than in
+ * `ui/splash.ts`: the fixed loop must not import a module that touches the DOM. This file names
+ * neither of them and knows only that something may be holding frames back.
+ */
+
+/** What is holding frames, if anything. Set by the badge, read by the loop. */
+let holder: (() => boolean) | null = null;
+
+/**
+ * Register what decides whether frames are held, and hand back the way to stop deciding.
+ *
+ * The last registration wins, and releasing only clears the gate if it is still yours — two
+ * badges cannot exist at once, but a badge that was released after a second one mounted must
+ * not open a gate it no longer owns.
+ */
+export function holdFrames(frozen: () => boolean): () => void {
+  holder = frozen;
+  return () => {
+    if (holder === frozen) holder = null;
+  };
+}
+
+/**
+ * Whether this frame should be skipped entirely.
+ *
+ * A null check and at most one call, per frame, for the handful of frames a badge is up and none
+ * at all afterwards — the badge clears the holder when it leaves. Nothing here allocates.
+ */
+export function framesHeld(): boolean {
+  return holder !== null && holder();
+}

package/src/core/loadTracker.ts

@@ -0,0 +1,144 @@
+/** Aggregating everything an app is waiting on into one honest number. */
+
+/**
+ * One thing being waited for.
+ *
+ * `weight` is what makes the total mean anything. A progress bar that treats "decode 58 audio
+ * tracks" and "read a settings file" as half each spends most of its life at 50%, which is worse
+ * than no bar: it teaches a viewer that the bar is decoration. Weights are in whatever unit the
+ * caller likes as long as they are the same unit — bytes are the obvious one because they are
+ * usually known in advance, and a rough guess in "seconds this normally takes" also works.
+ */
+export interface LoadTask {
+  /** Stable, and not for showing: a caller maps it to whatever words its audience needs. */
+  readonly id: string;
+  readonly weight: number;
+  /** 0 to 1. */
+  fraction: number;
+  done: boolean;
+}
+
+export interface LoadSummary {
+  /** 0 to 1 across everything registered, weighted. */
+  readonly fraction: number;
+  /**
+   * The id of the task the caller should be talking about: the heaviest one still unfinished.
+   *
+   * Heaviest rather than first-registered, because that is the one a viewer is actually waiting
+   * for. Empty when nothing is outstanding.
+   */
+  readonly activeId: string;
+  readonly done: boolean;
+  readonly tasksDone: number;
+  readonly tasksTotal: number;
+}
+
+/**
+ * What an app is waiting on, as one weighted number.
+ *
+ * **Why this is in the engine.** Every consumer builds this, and every one of them builds it
+ * slightly wrong in the same way: a bar driven by whichever load happens to report last, or a
+ * fraction over a task count that jumps in sevenths, or a spinner that says nothing at all. None
+ * of that is a game's decision — it is arithmetic over a set of things with sizes — so it belongs
+ * here beside the things that produce the sizes. What stays with the consumer is every word: this
+ * hands back ids and numbers, because what to *call* a stage depends entirely on who is reading.
+ *
+ * **It holds no clock and no DOM.** A caller polls `summary` in its own frame, so a tracker works
+ * the same in a browser, a test and a headless bake.
+ *
+ * Deliberately small. It does not start work, own promises, retry, or time out: a task is
+ * something the caller is already doing, and all this knows is how big it is and how far along.
+ * Anything more would be a scheduler, which is a different thing with different failure modes.
+ */
+export class LoadTracker {
+  private readonly tasks = new Map<string, LoadTask>();
+
+  /**
+   * Declare something to wait for, or re-declare it with a new weight.
+   *
+   * Registering the same id twice is deliberately allowed and is not a reset: a caller frequently
+   * learns the real size of a thing after starting it — a fetch that finally reports its
+   * `Content-Length`, a model whose manifest says how many parts are coming — and having to choose
+   * between a wrong weight and a lost fraction would be a bad choice to force.
+   */
+  add(id: string, weight: number): void {
+    const existing = this.tasks.get(id);
+    const safeWeight = Number.isFinite(weight) && weight > 0 ? weight : 1;
+    if (existing === undefined) {
+      this.tasks.set(id, { id, weight: safeWeight, fraction: 0, done: false });
+      return;
+    }
+    this.tasks.set(id, {
+      id,
+      weight: safeWeight,
+      fraction: existing.fraction,
+      done: existing.done,
+    });
+  }
+
+  /** How far along one task is, 0 to 1. Unknown ids are ignored rather than thrown at. */
+  report(id: string, fraction: number): void {
+    const task = this.tasks.get(id);
+    if (task === undefined) return;
+    /*
+     * Clamped and guarded, because this is fed by arithmetic a caller did — a division by a total
+     * that has not arrived yet is one edit away, and a NaN here would spread to the whole bar and
+     * then to whatever the bar drives.
+     */
+    const safe = Number.isFinite(fraction) ? Math.min(1, Math.max(0, fraction)) : 0;
+    task.fraction = task.done ? 1 : safe;
+  }
+
+  /** Mark one finished, whatever it last reported. */
+  finish(id: string): void {
+    const task = this.tasks.get(id);
+    if (task === undefined) return;
+    task.fraction = 1;
+    task.done = true;
+  }
+
+  /**
+   * A task that turned out not to be needed: dropped from the total rather than completed.
+   *
+   * The distinction matters for the number. An optional asset that is absent — no model baked, a
+   * track with no audio — is not 100% loaded, it is not part of this load at all, and counting it
+   * as finished makes the bar say a thing arrived that never did.
+   */
+  drop(id: string): void {
+    this.tasks.delete(id);
+  }
+
+  /** Nothing to wait for. A tracker with no tasks is done, which is the useful answer. */
+  get summary(): LoadSummary {
+    let weighted = 0;
+    let total = 0;
+    let doneCount = 0;
+    let activeId = '';
+    let activeWeight = -1;
+    for (const task of this.tasks.values()) {
+      total += task.weight;
+      weighted += task.weight * (task.done ? 1 : task.fraction);
+      if (task.done) doneCount++;
+      else if (task.weight > activeWeight) {
+        activeWeight = task.weight;
+        activeId = task.id;
+      }
+    }
+    return {
+      fraction: total > 0 ? Math.min(1, weighted / total) : 1,
+      activeId,
+      done: activeId === '',
+      tasksDone: doneCount,
+      tasksTotal: this.tasks.size,
+    };
+  }
+
+  /** Every task, for a caller that wants to show a line each rather than one bar. */
+  get entries(): readonly LoadTask[] {
+    return [...this.tasks.values()];
+  }
+
+  clear(): void {
+    this.tasks.clear();
+  }
+}

package/src/core/loop.ts

@@ -0,0 +1,211 @@
+import { framesHeld } from './bootGate.ts';
+
+/**
+ * Fixed-timestep game loop with render interpolation.
+ *
+ * Simulation always advances in `fixedDt` increments (determinism requirement,
+ * see AGENTS.md); rendering runs once per animation frame and receives the
+ * interpolation factor `alpha` in [0, 1) between the two most recent sim states.
+ */
+export interface LoopHooks {
+  /**
+   * Advance the simulation by exactly `dt` seconds.
+   *
+   * `tick` counts fixed steps from `LoopOptions.startTick`, and it is the identity every
+   * networked and recorded thing indexes by: an input belongs to a tick, a snapshot is of a tick,
+   * a desync begins at a tick. `AGENTS.md` already states the contract it makes concrete — "time
+   * is a tick count the caller supplies" — and the loop was the one place that knew the count and
+   * did not hand it over, so a caller wanting one kept a second counter beside this callback and
+   * hoped the two agreed.
+   *
+   * A caller with no use for it takes one argument and is unaffected.
+   */
+  simulate(dt: number, tick: number): void;
+  /**
+   * Draw one frame. `alpha` interpolates prev→current sim state.
+   *
+   * `frameDt` is clamped by `maxFrameTime` and is the one to animate against:
+   * a stall must not advance the wind by a minute when the page comes back.
+   *
+   * `wallDt` is the same gap with nothing done to it, and it exists for the
+   * diagnostics. A clamped delta cannot tell a device that took a quarter second
+   * from a browser that waited a second before asking — both arrive as 0.25 —
+   * and three bug reports were filed on that ambiguity before anyone could see it.
+   * Nothing that animates should read it.
+   */
+  /**
+   * @param frame What the frame source delivered, when it delivers anything.
+   *
+   * `undefined` under the window, which is every frame outside a session. An immersive session
+   * hands over the object every pose in that frame is read from, and it is valid only for the
+   * duration of this call. Typed `unknown` because core does not name an `XRFrame`; the package
+   * that does narrows it. An implementation written before this parameter existed still satisfies
+   * the interface, which is why it was added at the end rather than anywhere more readable.
+   */
+  render(alpha: number, frameDt: number, wallDt: number, frame?: unknown): void;
+  /**
+   * Whether the simulation should advance this frame. Absent means always.
+   *
+   * Pause is expressed here rather than by stopping the loop, so a paused game
+   * keeps rendering — the world stays on screen behind the menu instead of
+   * freezing on whatever the last frame happened to be.
+   */
+  shouldSimulate?: () => boolean;
+  /**
+   * Whether this frame is worth drawing at all. Absent means always.
+   *
+   * For the clip export, and it is not an optimisation. A clip is a fixed 60
+   * frames a second; a display running at 144 offers 2.4 animation frames per
+   * clip frame, and the recorder can only take one of them — so the other 1.4
+   * are a full render of a 1080x1920 frame that is thrown away, competing for the
+   * GPU with the one that is kept. Worse, on a 100 Hz display no frame lands
+   * near enough to every slot and the capture rate falls to 50: the file then
+   * claims 60 fps while holding 50, which is precisely the stutter this exists to
+   * remove.
+   *
+   * Skipped time is not lost — it is added to the `frameDt` the next drawn frame
+   * receives, so anything smoothing against it sees real elapsed time.
+   *
+   * **The 60 above is the example and not a limit**, which is worth saying because every sentence
+   * of it names one. This hook is a predicate the caller supplies, so the rate is whatever the
+   * caller returns true at, and `FramePacer` takes the rate it paces to as a constructor argument:
+   * `new FramePacer(30)` is a thirty-a-second export and needs nothing here. A consumer capturing
+   * at 60 and dropping every other frame is paying a full render per discarded frame for a rate the
+   * pacer would have given them.
+   */
+  shouldRender?: () => boolean;
+}
+
+export interface LoopOptions {
+  fixedDt?: number;
+  /** Clamp for pathological frames (tab switch, debugger) to avoid a sim spiral. */
+  maxFrameTime?: number;
+  /**
+   * The tick number the first fixed step reports. Zero unless a caller says otherwise.
+   *
+   * A participant joining a session in progress is told the host's tick and has to agree with it,
+   * because every input and every snapshot is addressed by that number. Starting at zero and
+   * adding an offset at each use is the same arithmetic done in more places, and one of them
+   * eventually forgets.
+   */
+  startTick?: number;
+  /**
+   * Who asks for the next frame, and what that frame carries.
+   *
+   * **The window, unless a session is driving.** An immersive session produces frames on the
+   * headset's clock through `session.requestAnimationFrame`, at whatever rate its display runs, and
+   * the callback carries the frame object every pose in that frame is read from. A loop calling the
+   * window's `requestAnimationFrame` inside a session draws at the page's rate into a display that
+   * wanted something else, which is the difference between presence and motion sickness.
+   *
+   * Optional and defaulting to the window, so no existing caller changes.
+   *
+   * `frame` is `unknown` deliberately. This file is `@driftengine/core`'s clock and has no business
+   * naming an `XRFrame`, which lives in a package core does not depend on; `@driftengine/xr`
+   * narrows it at the one place that reads it. What core owns is that *something* arrived with the
+   * frame and is handed to `render` unread.
+   */
+  frameSource?: FrameSource;
+}
+
+/**
+ * A source of animation frames. `window` satisfies it, and so does an `XRSession`.
+ *
+ * Structural rather than a class, because both of the things that satisfy it are somebody else's:
+ * one is the browser's and one is a runtime's.
+ */
+export interface FrameSource {
+  requestAnimationFrame(callback: (timeMs: number, frame?: unknown) => void): number;
+  cancelAnimationFrame(handle: number): void;
+}
+
+/** Starts the loop immediately. Returns a stop function. */
+export function startLoop(hooks: LoopHooks, options: LoopOptions = {}): () => void {
+  const fixedDt = options.fixedDt ?? 1 / 60;
+  const maxFrameTime = options.maxFrameTime ?? 0.25;
+
+  let last = performance.now();
+  let accumulator = 0;
+  /**
+   * Fixed steps taken, offset by `startTick`.
+   *
+   * **It counts steps and not frames, and it never moves while paused.** A tick is a unit of
+   * simulation, so a paused game that keeps rendering is at the same tick for as long as the menu
+   * is open — which is what makes the number usable as an index into a recording.
+   */
+  let tick = Math.trunc(options.startTick ?? 0);
+  let rafId = 0;
+  /** Frame time banked by animation frames that were not drawn. */
+  let undrawnDt = 0;
+  /** The same bank, unclamped. See `LoopHooks.render`. */
+  let undrawnWallDt = 0;
+
+  /*
+   * Read once and held. A session that ends mid-loop is a consumer stopping this loop and starting
+   * another, because the two run at different rates and share no accumulator worth carrying across.
+   */
+  const source: FrameSource = options.frameSource ?? {
+    requestAnimationFrame: (callback) => requestAnimationFrame(callback),
+    cancelAnimationFrame: (handle) => {
+      cancelAnimationFrame(handle);
+    },
+  };
+
+  const frame = (now: number, xrFrame?: unknown): void => {
+    rafId = source.requestAnimationFrame(frame);
+
+    /*
+     * **Held: draw nothing, advance nothing, and bank nothing.**
+     *
+     * The engine badge holds the screen for a few seconds after the first frame reaches it, and
+     * a game left running behind an opaque plate is a game whose opening seconds nobody sees —
+     * an intro that plays to a black rectangle, a cue that is already three seconds in when the
+     * plate lifts. Freezing on the drawn frame is what makes the badge a hold rather than a
+     * theft.
+     *
+     * `last` moves with the clock so the wait is not banked. Without that line every held frame
+     * accumulates, and the resume replays the whole hold in one step: the same failure the pause
+     * above drops its accumulator for, arrived at from a different direction.
+     */
+    if (framesHeld()) {
+      last = now;
+      accumulator = 0;
+      return;
+    }
+
+    let frameDt = (now - last) / 1000;
+    last = now;
+    const wallDt = frameDt;
+    if (frameDt > maxFrameTime) frameDt = maxFrameTime;
+
+    accumulator += frameDt;
+
+    // Paused: drop the banked time rather than keeping it. Holding it would
+    // replay the whole pause in one resume frame, and every one of those ticks
+    // would land in a run timer that M4 turns into a leaderboard entry.
+    if (hooks.shouldSimulate !== undefined && !hooks.shouldSimulate()) {
+      accumulator = 0;
+    } else {
+      while (accumulator >= fixedDt) {
+        hooks.simulate(fixedDt, tick);
+        tick += 1;
+        accumulator -= fixedDt;
+      }
+    }
+
+    if (hooks.shouldRender !== undefined && !hooks.shouldRender()) {
+      undrawnDt += frameDt;
+      undrawnWallDt += wallDt;
+      return;
+    }
+    /* Handed on unread. See `LoopOptions.frameSource` for why core does not look inside it. */
+    hooks.render(accumulator / fixedDt, frameDt + undrawnDt, wallDt + undrawnWallDt, xrFrame);
+    undrawnDt = 0;
+    undrawnWallDt = 0;
+  };
+
+  rafId = source.requestAnimationFrame(frame);
+  return () => {
+    source.cancelAnimationFrame(rafId);
+  };
+}