performance

Performance

The budget is 8 ms a frame for everything. Almost nothing in this kit costs a measurable fraction of that; when a Lattice game is slow it is almost always one of about six specific things, and this skill is those six in the order they are worth checking.

Measure before you change anything. Half the optimizations people reach for here are unavailable — there is no sprite cache to add, it was measured and deleted — and the other half are in the wrong place.

---

First: is the number you are reading true?

Two instruments, and the one that reads better is blind.

import type { Loop } from '@latticekit/loop';

export function verdict(loop: Loop): string {
  const gap = loop.stats.worstGapMs;      // wall time between two PAINTED frames
  const cadence = loop.stats.cadenceMs;   // the display's own period, as observed
  // The verdict is the RATIO. Under about 1.5 cadences dropped no frames.
  return `${gap.toFixed(1)} ms worst against a ${cadence.toFixed(1)} ms display`;
}

loop.stats.worstFrameMs is the pump's own wall time — the loop reads the clock on the way into a pump and on the way out. A garbage collection, a style recalculation, or anything else that lands between two pumps is in neither reading. That is not hypothetical:

• one game measured 23.1 ms worst on one machine and 13.1 ms on another for the same build, because whether the pause lands inside a pump is machine-dependent and the readout is not;
• another shipped a HUD reading 0.0 ms against a real worst gap of 9.2 ms;
• a third latched worstFrameMs at the close of each window and displayed 0.0 ms for the first ten seconds, because it was showing its own initializer and nothing renders in zero milliseconds.

worstGapMs is the wall time from one painted frame to the next, so everything in between is inside it by construction, and it is measured from the loop's own single clock reading rather than from performance.now().

Read it next to cadenceMs, never next to a budget. A gap contains a whole display period that is not work: 16.7 ms is a perfect frame on a 60 Hz panel and 8.3 ms is a perfect one at 120 Hz. budgetMs is a work budget and belongs to overBudget, which counts pumps.