refactor: implement new FixedTimeStep class for runtime gameloop (#138)

Author: fraxken

.changeset/five-pants-sleep.md

@@ -0,0 +1,6 @@
+---
+"@jolly-pixel/runtime": minor
+"@jolly-pixel/engine": minor
+---
+
+Integrate new FixedTimeStep for gameloop with fixedUpdate and classical update

packages/engine/docs/internals/fixed-time-step.md

@@ -1,130 +1,76 @@
 ## FixedTimeStep
 
-`FixedTimeStep` decouples the game's **logical update rate** from
-the display's frame rate. Instead of updating once per rendered
-frame (which varies with hardware and browser load), it
-accumulates elapsed time and runs a fixed number of updates at a
-constant interval. This ensures deterministic, reproducible
-physics and gameplay regardless of rendering performance.
+`FixedTimeStep` decouples the game's **logical update rate** (e.g. physics, simulation) from the display's frame rate. Instead of updating once per rendered frame (which varies with hardware and browser load), it accumulates elapsed time and runs a fixed number of updates at a constant interval. This ensures deterministic, reproducible physics and gameplay regardless of rendering performance.
 
-The implementation guards against the
-["doom spiral"](http://blogs.msdn.com/b/shawnhar/archive/2011/03/25/technical-term-that-should-exist-quot-black-pit-of-despair-quot.aspx)
-— a situation where each tick takes longer than the previous one —
-by capping accumulated time to at most 5 update intervals.
-
-### How it works
-
-```
-requestAnimationFrame
-  │
-  ├─ clock.update()           ← advance the timer
-  │
-  ├─ accumulatedTime += dt    ← add frame delta
-  │
-  └─ while accumulatedTime >= updateInterval
-       ├─ callback(deltaTime) ← fixed-step game update
-       └─ accumulatedTime -= updateInterval
-```
-
-On every browser frame the caller feeds the accumulated time into
-`tick()`. The method consumes as many fixed-size intervals as
-possible, calls the update callback for each one, and returns how
-much time is left over for the next frame.
+The implementation guards against the ["doom spiral"](http://blogs.msdn.com/b/shawnhar/archive/2011/03/25/technical-term-that-should-exist-quot-black-pit-of-despair-quot.aspx) — a situation where each tick takes longer than the previous one — by capping accumulated time to at most 5 update intervals.
 
 ### Usage
 
 ```ts
 import { FixedTimeStep } from "@jolly-pixel/engine";
 
 const fixedTimeStep = new FixedTimeStep();
-fixedTimeStep.setFps(60);
+fixedTimeStep.setFps(60); // (render FPS, fixed update FPS)
 
-let accumulatedTime = 0;
+// Start the timer before your main loop
+fixedTimeStep.start();
 
 function loop() {
-  const { updates, timeLeft } = fixedTimeStep.tick(
-    accumulatedTime,
-    (deltaTime) => {
-      // Run one fixed-step update
-      const exited = game.update(deltaTime);
-
-      // Returning true stops processing remaining steps
-      return exited;
+  fixedTimeStep.tick({
+    fixedUpdate: (fixedDelta) => {
+      // Run physics or deterministic logic here
+      game.fixedUpdate(fixedDelta);
+    },
+    update: (interpolation, delta) => {
+      // Use interpolation for smooth rendering
+      game.render(interpolation, delta);
     }
-  );
+  });
 
-  accumulatedTime = timeLeft;
-  game.render();
   requestAnimationFrame(loop);
 }
 
 requestAnimationFrame(loop);
 ```
 
-### TimerAdapter
-
-`FixedTimeStep` relies on a `TimerAdapter` for time measurement.
-By default it uses Three.js's `THREE.Timer`, but any object that
-satisfies the interface can be injected (useful for testing with
 deterministic time):
 
+### Callbacks
+
+`FixedTimeStep` uses a callback object:
+
 ```ts
-interface TimerAdapter {
-  /** Advance the internal clock. Called once per tick. */
-  update: () => void;
-  /** Return the elapsed time since the last update (in ms). */
-  getDelta: () => number;
+interface FixedTimeStepCallbacks {
+  fixedUpdate: (fixedDelta: number) => void;
+  update?: (interpolation: number, delta: number) => void;
 }
 ```
 
-```ts
-// Custom clock for tests
-const mockClock: TimerAdapter = {
-  update: () => {},
-  getDelta: () => 16.67
-};
-
-const fixedTimeStep = new FixedTimeStep(mockClock);
-```
+- `fixedUpdate` is called one or more times per frame, using a fixed timestep (in ms). Use this for physics and deterministic logic.
+- `update` is called once per frame
 
-### Configuring the frame rate
+#### Interpolation
 
-The target frame rate defaults to **60 FPS** and can be changed
-with `setFps`. Values are clamped between `1` and
-`FixedTimeStep.MaxFramesPerSecond` (60):
+The `interpolation` value passed to `update` allows you to render objects smoothly between physics steps. For example, if your physics runs at 60Hz but your display is 144Hz, you can interpolate between the previous and current physics states:
 
 ```ts
-fixedTimeStep.setFps(30);
+const renderedPosition = (1 - interpolation) * previousPosition + interpolation * currentPosition;
 ```
 
-The update interval is derived as `1000 / framesPerSecond`
-(in milliseconds).
+This makes movement appear smooth, even if the physics steps are less frequent than the rendering frames.
 
-### Tick result
+### Configuring the frame rate
 
-`tick()` returns an object describing what happened during the
-call:
+The target frame rate defaults to **60 FPS** for both rendering and fixed updates. You can change them with `setFps(renderFps, fixedFps)`. Values are clamped between `1` and `FixedTimeStep.MaxFramesPerSecond` (60):
 
 ```ts
-interface TickResult {
-  /** Number of fixed updates that were executed. */
-  updates: number;
-  /** Remaining accumulated time to carry over to the next frame. */
-  timeLeft: number;
-}
+fixedTimeStep.setFps(30, 60); // 30 FPS render, 60 FPS fixed update
 ```
 
-- **`updates === 0`** — the frame was too short for a full step;
-  the leftover time is carried over.
-- **`updates > 0`** — the callback ran that many times, each with
-  a consistent `deltaTime`.
-- **Early exit** — if the callback returns `true`, processing
-  stops immediately and the remaining time is returned.
+The fixed update interval is derived as `1000 / fixedFramesPerSecond` (in milliseconds).
 
 ### Doom spiral protection
 
-If the browser stalls (e.g. tab switch, debugger breakpoint), the
-accumulated time can grow very large. Without a cap, the engine
-would try to catch up with dozens of updates in a single frame,
-making the problem worse. `FixedTimeStep` limits catch-up to at
-most **5 intervals**, discarding excess time.
+If the browser stalls (e.g. tab switch, debugger breakpoint), the accumulated time can grow very large. Without a cap, the engine would try to catch up with dozens of updates in a single frame, making the problem worse.
+
+`FixedTimeStep` limits catch-up to at most **5 intervals**, discarding excess time.

packages/engine/src/systems/FixedTimeStep.ts

@@ -1,68 +1,122 @@
-// Import Third-party Dependencies
-import * as THREE from "three";
+// CONSTANTS
+const kDefaultMaxFps = 60;
+const kDefaultFixedFps = 60;
+const kMaxAccumulatedSteps = 5;
 
-export interface TimerAdapter {
-  update: () => void;
-  getDelta: () => number;
+class InternalTimer {
+  #last = 0;
+  #delta = 0;
+
+  start() {
+    this.#last = performance.now();
+    this.#delta = 0;
+  }
+
+  update() {
+    const now = performance.now();
+    this.#delta = now - this.#last;
+    this.#last = now;
+  }
+
+  getDelta() {
+    return this.#delta;
+  }
+}
+
+export interface FixedTimeStepCallbacks {
+  // Called every fixed step (physics/deterministic logic)
+  fixedUpdate: (fixedDelta: number) => void;
+  // Called every frame (rendering/variable logic)
+  update?: (interpolation: number, delta: number) => void;
 }
 
 export class FixedTimeStep {
-  static MaxFramesPerSecond = 60;
+  static MaxFramesPerSecond = kDefaultMaxFps;
+
+  #timer: InternalTimer;
+  #accumulated = 0;
+  #fixedDelta: number;
+  #maxAccumulated: number;
+  #running = false;
 
-  framesPerSecond = 60;
-  timestep = 1000 / this.framesPerSecond;
-  clock: TimerAdapter;
+  framesPerSecond = kDefaultMaxFps;
+  fixedFramesPerSecond = kDefaultFixedFps;
 
   constructor(
-    clock: TimerAdapter = new THREE.Timer()
+    fps: number = kDefaultMaxFps,
+    fixedFps: number = kDefaultFixedFps
   ) {
-    this.clock = clock;
+    this.framesPerSecond = fps;
+    this.fixedFramesPerSecond = fixedFps;
+    this.#fixedDelta = 1000 / this.fixedFramesPerSecond;
+    this.#maxAccumulated = kMaxAccumulatedSteps * this.#fixedDelta;
+    this.#timer = new InternalTimer();
   }
 
   setFps(
-    framesPerSecond: number | undefined
+    fps: number,
+    fixedFps: number = fps
   ): void {
-    if (!framesPerSecond) {
-      return;
+    if (typeof fps === "number") {
+      this.framesPerSecond = Math.max(1, Math.min(fps, FixedTimeStep.MaxFramesPerSecond));
+    }
+    if (typeof fixedFps === "number") {
+      this.fixedFramesPerSecond = Math.max(1, Math.min(fixedFps, FixedTimeStep.MaxFramesPerSecond));
     }
 
-    this.framesPerSecond = THREE.MathUtils.clamp(
-      framesPerSecond,
-      1,
-      FixedTimeStep.MaxFramesPerSecond
-    );
-    this.timestep = 1000 / this.framesPerSecond;
+    this.#fixedDelta = 1000 / this.fixedFramesPerSecond;
+    this.#maxAccumulated = kMaxAccumulatedSteps * this.#fixedDelta;
   }
 
+  start() {
+    this.#accumulated = 0;
+    this.#timer.start();
+    this.#running = true;
+  }
+
+  stop() {
+    this.#running = false;
+  }
+
+  /**
+   * Main loop. Call this from your requestAnimationFrame or similar.
+   * @param callbacks { fixedUpdate, update }
+   */
   tick(
-    accumulatedTime: number,
-    callback?: (deltaTime: number) => boolean
-  ): { updates: number; timeLeft: number; } {
-    this.clock.update();
-
-    const updateInterval = this.timestep;
-    let newAccumulatedTime = accumulatedTime;
-
-    // Limit how many update()s to try and catch up,
-    // to avoid falling into the "black pit of despair" aka "doom spiral".
-    // where every tick takes longer than the previous one.
-    // See http://blogs.msdn.com/b/shawnhar/archive/2011/03/25/technical-term-that-should-exist-quot-black-pit-of-despair-quot.aspx
-    const maxAccumulatedUpdates = 5;
-    const maxAccumulatedTime = maxAccumulatedUpdates * updateInterval;
-    if (newAccumulatedTime > maxAccumulatedTime) {
-      newAccumulatedTime = maxAccumulatedTime;
+    callbacks: FixedTimeStepCallbacks
+  ): void {
+    if (!this.#running) {
+      return;
     }
 
-    // Update
-    let updates = 0;
-    while (newAccumulatedTime >= updateInterval) {
-      if (callback?.(updateInterval)) {
+    this.#timer.update();
+    let delta = this.#timer.getDelta();
+    if (delta > 1000) {
+      // Prevent huge catch-up after tab switch or pause
+      delta = this.#fixedDelta;
+    }
+    this.#accumulated += delta;
+    if (this.#accumulated > this.#maxAccumulated) {
+      this.#accumulated = this.#maxAccumulated;
+    }
+
+    // Fixed update steps
+    let steps = 0;
+    while (this.#accumulated >= this.#fixedDelta) {
+      callbacks.fixedUpdate(this.#fixedDelta);
+      this.#accumulated -= this.#fixedDelta;
+      steps++;
+      if (steps > kMaxAccumulatedSteps) {
+        // Avoid spiral of death
+        this.#accumulated = 0;
         break;
       }
-      newAccumulatedTime -= updateInterval;
-      updates++;
     }
 
-    return { updates, timeLeft: newAccumulatedTime };
+    // Variable update (render/interpolation)
+    if (callbacks.update) {
+      const alpha = this.#accumulated / this.#fixedDelta;
+      callbacks.update(alpha, delta);
+    }
   }
 }

packages/engine/src/systems/index.ts

@@ -12,6 +12,7 @@ export type {
 } from "./asset/Registry.ts";
 
 export * from "./GameInstance.ts";
+export * from "./FixedTimeStep.ts";
 export * from "./rendering/index.ts";
 export * from "./Scene.ts";