💃 Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @jolly-pixel/loop
# or
$ yarn add @jolly-pixel/loop

👀 Usage example

import { GameLoop } from "@jolly-pixel/loop";

const loop = new GameLoop({
  fixedFps: 60,
  maxFps: 144
});

loop.on("panic", ({ droppedMs }) => {
  console.warn(`the frame overran its budget, dropped ${droppedMs}ms`);
});

loop.start({
  fixedUpdate: (fixedDeltaMs, stepIndex) => {
    world.step(
      fixedDeltaMs / 1000,
      stepIndex
    );
  },
  update: (renderDeltaMs, alpha) => {
    renderer.draw(alpha);
  }
});

for a host with its own frame pump:

import { FrameScheduler } from "@jolly-pixel/loop";

const scheduler = new FrameScheduler({
  fixedFps: 60
});

function tick(
  now: number
) {
  const schedule = scheduler.advance(now);

  for (let stepIndex = 0; stepIndex < schedule.steps; stepIndex++) {
    world.step(
      schedule.fixedDelta / 1000,
      stepIndex
    );
  }
  if (schedule.render) {
    renderer.draw(schedule.alpha);
  }
}

Tests drive either layer without timers:

import {
  GameLoop,
  ManualFrameSource
} from "@jolly-pixel/loop";

const source = new ManualFrameSource();
const loop = new GameLoop({
  source
});

loop.start({
  fixedUpdate,
  update
});
source.run([16, 16, 5000, 16]);

📚 API

Core

What runs the loop. Start with GameLoop.

• GameLoop: the ready-made loop, its callbacks and events.
• FrameScheduler: the scheduler under GameLoop, for hosts with their own frame pump.
• FrameSource: where frames come from.
  • RequestAnimationFrameSource: browsers, the default.
  • AnimationLoopFrameSource: renderers with setAnimationLoop().
  • ManualFrameSource: tests and replays.

Utilities

Optional helpers. Use them only when you need them.

• Interpolated: smooth rendering between two fixed steps.
• FrameBudget: a time limit for optional work inside a frame.
• FrameRateGovernor: render at half rate while frames keep missing their refresh.
• suspendWhenHidden: stop a loop while its canvas is off screen.
• Clock: PerformanceClock and ManualClock, for FrameBudget and tests.

See GLOSSARY.md for the timing terms used by the package.

🐌 Lag policy

The scheduler limits lag in two stages.

Option	Default	Meaning
fixedFps	60	Simulation rate. Fixed, never adapted.
maxFps	Infinity	Render cap. Independent of fixedFps.
maxFrameDelta	250	The raw delta is clamped to this before accumulating.
maxStepsPerFrame	5	Upper bound on fixed steps per frame, multiplied by timeScale above 1.
timeScale	1	Multiplier applied to the frame delta. 0 pauses.
snapTolerance	0	Snaps deltas near whole refresh periods. See frame pacing.

A tab switch, a breakpoint or a laptop waking up produces one enormous delta. maxFrameDelta absorbs it and the frame reports clamped: true.

An overloaded frame wants more steps than its budget allows. The budget is ceil(maxStepsPerFrame × max(timeScale, 1)), so fast-forward does not count as overload. The scheduler runs that many steps and discards the rest beyond half a step, reporting panicked: true with droppedMs. Simulation time falls behind wall-clock time, the game slows down, and the loop cannot spiral, because unrun work is never carried forward.

A capped frame still accumulates time and still runs its fixed steps. Only render comes back false, because a source that swallowed frames would hide their elapsed time from the accumulator.

🧪 Benchmarks

The suites measure FrameScheduler#advance(), GameLoop callback dispatch, Interpolated, and FrameBudget.

pnpm --filter @jolly-pixel/loop bench

Use -- --list to inspect the suites. Filtering and measurement rules are documented by @jolly-pixel/bench.

✨ Contributors guide

If you are a developer looking to contribute to the project, you must first read the CONTRIBUTING guide.

Once you have finished your development, check that the tests (and linter) are still good by running the following script:

$ pnpm run test
$ pnpm run lint

CAUTION

In case you introduce a new feature or fix a bug, make sure to include tests for it as well.

📃 License

MIT