@waica/engine 0.13.0 → 0.14.1

package/README.md

@@ -6,6 +6,47 @@ Waica's public engine core: entities and components, the game loop, scene and pr
 import { Component, Game, loadScene } from '@waica/engine'
 ```
 
+## Logical spatial queries
+
+Every `Game` owns one stable `game.query` service. Queries use logical XY coordinates, including in isometric scenes, and return typed live engine objects:
+
+```ts
+import { Component, type CollisionBody, type Entity, type Game } from '@waica/engine'
+
+declare const game: Game
+declare const player: Entity
+
+class Faction extends Component {
+  name = 'neutral'
+}
+
+const search: CollisionBody = { x: 0, y: 0, width: 8, height: 6 }
+const nearby = game.query.area(search, {
+  with: [Faction] as const,
+  exclude: player,
+  where: (entity) => entity.get(Faction).name !== 'friendly',
+})
+
+// `with` makes this non-optional at compile time.
+nearby[0]?.get(Faction).name
+```
+
+| Method | Spatial domain | Result |
+| --- | --- | --- |
+| `area(body, filter?)` | Hitbox collision outlines | All overlapping Hitbox owners |
+| `point(x, y, filter?)` | Hitbox collision outlines | All strict point containers |
+| `nearest(x, y, filter?)` | Entity logical transforms | The nearest Entity or `null` |
+| `ray(x, y, dx, dy, maxDistance, filter?)` | Direct and source-derived Solids | The first `RayHit` or `null` |
+| `Pointer` picking | Sprite visuals in projected/render space | The front-most visual owner |
+
+Every filter can require all classes in `with`, reject any class in `without`, exclude one Entity, a readonly Entity array, or a `ReadonlySet` by identity, and apply a final `where` predicate. `nearest` also accepts inclusive `maxDistance` and passes `{ distance }` to `where`. Filters compose conjunctively. Ray filters apply to each Solid's owner; for example, a generated Tilemap Solid can match `with: [Tilemap]`, but only an owner with a direct Solid matches `with: [Solid]`.
+
+Calls eagerly snapshot candidates that are alive at call start. Results preserve scene/source order, and ties keep the first candidate. Later spawns do not enter a result and later destruction does not remove it. Returned Entity, Component, and Solid references remain live; a `RayHit`'s distance, point, and normal are detached query-time values.
+
+Invalid inputs fail closed without throwing: invalid `area` bodies and non-finite point coordinates return `[]`; invalid nearest coordinates or radii return `null`; and ray returns `null` for non-finite values, a zero direction, or a negative distance. Nearest permits positive `Infinity`; ray distance must be finite and may be zero. Zero-area candidate geometry never matches.
+
+Area and point intentionally use the collision system's polygonally approximated circle/ellipse outline. Ray queries intersect circle-shaped Solids as analytic ellipses and return their exact outward unit normal.
+
 ## Component lifecycle
 
 Waica keeps the lifecycle boundaries distinct:

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/collision-body.d.ts

@@ -0,0 +1,5 @@
+import type { CollisionBody } from './collision-shape.js';
+import type { Hitbox } from './components/hitbox.js';
+import type { Solid } from './components/solid.js';
+/** Package-internal conversion shared by trigger dispatch and spatial queries. */
+export declare function collisionBody(component: Hitbox | Solid): CollisionBody;

package/dist/collision-body.js

@@ -0,0 +1,11 @@
+/** Package-internal conversion shared by trigger dispatch and spatial queries. */
+export function collisionBody(component) {
+    return {
+        x: component.entity.position.x + component.offsetX,
+        y: component.entity.position.y + component.offsetY,
+        width: component.width,
+        height: component.height,
+        shape: component.shape,
+        points: component.points,
+    };
+}

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

@@ -8,6 +8,7 @@ import { Emitter } from './events.js';
 import { Input, type InputBindings } from './input.js';
 import { Pointer } from './pointer.js';
 import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
+import { type SpatialQuery } from './spatial-query.js';
 import { Stats, type StatValue } from './stats.js';
 import { GameUi } from './ui.js';
 /** Fixed game resolution: the view keeps this aspect, letterboxed. */
@@ -58,6 +59,7 @@ export declare class Game {
     readonly camera: THREE.OrthographicCamera;
     readonly input: Input;
     readonly pointer: Pointer;
+    readonly query: SpatialQuery;
     readonly entities: Entity[];
     readonly events: Emitter;
     readonly stats: Stats;
@@ -77,6 +79,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 +94,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 +149,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 +177,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. */