The game loop & phases

The game loop is the heartbeat of the engine. vgai uses a fixed-timestep loop with an accumulator, so gameplay and physics advance at a steady rate no matter the display frame rate. Rendering is deliberately fixed-rate too (decided — D1): there is no per-real-frame render step and no display-refresh interpolation.

Fixed timestep

createGameLoop (packages/engine/src/core/game-loop.ts) advances simulation in fixed increments — fixedTimestep defaults to 1/60 (60 Hz). Each animation frame it adds the elapsed real time to an accumulator and runs as many fixed steps as fit:

// game-loop.ts (shape)
const fixedDt = config.fixedTimestep ?? 1 / 60;
const maxSubSteps = config.maxSubSteps ?? 8;
const maxAccumulator = fixedDt * maxSubSteps; // also the accumulator's hard ceiling
let accumulator = 0;

// per frame:
const dt = Math.min(rawDt, maxAccumulator) * timeScale;
accumulator += dt;
if (accumulator > maxAccumulator) accumulator = maxAccumulator;

let steps = 0;
while (accumulator >= fixedDt && steps < maxSubSteps) {
  config.update(fixedDt); // one fixed tick — rendering happens *inside* this call
  accumulator -= fixedDt;
  steps++;
}

Three things to note:

• No render(alpha), no interpolation. config.update(fixedDt) is called once per consumed fixed substep, and per the documented phase order (PHASE_ORDER in core/types.ts) the render phase runs as the last phase inside that same call — there is no separate render callback and nothing to interpolate between. A real frame whose accumulator produces zero substeps calls update zero times and therefore renders zero times that frame.
• Spiral-of-death guard, with a hard accumulator cap. rawDt is clamped to maxAccumulator (fixedDt * maxSubSteps, default 8 steps) before it’s added to the accumulator, and after adding, the accumulator itself is clamped back down to maxAccumulator if it overflows — regardless of timeScale or how large the frame gap was. Time that can’t possibly be caught up on is dropped, never carried forward, so a long stall can’t snowball into an ever-growing backlog.
• timeScale is clamped to [0, 8] (values outside the range are clamped with a console warning): 0 pauses, 0.5 is slow-motion, up to 8 for fast-forward. The GameSession’s pause() / resume() / step() controls build on this.

Idle throttle

When the document becomes hidden (e.g. the tab is backgrounded), the loop stops outright rather than continuing to accumulate; becoming visible again resyncs the accumulator clock to “now” with no catch-up burst for the wall-clock time spent hidden.

The eight phases

Every fixed tick, systems and component updates run in one fixed, ordered sequence. The order is defined once in PHASE_ORDER (packages/engine/src/core/types.ts):

PHASE_ORDER — the fixed sequence every tick follows.

Phase	Purpose
input	Sample keyboard / mouse / gamepad.
prePhysics	Apply forces / intents to rigid bodies before the step.
physics	Step the Rapier world.
postPhysics	Read results back; sync body transforms to Object3D; dispatch triggers.
gameLogic	General gameplay. The default phase for GameComponents.
animation	Advance animation graphs / mixers.
preRender	Camera / HUD fixups before drawing.
render	Draw the frame.

This order is sacred: data flows one way through it, so you never have to reason about “did this run before or after physics?” A component that reads physics results belongs in postPhysics or later; one that pushes forces belongs in prePhysics.

Wrong phase = one-frame-late bugs

Putting logic in the wrong phase is the most common source of subtle one-frame-late behavior. Choose a component’s phase deliberately (see Entities & components).

Systems

A system is just a function of delta time: type SystemFn = (dt: number) => void. The SystemRunner (packages/engine/src/core/system-runner.ts) registers systems into phase buckets and runs each bucket in PHASE_ORDER. A richer SystemDef adds init() and dispose() lifecycle hooks alongside its phase and update.

Within a single phase, runPhase executes three structural buckets in a fixed order: engine systems (everything registered before the engine boundary is marked), then the phase’s one component tick (a dedicated slot the ComponentManager owns — see Entities & components), then game systems (everything a game’s setup() registers via ctx.systems.add). Within each bucket, systems run in registration order — there is no implicit dependency resolution. The bucket order is a structural guarantee: engine systems always run before component ticks, and component ticks before game callbacks, no matter when each was registered. Ordering beyond that is explicit by design (the “one obvious way” principle).

See also

• Entities & components — how update() plugs into a phase.
• Scenes & prefabs — what runs at load time.
• Engine API reference — the generated phase list + GameComponent contract.
• Design philosophy — why ordering is sacred.