@waica/engine 0.13.0 → 0.14.0

package/dist/animation/clip-player.js

@@ -1,3 +1,4 @@
+import { SIMULATION_TIME_EPSILON } from '../fixed-step.js';
 /**
  * Advances a clip through time. Pure logic (no three, no DOM) so it can
  * be tested deterministically.
@@ -16,7 +17,11 @@ export class ClipPlayer {
     /** Advances the clock and returns the sheet frame to show. */
     advance(dt) {
         this.t += dt;
-        const idx = Math.floor(this.t * this.fps);
+        // this.t is a sum of SIMULATION_STEP-sized dts, which float error can
+        // leave a hair under an exact multiple of a frame's duration; without
+        // the epsilon, floor(t * fps) holds some frames one step short and
+        // others one step long instead of a flat, even count per frame.
+        const idx = Math.floor((this.t + SIMULATION_TIME_EPSILON) * this.fps);
         const n = this.frames.length;
         const clamped = this.loop ? idx % n : Math.min(idx, n - 1);
         return this.frames[clamped] ?? 0;

package/dist/fixed-step-test-support.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Milliseconds per display frame at `hz`, for driving `Game`'s real
+ * animation-loop callback in a test. No epsilon pad: frame-rate snapping
+ * (`snapElapsedToStep`) is what makes a measured duration this close to a
+ * whole number of Simulation Steps count as exactly that many, not a float
+ * nudge chosen to dodge the exact boundary — `1000 / 60 / 1000 === 1 / 60`
+ * bit-for-bit already, before snapping even applies.
+ */
+export declare const frameMs: (hz: number) => number;

package/dist/fixed-step-test-support.js

@@ -0,0 +1,9 @@
+/**
+ * Milliseconds per display frame at `hz`, for driving `Game`'s real
+ * animation-loop callback in a test. No epsilon pad: frame-rate snapping
+ * (`snapElapsedToStep`) is what makes a measured duration this close to a
+ * whole number of Simulation Steps count as exactly that many, not a float
+ * nudge chosen to dodge the exact boundary — `1000 / 60 / 1000 === 1 / 60`
+ * bit-for-bit already, before snapping even applies.
+ */
+export const frameMs = (hz) => 1000 / hz;

package/dist/fixed-step.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The Simulation Step (ADR 0014): the fixed slice of game time by which the
+ * engine advances every component update, however often the display
+ * refreshes. An engine constant, not a project setting — the archetypes'
+ * feel is tuned against it, and the Runtime Bridge's `step` means exactly
+ * one of these.
+ */
+export declare const SIMULATION_STEP: number;
+/**
+ * The most steps one render frame may run. Beyond it the elapsed time is
+ * dropped, never repaid: a machine that cannot keep up falls behind the
+ * wall clock instead of spiralling into ever-longer frames. Six steps is
+ * 100 ms, the same ceiling the old per-frame clamp imposed.
+ */
+export declare const MAX_STEPS_PER_FRAME = 6;
+/**
+ * Floating-point slack for comparing a value built by summing many
+ * SIMULATION_STEP-sized deltas (a state's `elapsed`, a countdown, a clip's
+ * playback clock) against a target duration. Each addition can leave the
+ * sum a hair under the mathematically exact value — 15 additions of 1/60
+ * give 0.24999999999999997, not 0.25 — by an error on the order of 1e-15,
+ * many orders of magnitude below this. Large enough to call a step-multiple
+ * duration exact, far too small to ever mistake a genuinely later step for
+ * an earlier one.
+ */
+export declare const SIMULATION_TIME_EPSILON = 1e-9;
+/**
+ * Cap on same-tick, chained processing that could otherwise spin forever
+ * on a degenerate cycle: StateMachine settling a chain of transitions
+ * within one `onUpdate` (land → idle → run…) and Game draining a chain of
+ * `loadSceneByName` calls queued from a scene's own `onReady` within one
+ * frame. Shared so the two call sites' caps stay in lockstep instead of
+ * matching only by coincidence; eight is comfortably more hops than any
+ * real content chains in a single update.
+ */
+export declare const MAX_CHAINED_HOPS = 8;
+export interface SimulationSteps {
+    /** Whole steps this frame runs, 0 through MAX_STEPS_PER_FRAME. */
+    steps: number;
+    /** Seconds carried into the next frame; 0 whenever the cap was hit. */
+    remainder: number;
+}
+/**
+ * Pure accumulator: from the time retained after the last frame and the
+ * seconds elapsed since it, how many whole steps to run now and what to
+ * keep. Hitting the cap discards the whole remainder (CA-2). A non-finite
+ * or negative `elapsed` (a NaN timestamp delta, a backwards clock) is
+ * treated as zero rather than poisoning the remainder or yielding negative
+ * steps — hardening against inputs a real rAF timestamp never produces.
+ */
+export declare function consumeSimulationSteps(remainder: number, elapsed: number): SimulationSteps;
+/**
+ * How far a measured frame duration may sit from a whole number of
+ * Simulation Steps and still count as exactly that many (round 2
+ * correctness fix). Sized to absorb not just the sub-millisecond jitter a
+ * real 60 Hz `requestAnimationFrame` shows on Chromium — timestamp
+ * coarsening and float noise there put it at roughly 0.1-0.3 ms — but also
+ * the coarser 1-2 ms `requestAnimationFrame` timestamp rounding Firefox
+ * and Safari apply (their privacy/fingerprinting mitigation), without ever
+ * mistaking a genuine partial step for one of these snaps.
+ */
+export declare const STEP_SNAP_TOLERANCE = 0.0025;
+export interface SnapResult {
+    /** The elapsed time to feed the accumulator: snapped, and possibly resynced. */
+    elapsed: number;
+    /** Time discarded by snapping so far, still owed to (or by) the wall clock. */
+    residual: number;
+}
+/**
+ * Frame-rate snapping (ADR 0014, round 2 correctness): a measured frame
+ * duration that lands within STEP_SNAP_TOLERANCE of an exact multiple of
+ * SIMULATION_STEP is treated as exactly that multiple. Without this, a
+ * display refreshing at exactly 60.00 Hz can measure e.g. 16.6666 ms
+ * instead of the true 16.6667 ms — `consumeSimulationSteps` then floors the
+ * whole-steps count to 0 that frame and 2 the next, a routine 0/2-step
+ * judder at the one refresh rate ADR 0014 calls exact; on Firefox and
+ * Safari the same judder shows up permanently, every frame, because their
+ * coarser timestamp rounding never lands as close to the exact multiple as
+ * a 0.25 ms tolerance required. Applied to the raw per-frame measurement
+ * before it ever reaches the accumulator, so `consumeSimulationSteps`
+ * itself — and CA-2's 0.034 s / 0.0999 s / 0.005 s examples, each well
+ * outside the tolerance — are untouched.
+ *
+ * Every snap discards `elapsed - target`, which is carried forward in
+ * `residual` (round 3 correctness) instead of vanishing: a display a hair
+ * off 60.00 Hz — 59.94 Hz, the common NTSC-derived panel rate, discards
+ * ~0.017 ms every frame — would otherwise drift from the wall clock
+ * without bound (measured: -3.6 s/h at 59.94 Hz). Once the accumulated
+ * residual reaches a whole Simulation Step, one step is repaid into
+ * `elapsed` right away and subtracted back out of the residual, so the
+ * simulation is never more than about one step away from the wall clock.
+ */
+export declare function snapElapsedToStep(elapsed: number, residual: number): SnapResult;

package/dist/fixed-step.js

@@ -0,0 +1,109 @@
+/**
+ * The Simulation Step (ADR 0014): the fixed slice of game time by which the
+ * engine advances every component update, however often the display
+ * refreshes. An engine constant, not a project setting — the archetypes'
+ * feel is tuned against it, and the Runtime Bridge's `step` means exactly
+ * one of these.
+ */
+export const SIMULATION_STEP = 1 / 60;
+/**
+ * The most steps one render frame may run. Beyond it the elapsed time is
+ * dropped, never repaid: a machine that cannot keep up falls behind the
+ * wall clock instead of spiralling into ever-longer frames. Six steps is
+ * 100 ms, the same ceiling the old per-frame clamp imposed.
+ */
+export const MAX_STEPS_PER_FRAME = 6;
+/**
+ * Floating-point slack for comparing a value built by summing many
+ * SIMULATION_STEP-sized deltas (a state's `elapsed`, a countdown, a clip's
+ * playback clock) against a target duration. Each addition can leave the
+ * sum a hair under the mathematically exact value — 15 additions of 1/60
+ * give 0.24999999999999997, not 0.25 — by an error on the order of 1e-15,
+ * many orders of magnitude below this. Large enough to call a step-multiple
+ * duration exact, far too small to ever mistake a genuinely later step for
+ * an earlier one.
+ */
+export const SIMULATION_TIME_EPSILON = 1e-9;
+/**
+ * Cap on same-tick, chained processing that could otherwise spin forever
+ * on a degenerate cycle: StateMachine settling a chain of transitions
+ * within one `onUpdate` (land → idle → run…) and Game draining a chain of
+ * `loadSceneByName` calls queued from a scene's own `onReady` within one
+ * frame. Shared so the two call sites' caps stay in lockstep instead of
+ * matching only by coincidence; eight is comfortably more hops than any
+ * real content chains in a single update.
+ */
+export const MAX_CHAINED_HOPS = 8;
+/**
+ * Pure accumulator: from the time retained after the last frame and the
+ * seconds elapsed since it, how many whole steps to run now and what to
+ * keep. Hitting the cap discards the whole remainder (CA-2). A non-finite
+ * or negative `elapsed` (a NaN timestamp delta, a backwards clock) is
+ * treated as zero rather than poisoning the remainder or yielding negative
+ * steps — hardening against inputs a real rAF timestamp never produces.
+ */
+export function consumeSimulationSteps(remainder, elapsed) {
+    const safeElapsed = Number.isFinite(elapsed) && elapsed > 0 ? elapsed : 0;
+    const available = remainder + safeElapsed;
+    const whole = Math.floor(available / SIMULATION_STEP);
+    if (whole >= MAX_STEPS_PER_FRAME)
+        return { steps: MAX_STEPS_PER_FRAME, remainder: 0 };
+    return { steps: whole, remainder: available - whole * SIMULATION_STEP };
+}
+/**
+ * How far a measured frame duration may sit from a whole number of
+ * Simulation Steps and still count as exactly that many (round 2
+ * correctness fix). Sized to absorb not just the sub-millisecond jitter a
+ * real 60 Hz `requestAnimationFrame` shows on Chromium — timestamp
+ * coarsening and float noise there put it at roughly 0.1-0.3 ms — but also
+ * the coarser 1-2 ms `requestAnimationFrame` timestamp rounding Firefox
+ * and Safari apply (their privacy/fingerprinting mitigation), without ever
+ * mistaking a genuine partial step for one of these snaps.
+ */
+export const STEP_SNAP_TOLERANCE = 0.0025; // seconds (2.5 ms)
+/**
+ * Snapping considers only these small step counts: a display sitting
+ * exactly on one of the first few Simulation Step boundaries (60 Hz → 1,
+ * 30 Hz → 2, and so on) is the case timestamp jitter can push a hair off:
+ * higher counts already mean a hitch, where a fraction of a millisecond
+ * doesn't matter and forcing a snap would be presumptuous.
+ */
+const SNAPPABLE_STEPS = 4;
+/**
+ * Frame-rate snapping (ADR 0014, round 2 correctness): a measured frame
+ * duration that lands within STEP_SNAP_TOLERANCE of an exact multiple of
+ * SIMULATION_STEP is treated as exactly that multiple. Without this, a
+ * display refreshing at exactly 60.00 Hz can measure e.g. 16.6666 ms
+ * instead of the true 16.6667 ms — `consumeSimulationSteps` then floors the
+ * whole-steps count to 0 that frame and 2 the next, a routine 0/2-step
+ * judder at the one refresh rate ADR 0014 calls exact; on Firefox and
+ * Safari the same judder shows up permanently, every frame, because their
+ * coarser timestamp rounding never lands as close to the exact multiple as
+ * a 0.25 ms tolerance required. Applied to the raw per-frame measurement
+ * before it ever reaches the accumulator, so `consumeSimulationSteps`
+ * itself — and CA-2's 0.034 s / 0.0999 s / 0.005 s examples, each well
+ * outside the tolerance — are untouched.
+ *
+ * Every snap discards `elapsed - target`, which is carried forward in
+ * `residual` (round 3 correctness) instead of vanishing: a display a hair
+ * off 60.00 Hz — 59.94 Hz, the common NTSC-derived panel rate, discards
+ * ~0.017 ms every frame — would otherwise drift from the wall clock
+ * without bound (measured: -3.6 s/h at 59.94 Hz). Once the accumulated
+ * residual reaches a whole Simulation Step, one step is repaid into
+ * `elapsed` right away and subtracted back out of the residual, so the
+ * simulation is never more than about one step away from the wall clock.
+ */
+export function snapElapsedToStep(elapsed, residual) {
+    for (let steps = 1; steps <= SNAPPABLE_STEPS; steps += 1) {
+        const target = steps * SIMULATION_STEP;
+        if (Math.abs(elapsed - target) < STEP_SNAP_TOLERANCE) {
+            const pending = residual + (elapsed - target);
+            if (Math.abs(pending) >= SIMULATION_STEP) {
+                const repaid = Math.sign(pending) * SIMULATION_STEP;
+                return { elapsed: target + repaid, residual: pending - repaid };
+            }
+            return { elapsed: target, residual: pending };
+        }
+    }
+    return { elapsed, residual };
+}

package/dist/game.d.ts

@@ -77,6 +77,14 @@ export declare class Game {
     private readonly resizeObserver;
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
+    /**
+     * componentUpdateSchedule's result for the last composition signature seen
+     * per entity: the resolve (Tarjan SCC + Kahn sort) it's built from is pure
+     * for a fixed composition, so a signature match skips it entirely. Only
+     * ever holds a successful resolution — an invalid composition is never
+     * cached, since invalidUpdateCompositions already dedupes its console.error.
+     */
+    private readonly updateScheduleCache;
     private readonly resolution;
     /** The constructor's viewHeight — unloadScene() restores it. */
     private readonly baseViewHeight;
@@ -84,7 +92,12 @@ export declare class Game {
     private sceneCamera;
     private renderSort;
     private sceneProjection;
+    /** Timestamp of the last animation frame; null until the loop's first frame seeds it. */
     private lastTime;
+    /** Seconds of elapsed time not yet worth a whole Simulation Step (ADR 0014). */
+    private stepRemainder;
+    /** Seconds discarded by frame-rate snapping, not yet repaid (round 3 correctness). */
+    private snapResidual;
     private runtimeBridge;
     /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
     private sceneCatalog;
@@ -134,7 +147,12 @@ export declare class Game {
     loadParams(url: string): Promise<void>;
     /** Applies persisted overrides to a freshly added component. */
     applyParamOverrides(entity: Entity, component: Component): void;
-    /** Registers a function that runs once per frame. Returns the unsubscribe. */
+    /**
+     * Registers a function that runs once per Simulation Step, with the step
+     * as its dt (ADR 0014). While the Game is not simulating (the editor's edit
+     * mode) it runs once per render frame instead, so a host can keep drawing
+     * its overlays. Returns the unsubscribe.
+     */
     onUpdate(fn: UpdateFn): () => void;
     /**
      * Adopts a scene's render block. Called by loadScene; without a block the
@@ -157,9 +175,46 @@ export declare class Game {
     setViewHeight(value: number): void;
     /** Shuts the game down completely (loop, input, GPU). */
     dispose(): void;
+    /**
+     * Real-time playback for the Runtime Bridge: the same clock-driven loop
+     * as start(), sharing the accumulator, with `onStep` told after every
+     * Simulation Step so the bridge counts frames exactly as paused stepping
+     * does (CA-7). No wall-clock catch-up: the first frame only seeds the
+     * clock (CA-3).
+     */
     private resumeRuntime;
+    /** Forgets the clock and any partial step, so the next frame runs no burst. */
+    private resetClock;
+    /**
+     * One animation frame (ADR 0014): the elapsed wall-clock time joins the
+     * retained remainder, and as many whole Simulation Steps as it holds run
+     * — capped, with the excess dropped, so a hitch can neither spiral nor
+     * play in slow motion. Not simulating: no time accrues at all. The
+     * measured duration is frame-rate-snapped first (round 2 correctness) so
+     * sub-millisecond timestamp jitter at an exact cadence like 60 Hz can't
+     * flip the whole-steps floor and judder 0/2/0/2.
+     */
     private tick;
+    /**
+     * Runs `steps` Simulation Steps back to back, then the once-per-frame
+     * tail: audio activity and placements, the UI overlay and the render
+     * (CA-5). A queued scene swap flushes at the very start of the frame —
+     * loadSceneByName's contract — and again before every step after the
+     * first (CA-4), so two steps in one frame never see the same press
+     * twice or the outgoing scene once too often; a frame that runs zero
+     * steps (round 2 correctness) still flushes, so it never renders/
+     * audio-places the outgoing scene one frame longer than it should.
+     */
     private runFrame;
+    /**
+     * One Simulation Step: the Component Update Schedule (ADR 0004) in full,
+     * collisions, the scene camera and the host's callbacks, every one of
+     * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
+     */
+    private simulateStep;
+    /** Closes a step (real or the non-simulating stand-in): host callbacks, then the input frame. */
+    private finishStep;
+    private runHostUpdates;
     private flushPendingSceneLoad;
     private unregisterRuntimeBridge;
     /** Under y-sort, re-derives every participant's z from layer band + entity Y. */

package/dist/game.js

@@ -6,6 +6,7 @@ import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Hitbox } from './components/hitbox.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
+import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedToStep, } from './fixed-step.js';
 import { Input } from './input.js';
 import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
@@ -44,6 +45,14 @@ export class Game {
     resizeObserver;
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
+    /**
+     * componentUpdateSchedule's result for the last composition signature seen
+     * per entity: the resolve (Tarjan SCC + Kahn sort) it's built from is pure
+     * for a fixed composition, so a signature match skips it entirely. Only
+     * ever holds a successful resolution — an invalid composition is never
+     * cached, since invalidUpdateCompositions already dedupes its console.error.
+     */
+    updateScheduleCache = new WeakMap();
     resolution;
     /** The constructor's viewHeight — unloadScene() restores it. */
     baseViewHeight;
@@ -51,7 +60,12 @@ export class Game {
     sceneCamera = null;
     renderSort = null;
     sceneProjection = null;
-    lastTime = 0;
+    /** Timestamp of the last animation frame; null until the loop's first frame seeds it. */
+    lastTime = null;
+    /** Seconds of elapsed time not yet worth a whole Simulation Step (ADR 0014). */
+    stepRemainder = 0;
+    /** Seconds discarded by frame-rate snapping, not yet repaid (round 3 correctness). */
+    snapResidual = 0;
     runtimeBridge = null;
     /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
     sceneCatalog = null;
@@ -217,7 +231,12 @@ export class Game {
         if (override)
             Object.assign(component, override);
     }
-    /** Registers a function that runs once per frame. Returns the unsubscribe. */
+    /**
+     * Registers a function that runs once per Simulation Step, with the step
+     * as its dt (ADR 0014). While the Game is not simulating (the editor's edit
+     * mode) it runs once per render frame instead, so a host can keep drawing
+     * its overlays. Returns the unsubscribe.
+     */
     onUpdate(fn) {
         this.updateFns.add(fn);
         return () => this.updateFns.delete(fn);
@@ -265,8 +284,8 @@ export class Game {
             if (!this.runtimeBridge) {
                 const inspector = new RuntimeInspector(this);
                 this.runtimeBridge = new EngineRuntimeBridge(this.renderer.domElement, activation, {
-                    step: (dt) => this.runFrame(dt),
-                    resume: (frame) => this.resumeRuntime(frame),
+                    step: (onStep) => this.runFrame(1, onStep),
+                    resume: (onStep) => this.resumeRuntime(onStep),
                     pause: () => this.stop(),
                     injectAction: (action, operation) => this.input.injectAction(action, operation),
                     availableActions: () => this.input.availableActions(),
@@ -285,6 +304,7 @@ export class Game {
             this.renderSurface();
             return;
         }
+        this.resetClock();
         this.renderer.setAnimationLoop((time) => this.tick(time));
     }
     stop() {
@@ -321,60 +341,129 @@ export class Game {
             entity.destroy();
         this.renderer.dispose();
     }
-    resumeRuntime(frame) {
-        let previousTime = null;
-        this.renderer.setAnimationLoop((time) => {
-            const dt = previousTime === null ? 0 : Math.min((time - previousTime) / 1000, 0.1);
-            previousTime = time;
-            frame(dt);
-        });
+    /**
+     * Real-time playback for the Runtime Bridge: the same clock-driven loop
+     * as start(), sharing the accumulator, with `onStep` told after every
+     * Simulation Step so the bridge counts frames exactly as paused stepping
+     * does (CA-7). No wall-clock catch-up: the first frame only seeds the
+     * clock (CA-3).
+     */
+    resumeRuntime(onStep) {
+        this.resetClock();
+        this.renderer.setAnimationLoop((time) => this.tick(time, onStep));
     }
-    tick(time) {
-        // Clamp dt: switching tabs or pausing doesn't fast-forward the simulation.
-        const dt = Math.min((time - this.lastTime) / 1000, 0.1);
+    /** Forgets the clock and any partial step, so the next frame runs no burst. */
+    resetClock() {
+        this.lastTime = null;
+        this.stepRemainder = 0;
+        this.snapResidual = 0;
+    }
+    /**
+     * One animation frame (ADR 0014): the elapsed wall-clock time joins the
+     * retained remainder, and as many whole Simulation Steps as it holds run
+     * — capped, with the excess dropped, so a hitch can neither spiral nor
+     * play in slow motion. Not simulating: no time accrues at all. The
+     * measured duration is frame-rate-snapped first (round 2 correctness) so
+     * sub-millisecond timestamp jitter at an exact cadence like 60 Hz can't
+     * flip the whole-steps floor and judder 0/2/0/2.
+     */
+    tick(time, onStep) {
+        const measured = this.lastTime === null ? 0 : (time - this.lastTime) / 1000;
         this.lastTime = time;
-        this.runFrame(dt);
+        if (!this.simulate) {
+            this.stepRemainder = 0;
+            this.snapResidual = 0;
+            this.runFrame(0);
+            return;
+        }
+        const { elapsed, residual } = snapElapsedToStep(measured, this.snapResidual);
+        this.snapResidual = residual;
+        const { steps, remainder } = consumeSimulationSteps(this.stepRemainder, elapsed);
+        this.stepRemainder = remainder;
+        this.runFrame(steps, onStep);
     }
-    runFrame(dt) {
+    /**
+     * Runs `steps` Simulation Steps back to back, then the once-per-frame
+     * tail: audio activity and placements, the UI overlay and the render
+     * (CA-5). A queued scene swap flushes at the very start of the frame —
+     * loadSceneByName's contract — and again before every step after the
+     * first (CA-4), so two steps in one frame never see the same press
+     * twice or the outgoing scene once too often; a frame that runs zero
+     * steps (round 2 correctness) still flushes, so it never renders/
+     * audio-places the outgoing scene one frame longer than it should.
+     */
+    runFrame(steps, onStep) {
         this.insideFrame = true;
         try {
-            // Flushes a scene swap enqueued mid-frame last time (CA-7): applied
-            // before this frame's own simulation, so the incoming scene's
-            // entities are present only from this next frame onward.
             this.flushPendingSceneLoad();
             if (this.simulate) {
-                for (const entity of [...this.entities]) {
-                    const schedule = this.componentUpdateSchedule(entity);
-                    if (!schedule)
-                        continue;
-                    for (const component of schedule)
-                        component.onUpdate?.(dt);
+                // Re-read every iteration, not just once before the loop: a
+                // component or host callback can set `simulate = false` mid-step,
+                // and the remaining steps of this catch-up frame must not run.
+                for (let index = 0; index < steps && this.simulate; index += 1) {
+                    // Step 0 was just flushed above; only later steps need it again.
+                    if (index > 0)
+                        this.flushPendingSceneLoad();
+                    this.simulateStep();
+                    onStep?.();
                 }
-                this.dispatchCollisions();
-                this.updateSceneCamera(dt);
             }
-            // The UI must react to the pause itself (hide until resumed).
-            this.ui.setActive(this.simulate);
+            else {
+                // [DEVIATION 2026-09-12] The editor draws its edit-mode overlays from
+                // game.onUpdate with simulate = false (Viewport.tsx), exactly as it
+                // did before the fixed step: a non-simulating frame runs no step but
+                // still hands the host one callback and closes the input frame.
+                this.finishStep();
+            }
             this.audio.setActive(this.simulate);
             // Positional audio (CA-8): recomputed every frame, on this same pass —
             // never a second walk of `this.entities`, since `this.audio` already
             // holds direct references to whichever entities are tracked.
             this.audio.updatePlacements(this.audioListenerPosition(), (x, y) => this.renderPoint(x, y));
-            for (const fn of this.updateFns)
-                fn(dt);
-            this.input.endFrame();
             this.renderSurface();
         }
         finally {
             this.insideFrame = false;
         }
     }
+    /**
+     * One Simulation Step: the Component Update Schedule (ADR 0004) in full,
+     * collisions, the scene camera and the host's callbacks, every one of
+     * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
+     */
+    simulateStep() {
+        for (const entity of [...this.entities]) {
+            const schedule = this.componentUpdateSchedule(entity);
+            if (!schedule)
+                continue;
+            for (const component of schedule)
+                component.onUpdate?.(SIMULATION_STEP);
+        }
+        this.dispatchCollisions();
+        this.updateSceneCamera(SIMULATION_STEP);
+        this.finishStep();
+    }
+    /** Closes a step (real or the non-simulating stand-in): host callbacks, then the input frame. */
+    finishStep() {
+        this.runHostUpdates();
+        this.input.endFrame();
+    }
+    runHostUpdates() {
+        for (const fn of this.updateFns)
+            fn(SIMULATION_STEP);
+    }
     flushPendingSceneLoad() {
-        const pending = this.pendingSceneLoad;
-        if (!pending)
-            return;
-        this.pendingSceneLoad = null;
-        pending();
+        // Drains the whole chain, not just one level: a loadSceneByName called
+        // from the incoming scene's onReady (still insideFrame) re-queues
+        // pendingSceneLoad, and a frame that runs zero steps never reaches the
+        // per-step flush that would otherwise pick it up next. Capped like the
+        // state machine's chained-transition loop (MAX_CHAINED_HOPS), so a
+        // degenerate scene cycle can't hang here either.
+        for (let hops = 0; hops < MAX_CHAINED_HOPS && this.pendingSceneLoad; hops += 1) {
+            const pending = this.pendingSceneLoad;
+            this.pendingSceneLoad = null;
+            pending();
+        }
     }
     unregisterRuntimeBridge = () => {
         window.removeEventListener('pagehide', this.unregisterRuntimeBridge);
@@ -420,24 +509,36 @@ export class Game {
     }
     componentUpdateSchedule(entity) {
         const components = [...entity.components];
-        const registry = {
-            ...(this.registry?.components ?? {}),
-        };
         const byName = new Map();
         const names = [];
         const signatureParts = [];
         for (const component of components) {
             const Class = component.constructor;
             const name = Class.componentName;
-            registry[name] = Class;
             names.push(name);
             byName.set(name, component);
             signatureParts.push(`${name}:${typeof Class.prototype.onUpdate === 'function' ? 'updates' : 'passive'}:` +
                 [...new Set(Class.updateAfter ?? [])].sort().join(','));
         }
+        const signature = signatureParts.sort().join('|');
+        // The resolve below (duplicate check + Tarjan SCC + Kahn sort) is pure
+        // for a fixed composition, and this method now runs once per entity per
+        // Simulation Step rather than once per rendered frame: skip it entirely
+        // when nothing about this entity's components changed since last time.
+        const cached = this.updateScheduleCache.get(entity);
+        if (cached && cached.signature === signature) {
+            return cached.order.map((name) => byName.get(name));
+        }
+        const registry = {
+            ...(this.registry?.components ?? {}),
+        };
+        for (const component of components) {
+            const Class = component.constructor;
+            registry[Class.componentName] = Class;
+        }
         const result = resolveComponentUpdateSchedule(names, registry);
         if (!result.ok) {
-            const signature = signatureParts.sort().join('|');
+            this.updateScheduleCache.delete(entity);
             if (this.invalidUpdateCompositions.get(entity) !== signature) {
                 this.invalidUpdateCompositions.set(entity, signature);
                 console.error(`[waica] invalid component update schedule for "${entity.name}": ` +
@@ -446,6 +547,7 @@ export class Game {
             return null;
         }
         this.invalidUpdateCompositions.delete(entity);
+        this.updateScheduleCache.set(entity, { signature, order: result.order });
         return result.order.map((name) => byName.get(name));
     }
     updateSceneCamera(dt) {

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export type { ProjectedPoint } from './projection.js';
 export { spritePlacement } from './sprite-placement.js';
 export type { SpritePlacement, SpritePlacementInput } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
+export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
 export type { SceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export { isYSortParticipant, ySortZ } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
 export { spritePlacement } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
+export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';

package/dist/runtime-bridge.d.ts

@@ -9,9 +9,10 @@ export type RuntimeMode = 'paused' | 'real-time';
  * pre-CA-10 engine simply lacks this field, which is exactly what callers
  * gating on capabilities check for (review finding #4) — protocol 1 alone
  * doesn't distinguish an engine that silently no-ops an unknown operation
- * from one that runs it.
+ * from one that runs it. `fixed-step` (ADR 0014) announces that `step`
+ * advances whole 1/60 s Simulation Steps and takes no `dt`.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -25,9 +26,10 @@ export type RuntimeControlRequest = {
     action: string;
 } | {
     operation: 'pause' | 'resume';
-} | {
+}
+/** Advances `frames` whole Simulation Steps (1/60 s each, ADR 0014); default 1. */
+ | {
     operation: 'step';
-    dt?: number;
     frames?: number;
 } | {
     operation: 'click';
@@ -62,8 +64,14 @@ export interface RuntimeBridgeActivation {
 }
 export declare function activeRuntimeBridgeHook(): RuntimeBridgeActivation | null;
 export interface RuntimeBridgeHost {
-    step(dt: number): void;
-    resume(frame: (dt: number) => void): void;
+    /**
+     * Runs exactly one Simulation Step and renders; `onStep` is told only if a
+     * step actually ran (the Game may be non-simulating, in which case this
+     * renders a frame but advances nothing).
+     */
+    step(onStep: () => void): void;
+    /** Starts clock-driven playback; `onStep` is told after every Simulation Step. */
+    resume(onStep: () => void): void;
     pause(): void;
     injectAction(action: string, operation: 'press' | 'hold' | 'release'): boolean;
     availableActions(): string[];
@@ -81,12 +89,13 @@ export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly engineVersion: string;
     private registered;
     private mode;
+    /** Simulation Steps advanced since registration, paused or real-time alike. */
     private frame;
-    private simulationTime;
     constructor(surface: HTMLCanvasElement, activation: RuntimeBridgeActivation, host: RuntimeBridgeHost);
     metadata(): RuntimeMetadata;
     inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     control(request: RuntimeControlRequest): RuntimeControlResult;
+    /** Counts one Simulation Step, whoever ran it (paused stepping or real-time playback). */
     private advance;
     unregister(): void;
 }

package/dist/runtime-bridge.js

@@ -1,4 +1,5 @@
 import enginePackage from '../package.json' with { type: 'json' };
+import { SIMULATION_STEP } from './fixed-step.js';
 export const RUNTIME_BRIDGE_PROTOCOL_VERSION = 1;
 export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
 /**
@@ -8,9 +9,10 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * pre-CA-10 engine simply lacks this field, which is exactly what callers
  * gating on capabilities check for (review finding #4) — protocol 1 alone
  * doesn't distinguish an engine that silently no-ops an unknown operation
- * from one that runs it.
+ * from one that runs it. `fixed-step` (ADR 0014) announces that `step`
+ * advances whole 1/60 s Simulation Steps and takes no `dt`.
  */
-export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene'];
+export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene', 'fixed-step'];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;
@@ -43,8 +45,8 @@ export class EngineRuntimeBridge {
     engineVersion = enginePackage.version;
     registered = true;
     mode = 'paused';
+    /** Simulation Steps advanced since registration, paused or real-time alike. */
     frame = 0;
-    simulationTime = 0;
     constructor(surface, activation, host) {
         this.surface = surface;
         this.activation = activation;
@@ -56,7 +58,8 @@ export class EngineRuntimeBridge {
             engineVersion: this.engineVersion,
             mode: this.mode,
             frame: this.frame,
-            simulationTime: this.simulationTime,
+            // Derived, never summed: 60 steps are exactly 1 s, with no float drift.
+            simulationTime: this.frame * SIMULATION_STEP,
             capabilities: RUNTIME_BRIDGE_CAPABILITIES,
         };
     }
@@ -74,7 +77,7 @@ export class EngineRuntimeBridge {
             case 'resume':
                 if (this.mode === 'paused') {
                     this.mode = 'real-time';
-                    this.host.resume((dt) => this.advance(dt));
+                    this.host.resume(() => this.advance());
                 }
                 break;
             case 'press':
@@ -89,16 +92,18 @@ export class EngineRuntimeBridge {
                 if (this.mode !== 'paused') {
                     throw new RuntimeBridgeOperationError('runtime-invalid-state', 'step is only available while the Runtime Bridge is paused.');
                 }
-                const dt = request.dt ?? 1 / 60;
-                const frames = request.frames ?? 1;
-                if (!Number.isFinite(dt) || dt <= 0 || dt > 0.1) {
-                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'dt must be finite and greater than 0 and at most 0.1.');
+                // A caller-chosen dt is rejected outright, never ignored: a pre-ADR-0014
+                // client that still sends one would otherwise believe it stepped by it.
+                if ('dt' in request) {
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'step takes no dt: it advances whole Simulation Steps of 1/60 s each; pass frames (1 through 600) instead.');
                 }
+                const frames = request.frames ?? 1;
                 if (!Number.isInteger(frames) || frames < 1 || frames > 600) {
                     throw new RuntimeBridgeOperationError('runtime-operation-failed', 'frames must be an integer from 1 through 600.');
                 }
-                for (let index = 0; index < frames; index += 1)
-                    this.advance(dt);
+                for (let index = 0; index < frames; index += 1) {
+                    this.host.step(() => this.advance());
+                }
                 break;
             }
             case 'click': {
@@ -122,10 +127,9 @@ export class EngineRuntimeBridge {
         }
         return { ...this.metadata(), heldActions: this.host.heldActions() };
     }
-    advance(dt) {
-        this.host.step(dt);
+    /** Counts one Simulation Step, whoever ran it (paused stepping or real-time playback). */
+    advance() {
         this.frame += 1;
-        this.simulationTime += dt;
     }
     unregister() {
         if (!this.registered)

package/dist/state/state-machine.js

@@ -1,6 +1,7 @@
 import { installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from '../animation/directional.js';
 import { Component } from '../component.js';
 import { AnimatedSprite } from '../components/animated-sprite.js';
+import { MAX_CHAINED_HOPS, SIMULATION_TIME_EPSILON } from '../fixed-step.js';
 import { closestLogicSet, logicSet, registeredLogicSets, } from './hooks.js';
 /** Whether one trigger fires. Unknown or malformed triggers never fire. */
 export function evaluateTrigger(on, env) {
@@ -11,8 +12,15 @@ export function evaluateTrigger(on, env) {
     const arg = on.slice(sep + 1);
     if (kind === 'input')
         return env.justPressed(arg);
+    // A float epsilon of tolerance, not half a Simulation Step: `elapsed` is
+    // a sum of many SIMULATION_STEP-sized dts, and float error can leave it a
+    // hair under an exact multiple (15 additions of 1/60 give
+    // 0.24999999999999997, not 0.25), which a bare `>=` would fire one whole
+    // step late. A tolerance as wide as half a step instead fired non-multiple
+    // durations one whole step early, since a target can sit closer to the
+    // step below than to the one it truly belongs to.
     if (kind === 'timer')
-        return env.elapsed >= Number(arg);
+        return env.elapsed + SIMULATION_TIME_EPSILON >= Number(arg);
     if (kind === 'signal')
         return env.signals.has(arg);
     return false;
@@ -105,7 +113,7 @@ export class StateMachine extends Component {
         this.elapsed += dt;
         // Chained transitions settle within the frame (e.g. land → idle → run),
         // capped so a degenerate cyclic graph can't hang the loop.
-        for (let hops = 0; hops < 8; hops++) {
+        for (let hops = 0; hops < MAX_CHAINED_HOPS; hops++) {
             const edge = nextTransition(this.states, this.current, this.env());
             // A '*' edge is re-merged against whatever state the loop just
             // entered, so a still-queued signal (signals.clear() only runs after

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",