@waica/engine 0.13.0 → 0.14.1

package/dist/game.js

@@ -1,11 +1,13 @@
 import * as THREE from 'three';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
+import { collisionBody } from './collision-body.js';
 import { collisionOverlap } from './collision-shape.js';
 import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
 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';
@@ -13,6 +15,7 @@ import { RuntimeInspector } from './runtime-inspection.js';
 import { projectIsometric, unprojectIsometric } from './projection.js';
 import { isYSortParticipant, ySortZ } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
+import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
 import { GameUi } from './ui.js';
 /**
@@ -24,6 +27,7 @@ export class Game {
     camera;
     input;
     pointer;
+    query;
     entities = [];
     events = new Emitter();
     stats;
@@ -44,6 +48,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 +63,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;
@@ -67,6 +84,7 @@ export class Game {
         this.viewHeight = viewHeight;
         this.resolution = options.resolution ?? null;
         this.input = new Input(options.bindings);
+        this.query = createSpatialQuery(this);
         this.stats = new Stats(options.stats);
         this.ui = new GameUi(this.stats, () => canvas.parentElement ?? document.body);
         this.audio = new AudioSubsystem({
@@ -217,7 +235,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 +288,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 +308,7 @@ export class Game {
             this.renderSurface();
             return;
         }
+        this.resetClock();
         this.renderer.setAnimationLoop((time) => this.tick(time));
     }
     stop() {
@@ -321,60 +345,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 +513,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 +551,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) {
@@ -500,21 +606,7 @@ export class Game {
                 const hb = b.get(Hitbox);
                 if (!ha || !hb)
                     continue;
-                const hit = collisionOverlap({
-                    x: a.position.x + ha.offsetX,
-                    y: a.position.y + ha.offsetY,
-                    width: ha.width,
-                    height: ha.height,
-                    shape: ha.shape,
-                    points: ha.points,
-                }, {
-                    x: b.position.x + hb.offsetX,
-                    y: b.position.y + hb.offsetY,
-                    width: hb.width,
-                    height: hb.height,
-                    shape: hb.shape,
-                    points: hb.points,
-                });
+                const hit = collisionOverlap(collisionBody(ha), collisionBody(hb));
                 if (!hit)
                     continue;
                 for (const c of [...a.components])

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';
@@ -49,6 +50,7 @@ export { cellAt, cellBounds, cellIndex } from './tilemap-grid.js';
 export type { TilemapCell, TilemapCellBounds, TilemapGridSpec, } from './tilemap-grid.js';
 export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collisionOverlap, collisionVertices, resolveCollisionPoints, } from './collision-shape.js';
 export type { CollisionBody, CollisionBounds, CollisionPoint, CollisionShape, } from './collision-shape.js';
+export type { EntityWith, NearestQueryContext, NearestSpatialQueryFilter, RayHit, SpatialQuery, SpatialQueryFilter, } from './spatial-query.js';
 export { Emitter } from './events.js';
 export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';
 export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, SceneRenderJson, PrefabJson, } from './scene.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/spatial-query-geometry.d.ts

@@ -0,0 +1,20 @@
+import { type CollisionBody } from './collision-shape.js';
+/** Internal absolute tolerance shared by point and ray boundary rules. */
+export declare const SPATIAL_QUERY_EPSILON = 1e-9;
+export interface SpatialGeometryRayHit {
+    readonly distance: number;
+    readonly point: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    readonly normal: Readonly<{
+        x: number;
+        y: number;
+    }>;
+}
+/** Valid finite geometry with a positive two-dimensional area. */
+export declare function usableCollisionBody(value: unknown): value is CollisionBody;
+/** Strict containment in the existing collision outline. */
+export declare function collisionBodyContainsPoint(body: unknown, x: number, y: number): boolean;
+/** First strict crossing against one resolved body. Direction must be normalized. */
+export declare function collisionBodyRay(body: unknown, x: number, y: number, dx: number, dy: number, maxDistance: number): SpatialGeometryRayHit | null;