@waica/engine 0.14.0 → 0.15.0

package/README.md

@@ -6,6 +6,93 @@ Waica's public engine core: entities and components, the game loop, scene and pr
 import { Component, Game, loadScene } from '@waica/engine'
 ```
 
+## Hitbox Collision Layers and Masks
+
+Every `Hitbox` belongs to one named Collision Layer and declares the other layers in which it is interested through a Collision Mask:
+
+```ts
+import { Hitbox } from '@waica/engine'
+
+entity.add(Hitbox, {
+  layer: 'projectile',
+  collidesWith: ['enemy'],
+})
+```
+
+A layer must match `^[a-z][a-z0-9-]*$`. Layer names form an open, project-owned vocabulary; matching is exact and case-sensitive. `"*"` is valid only in a mask and matches every valid layer. An empty mask means no outgoing interest. Invalid layers cannot be targeted, and invalid or non-string mask entries are ignored without runtime coercion or warnings.
+
+A pair reaches exact overlap testing when either side's mask names the other side's layer. After an overlap, only an interested side receives `onCollide`; a one-way projectile mask therefore does not notify its target. Omitted fields retain the compatibility defaults `layer: 'default'` and `collidesWith: ['*']`, so two unconfigured Hitboxes still notify both sides.
+
+Layers and masks are read while the collision-pair snapshot is consumed. A component can change them during `onUpdate` or one callback and affect later pairs in that Simulation Step. Pair order remains the original lexicographic Entity order, component callbacks remain in insertion order, and destroyed entities are still skipped between sides.
+
+### Shipped taxonomy and migration
+
+Waica's shipped prefabs use this directional policy:
+
+| Hitbox owner | `layer` | `collidesWith` |
+| --- | --- | --- |
+| Player | `player` | `['*']` |
+| Slime, blob, or orc / `Hazard` | `enemy` | `['player']` |
+| Coin, potion, or crate / `Collectible` | `collectible` | `['player']` |
+| Overlap `SceneTransition` | `scene-transition` | `['player']` |
+| Platformer projectile | `projectile` | `['enemy']` |
+
+`Collectible`, `Hazard`, overlap `SceneTransition`, and the example projectile trust those masks and no longer recheck the other Entity's role inside `onCollide`. Existing external projects using any of these handlers must explicitly migrate their sibling Hitboxes before relying on the new behavior. The defaults preserve engine-level callback delivery, but a wildcard-backed migrated handler can act on unintended default-layer entities.
+
+1. Assign `player` / `['*']` to player Hitboxes.
+2. Assign the relevant row above to each shipped handler carrier, or choose equivalent project-owned names.
+3. Run MCP `validate_project`; malformed values are errors and duplicate mask entries are warnings.
+4. Keep `trigger: 'interact'` Scene Transitions unchanged—their Hitbox mask is relevant only to overlap mode.
+
+The editor and MCP author explicit categories for newly generated player/enemy identities. NPCs, custom or identity-less characters, generic objects, and existing external project files are not inferred or rewritten. `public/waica.params.json` may override either field with the same exact values, including a `string[]` mask.
+
+## Collision broadphase
+
+The Game uses fresh internal uniform grids to accelerate automatic Hitbox dispatch, Hitbox-backed `area`/`point` queries, and Solid-backed `ray` queries. Hitboxes and Solids stay in separate domains. `nearest`, `DynamicBody` physical-contact solving, Pointer picking, navigation, and unrelated scans remain linear or otherwise unchanged.
+
+The grid changes candidate discovery only: existing exact geometry is still authoritative. Each operation observes candidates alive at its start, preserves Entity or Solid source order and tie behavior, and recomputes after scene swaps, spawns, movement, shape edits, or Tilemap-derived Solid changes. Oversized bodies and query regions fall back conservatively, so they may cost more but cannot lose results. Grid sizing, occupancy limits, indices, and rebuild controls are deliberately package-internal and have no public tuning API.
+
+## 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. Collision Layers and Masks never filter `area` or `point`; use a query filter when category-like eligibility is needed.
+
 ## Component lifecycle
 
 Waica keeps the lifecycle boundaries distinct:

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

@@ -0,0 +1,4 @@
+/** Package-internal runtime syntax check for one Collision Layer. */
+export declare function validCollisionLayer(value: unknown): value is string;
+/** Package-internal exact directional interest check. */
+export declare function collisionMaskTargets(mask: unknown, targetLayer: unknown): boolean;

package/dist/collision-category.js

@@ -0,0 +1,11 @@
+const COLLISION_LAYER_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Package-internal runtime syntax check for one Collision Layer. */
+export function validCollisionLayer(value) {
+    return typeof value === 'string' && COLLISION_LAYER_PATTERN.test(value);
+}
+/** Package-internal exact directional interest check. */
+export function collisionMaskTargets(mask, targetLayer) {
+    if (!validCollisionLayer(targetLayer) || !Array.isArray(mask))
+        return false;
+    return mask.some((entry) => typeof entry === 'string' && (entry === '*' || entry === targetLayer));
+}

package/dist/collision-dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { Game } from './game.js';
+/** Package-internal deterministic work receipt used by focused tests. */
+export interface CollisionDispatchStats {
+    readonly candidatePairs: number;
+    readonly narrowphaseCalls: number;
+}
+/** Game's package-internal trigger dispatch implementation. */
+export declare function dispatchCollisions(game: Game): CollisionDispatchStats;

package/dist/collision-dispatch.js

@@ -0,0 +1,36 @@
+import { collisionBody } from './collision-body.js';
+import { collisionMaskTargets } from './collision-category.js';
+import { collisionOverlap } from './collision-shape.js';
+import { Hitbox } from './components/hitbox.js';
+import { createHitboxBroadphase } from './spatial-broadphase.js';
+/** Game's package-internal trigger dispatch implementation. */
+export function dispatchCollisions(game) {
+    const pairs = createHitboxBroadphase(game).pairs();
+    let narrowphaseCalls = 0;
+    for (const [first, second] of pairs) {
+        const a = first.entity;
+        const b = second.entity;
+        if (!a.alive || !b.alive)
+            continue;
+        if (a.get(Hitbox) !== first.hitbox || b.get(Hitbox) !== second.hitbox)
+            continue;
+        const notifyA = collisionMaskTargets(first.hitbox.collidesWith, second.hitbox.layer);
+        const notifyB = collisionMaskTargets(second.hitbox.collidesWith, first.hitbox.layer);
+        if (!notifyA && !notifyB)
+            continue;
+        narrowphaseCalls += 1;
+        if (!collisionOverlap(collisionBody(first.hitbox), collisionBody(second.hitbox)))
+            continue;
+        if (notifyA) {
+            for (const component of [...a.components])
+                component.onCollide?.(b);
+        }
+        if (!a.alive || !b.alive)
+            continue;
+        if (notifyB) {
+            for (const component of [...b.components])
+                component.onCollide?.(a);
+        }
+    }
+    return { candidatePairs: pairs.length, narrowphaseCalls };
+}

package/dist/component.d.ts

@@ -7,6 +7,8 @@ export interface ParamSpec {
     min?: number;
     max?: number;
     step?: number;
+    /** Specialized editor control for values that are otherwise plain JSON. */
+    kind?: 'string-list';
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */
@@ -65,7 +67,7 @@ export declare abstract class Component {
     onUpdate?(dt: number): void;
     /** Runs after the scene changes between identity and projected rendering. */
     onProjectionChange?(projection: 'isometric' | null): void;
-    /** Runs when this entity's Hitbox overlaps another one's. */
+    /** Runs on overlap when this entity's Hitbox mask names the other's layer. */
     onCollide?(other: Entity): void;
     /** Runs when this entity's DynamicBody physically contacts a Solid. */
     onContact?(contact: SolidContact): void;

package/dist/components/hitbox.d.ts

@@ -1,13 +1,21 @@
 import { Component } from '../component.js';
 import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
 /**
- * Trigger collider: the Game detects overlaps between Hitboxes and calls
- * onCollide(other) on both entities' components. For static physical
+ * Trigger collider. A pair is tested when either Hitbox's Collision Mask
+ * names the other's Collision Layer; only each interested owner receives
+ * `onCollide`. Spatial Queries ignore categories. For static physical
  * collision see Solid.
  */
 export declare class Hitbox extends Component {
     static componentName: string;
     static params: {
+        layer: {
+            label: string;
+        };
+        collidesWith: {
+            label: string;
+            kind: 'string-list';
+        };
         offsetX: {
             label: string;
         };
@@ -15,6 +23,10 @@ export declare class Hitbox extends Component {
             label: string;
         };
     };
+    /** One exact, case-sensitive `^[a-z][a-z0-9-]*$` membership name. */
+    layer: string;
+    /** Outgoing layer interest; `'*'` means every valid layer and `[]` means none. */
+    collidesWith: string[];
     shape: CollisionShape;
     width: number;
     height: number;

package/dist/components/hitbox.js

@@ -1,16 +1,23 @@
 import { Component } from '../component.js';
 import { resolveCollisionPoints, } from '../collision-shape.js';
 /**
- * Trigger collider: the Game detects overlaps between Hitboxes and calls
- * onCollide(other) on both entities' components. For static physical
+ * Trigger collider. A pair is tested when either Hitbox's Collision Mask
+ * names the other's Collision Layer; only each interested owner receives
+ * `onCollide`. Spatial Queries ignore categories. For static physical
  * collision see Solid.
  */
 export class Hitbox extends Component {
     static componentName = 'Hitbox';
     static params = {
+        layer: { label: 'Collision Layer' },
+        collidesWith: { label: 'Collision Mask', kind: 'string-list' },
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },
     };
+    /** One exact, case-sensitive `^[a-z][a-z0-9-]*$` membership name. */
+    layer = 'default';
+    /** Outgoing layer interest; `'*'` means every valid layer and `[]` means none. */
+    collidesWith = ['*'];
     shape = 'rectangle';
     width = 1;
     height = 1;

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. */
@@ -48,7 +49,7 @@ export interface SceneCatalog {
     registry: SceneRegistry;
 }
 /** Persisted overrides: entity → componentName → prop → value. */
-export type ParamOverrides = Record<string, Record<string, Record<string, number | boolean | string>>>;
+export type ParamOverrides = Record<string, Record<string, Record<string, number | boolean | string | string[]>>>;
 /**
  * Engine core: loop, unified 2D/3D three scene, orthographic camera,
  * entities with components, and input. See DESIGN.md.
@@ -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;
@@ -135,8 +137,8 @@ export declare class Game {
      * the live scene. An unknown name warns and leaves the live scene
      * untouched. Triggered mid-frame (e.g. from a SceneTransition's
      * onCollide/onInteract) the swap is deferred to the very start of the
-     * next runFrame — dispatchCollisions finishes its double loop over the
-     * outgoing scene, and the incoming scene's entities are present only
+     * next runFrame — dispatchCollisions finishes its frozen pair snapshot for
+     * the outgoing scene, and the incoming scene's entities are present only
      * from the next frame. Called from outside a frame (boot, or the Runtime
      * Bridge's `scene` control operation) it applies synchronously and wins
      * over anything queued earlier this frame. A second mid-frame request

package/dist/game.js

@@ -1,9 +1,8 @@
 import * as THREE from 'three';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
-import { collisionOverlap } from './collision-shape.js';
+import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.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';
@@ -14,6 +13,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';
 /**
@@ -25,6 +25,7 @@ export class Game {
     camera;
     input;
     pointer;
+    query;
     entities = [];
     events = new Emitter();
     stats;
@@ -81,6 +82,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({
@@ -177,8 +179,8 @@ export class Game {
      * the live scene. An unknown name warns and leaves the live scene
      * untouched. Triggered mid-frame (e.g. from a SceneTransition's
      * onCollide/onInteract) the swap is deferred to the very start of the
-     * next runFrame — dispatchCollisions finishes its double loop over the
-     * outgoing scene, and the incoming scene's entities are present only
+     * next runFrame — dispatchCollisions finishes its frozen pair snapshot for
+     * the outgoing scene, and the incoming scene's entities are present only
      * from the next frame. Called from outside a frame (boot, or the Runtime
      * Bridge's `scene` control operation) it applies synchronously and wins
      * over anything queued earlier this frame. A second mid-frame request
@@ -591,42 +593,7 @@ export class Game {
         return this.sceneProjection === 'isometric' ? unprojectIsometric(x, y) : { x, y };
     }
     dispatchCollisions() {
-        const boxed = this.entities.filter((e) => e.has(Hitbox));
-        for (let i = 0; i < boxed.length; i++) {
-            for (let j = i + 1; j < boxed.length; j++) {
-                const a = boxed[i];
-                const b = boxed[j];
-                if (!a?.alive || !b?.alive)
-                    continue;
-                const ha = a.get(Hitbox);
-                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,
-                });
-                if (!hit)
-                    continue;
-                for (const c of [...a.components])
-                    c.onCollide?.(b);
-                if (!a.alive || !b.alive)
-                    continue;
-                for (const c of [...b.components])
-                    c.onCollide?.(a);
-            }
-        }
+        dispatchHitboxCollisions(this);
     }
     resize() {
         const canvas = this.renderer.domElement;

package/dist/index.d.ts

@@ -50,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/spatial-broadphase.d.ts

@@ -0,0 +1,38 @@
+import { type CollisionBody, type CollisionBounds } from './collision-shape.js';
+import { Hitbox } from './components/hitbox.js';
+import { Solid } from './components/solid.js';
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+export interface SpatialBroadphaseSource<T> {
+    readonly value: T;
+    readonly order: number;
+    readonly body: CollisionBody;
+}
+export interface SpatialBroadphaseStats {
+    readonly indexed: number;
+    readonly overflow: number;
+}
+export interface SpatialBroadphase<T> {
+    readonly stats: SpatialBroadphaseStats;
+    candidates(bounds: CollisionBounds): T[];
+    pairs(): Array<readonly [T, T]>;
+}
+/**
+ * Package-internal fresh uniform grid. Bodies above the fixed occupancy cap
+ * remain in an overflow bucket and are conservatively visible everywhere.
+ */
+export declare function createSpatialBroadphase<T>(sources: readonly SpatialBroadphaseSource<T>[], cellSize: number, isIndexable?: (body: CollisionBody) => boolean): SpatialBroadphase<T>;
+/** Smallest current live Tilemap cell, or one logical unit. */
+export declare function broadphaseCellSize(game: Game): number;
+export interface HitboxBroadphaseCandidate {
+    readonly entity: Entity;
+    readonly hitbox: Hitbox;
+    readonly entityIndex: number;
+}
+export interface SolidBroadphaseCandidate {
+    readonly entity: Entity;
+    readonly solid: Solid;
+    readonly sourceIndex: number;
+}
+export declare function createHitboxBroadphase(game: Game): SpatialBroadphase<HitboxBroadphaseCandidate>;
+export declare function createSolidBroadphase(game: Game): SpatialBroadphase<SolidBroadphaseCandidate>;

package/dist/spatial-broadphase.js

@@ -0,0 +1,180 @@
+import { collisionBody } from './collision-body.js';
+import { collisionBounds, } from './collision-shape.js';
+import { Hitbox } from './components/hitbox.js';
+import { Solid } from './components/solid.js';
+import { Tilemap } from './components/tilemap.js';
+import { sceneSolids } from './scene-solids.js';
+import { usableCollisionBody } from './spatial-query-geometry.js';
+const CELL_OCCUPANCY_CAP = 256;
+function rangeSize(range) {
+    const width = range.maxX - range.minX + 1;
+    const height = range.maxY - range.minY + 1;
+    if (!Number.isSafeInteger(width) ||
+        !Number.isSafeInteger(height) ||
+        width <= 0 ||
+        height <= 0 ||
+        width > CELL_OCCUPANCY_CAP ||
+        height > CELL_OCCUPANCY_CAP ||
+        width * height > CELL_OCCUPANCY_CAP) {
+        return null;
+    }
+    return width * height;
+}
+function cellRange(bounds, cellSize) {
+    const left = Math.min(bounds.left, bounds.right);
+    const right = Math.max(bounds.left, bounds.right);
+    const bottom = Math.min(bounds.bottom, bounds.top);
+    const top = Math.max(bounds.bottom, bounds.top);
+    if (![left, right, bottom, top, cellSize].every(Number.isFinite) || cellSize <= 0) {
+        return null;
+    }
+    const range = {
+        minX: Math.floor(left / cellSize),
+        maxX: Math.floor(right / cellSize),
+        minY: Math.floor(bottom / cellSize),
+        maxY: Math.floor(top / cellSize),
+    };
+    if (!Object.values(range).every(Number.isSafeInteger))
+        return null;
+    return rangeSize(range) === null ? null : range;
+}
+function cellKey(x, y) {
+    return `${x}:${y}`;
+}
+function eachCell(range, visit) {
+    for (let x = range.minX; x <= range.maxX; x += 1) {
+        for (let y = range.minY; y <= range.maxY; y += 1)
+            visit(cellKey(x, y));
+    }
+}
+/**
+ * Package-internal fresh uniform grid. Bodies above the fixed occupancy cap
+ * remain in an overflow bucket and are conservatively visible everywhere.
+ */
+export function createSpatialBroadphase(sources, cellSize, isIndexable = usableCollisionBody) {
+    const entries = sources
+        .map((source, serial) => {
+        if (!isIndexable(source.body))
+            return null;
+        return {
+            ...source,
+            serial,
+            range: cellRange(collisionBounds(source.body), cellSize),
+        };
+    })
+        .filter((entry) => entry !== null)
+        .sort((a, b) => a.order - b.order || a.serial - b.serial);
+    const buckets = new Map();
+    const overflow = [];
+    for (const [index, entry] of entries.entries()) {
+        if (!entry.range) {
+            overflow.push(index);
+            continue;
+        }
+        eachCell(entry.range, (key) => {
+            const bucket = buckets.get(key);
+            if (bucket)
+                bucket.push(index);
+            else
+                buckets.set(key, [index]);
+        });
+    }
+    return {
+        stats: { indexed: entries.length - overflow.length, overflow: overflow.length },
+        candidates(bounds) {
+            const range = cellRange(bounds, cellSize);
+            if (!range)
+                return entries.map((entry) => entry.value);
+            const selected = new Set(overflow);
+            eachCell(range, (key) => {
+                for (const index of buckets.get(key) ?? [])
+                    selected.add(index);
+            });
+            return [...selected]
+                .sort((a, b) => a - b)
+                .map((index) => entries[index].value);
+        },
+        pairs() {
+            const pairKeys = new Set();
+            const width = entries.length;
+            const addPair = (left, right) => {
+                if (left === right)
+                    return;
+                const first = Math.min(left, right);
+                const second = Math.max(left, right);
+                pairKeys.add(first * width + second);
+            };
+            for (const bucket of buckets.values()) {
+                for (let left = 0; left < bucket.length; left += 1) {
+                    for (let right = left + 1; right < bucket.length; right += 1) {
+                        addPair(bucket[left], bucket[right]);
+                    }
+                }
+            }
+            for (const overflowIndex of overflow) {
+                for (let index = 0; index < entries.length; index += 1) {
+                    addPair(overflowIndex, index);
+                }
+            }
+            return [...pairKeys]
+                .map((key) => [Math.floor(key / width), key % width])
+                .sort(([a1, a2], [b1, b2]) => a1 - b1 || a2 - b2)
+                .map(([first, second]) => [
+                entries[first].value,
+                entries[second].value,
+            ]);
+        },
+    };
+}
+/** Smallest current live Tilemap cell, or one logical unit. */
+export function broadphaseCellSize(game) {
+    let result = Infinity;
+    for (const entity of [...game.entities]) {
+        if (!entity.alive)
+            continue;
+        const size = entity.get(Tilemap)?.cellSize;
+        if (typeof size === 'number' && Number.isFinite(size) && size > 0) {
+            result = Math.min(result, size);
+        }
+    }
+    return result === Infinity ? 1 : result;
+}
+export function createHitboxBroadphase(game) {
+    const sources = [];
+    for (const [entityIndex, entity] of [...game.entities].entries()) {
+        if (!entity.alive)
+            continue;
+        const hitbox = entity.get(Hitbox);
+        if (!hitbox)
+            continue;
+        sources.push({
+            value: { entity, hitbox, entityIndex },
+            order: entityIndex,
+            body: collisionBody(hitbox),
+        });
+    }
+    return createSpatialBroadphase(sources, broadphaseCellSize(game));
+}
+function rayIndexableBody(body) {
+    if (body.shape !== 'circle')
+        return usableCollisionBody(body);
+    return (Number.isFinite(body.x) &&
+        Number.isFinite(body.y) &&
+        Number.isFinite(body.width) &&
+        Number.isFinite(body.height) &&
+        body.width !== 0 &&
+        body.height !== 0);
+}
+export function createSolidBroadphase(game) {
+    const sources = [];
+    for (const [sourceIndex, solid] of [...sceneSolids(game)].entries()) {
+        if (!solid.entity.alive)
+            continue;
+        sources.push({
+            value: { entity: solid.entity, solid, sourceIndex },
+            order: sourceIndex,
+            body: collisionBody(solid),
+        });
+    }
+    return createSpatialBroadphase(sources, broadphaseCellSize(game), rayIndexableBody);
+}

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;

package/dist/spatial-query-geometry.js

@@ -0,0 +1,291 @@
+import { collisionVertices, } from './collision-shape.js';
+/** Internal absolute tolerance shared by point and ray boundary rules. */
+export const SPATIAL_QUERY_EPSILON = 1e-9;
+function signedArea(points) {
+    let twiceArea = 0;
+    for (let index = 0; index < points.length; index += 1) {
+        const point = points[index];
+        const next = points[(index + 1) % points.length];
+        twiceArea += point[0] * next[1] - next[0] * point[1];
+    }
+    return twiceArea / 2;
+}
+function finiteCollisionBody(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const body = value;
+    return (Number.isFinite(body.x) &&
+        Number.isFinite(body.y) &&
+        Number.isFinite(body.width) &&
+        Number.isFinite(body.height));
+}
+/** Valid finite geometry with a positive two-dimensional area. */
+export function usableCollisionBody(value) {
+    if (!finiteCollisionBody(value))
+        return false;
+    const vertices = collisionVertices(value);
+    return (vertices.length >= 3 &&
+        vertices.every(([x, y]) => Number.isFinite(x) && Number.isFinite(y)) &&
+        Math.abs(signedArea(vertices)) > SPATIAL_QUERY_EPSILON);
+}
+function cross(a, b, point) {
+    return (b[0] - a[0]) * (point[1] - a[1]) -
+        (b[1] - a[1]) * (point[0] - a[0]);
+}
+function vectorCross(a, b) {
+    return a[0] * b[1] - a[1] * b[0];
+}
+function pointOnSegment(point, a, b) {
+    if (Math.abs(cross(a, b, point)) > SPATIAL_QUERY_EPSILON)
+        return false;
+    return (point[0] >= Math.min(a[0], b[0]) - SPATIAL_QUERY_EPSILON &&
+        point[0] <= Math.max(a[0], b[0]) + SPATIAL_QUERY_EPSILON &&
+        point[1] >= Math.min(a[1], b[1]) - SPATIAL_QUERY_EPSILON &&
+        point[1] <= Math.max(a[1], b[1]) + SPATIAL_QUERY_EPSILON);
+}
+function polygonPointLocation(polygon, point) {
+    let inside = false;
+    for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index, index += 1) {
+        const a = polygon[index];
+        const b = polygon[previous];
+        if (pointOnSegment(point, a, b))
+            return 'boundary';
+        const crosses = (a[1] > point[1]) !== (b[1] > point[1]) &&
+            point[0] <
+                ((b[0] - a[0]) * (point[1] - a[1])) / (b[1] - a[1]) + a[0];
+        if (crosses)
+            inside = !inside;
+    }
+    return inside ? 'inside' : 'outside';
+}
+/** Strict containment in the existing collision outline. */
+export function collisionBodyContainsPoint(body, x, y) {
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !usableCollisionBody(body))
+        return false;
+    return polygonPointLocation(collisionVertices(body), [x, y]) === 'inside';
+}
+function snappedDistance(distance, maxDistance) {
+    if (Math.abs(distance) <= SPATIAL_QUERY_EPSILON)
+        return 0;
+    if (Math.abs(distance - maxDistance) <= SPATIAL_QUERY_EPSILON)
+        return maxDistance;
+    return distance;
+}
+function inRayRange(distance, maxDistance) {
+    return (distance >= -SPATIAL_QUERY_EPSILON &&
+        distance <= maxDistance + SPATIAL_QUERY_EPSILON);
+}
+function onForwardRay(distance) {
+    return Number.isFinite(distance) && distance >= -SPATIAL_QUERY_EPSILON;
+}
+function cleanUnitValue(value) {
+    return Math.abs(value) <= SPATIAL_QUERY_EPSILON ? 0 : value;
+}
+function edgeNormal(a, b, winding) {
+    const edgeX = b[0] - a[0];
+    const edgeY = b[1] - a[1];
+    const length = Math.hypot(edgeX, edgeY);
+    if (length <= SPATIAL_QUERY_EPSILON)
+        return null;
+    return [
+        cleanUnitValue((winding * edgeY) / length),
+        cleanUnitValue((-winding * edgeX) / length),
+    ];
+}
+function edgeEvents(origin, direction, maxDistance, a, b, normal, edgeOrder) {
+    const edge = [b[0] - a[0], b[1] - a[1]];
+    const relative = [a[0] - origin[0], a[1] - origin[1]];
+    const denominator = vectorCross(direction, edge);
+    if (Math.abs(denominator) <= SPATIAL_QUERY_EPSILON) {
+        if (Math.abs(vectorCross(relative, direction)) > SPATIAL_QUERY_EPSILON)
+            return [];
+        const result = [];
+        for (const vertex of [a, b]) {
+            const distance = (vertex[0] - origin[0]) * direction[0] +
+                (vertex[1] - origin[1]) * direction[1];
+            if (onForwardRay(distance)) {
+                result.push({
+                    distance: snappedDistance(distance, maxDistance),
+                    edgeOrder,
+                });
+            }
+        }
+        return result;
+    }
+    const distance = vectorCross(relative, edge) / denominator;
+    const edgeFraction = vectorCross(relative, direction) / denominator;
+    if (!onForwardRay(distance) ||
+        !Number.isFinite(edgeFraction) ||
+        edgeFraction < -SPATIAL_QUERY_EPSILON ||
+        edgeFraction > 1 + SPATIAL_QUERY_EPSILON) {
+        return [];
+    }
+    return [{
+            distance: snappedDistance(distance, maxDistance),
+            edgeOrder,
+            normal,
+        }];
+}
+function groupEvents(events) {
+    const sorted = [...events].sort((a, b) => a.distance === b.distance ? a.edgeOrder - b.edgeOrder : a.distance - b.distance);
+    const groups = [];
+    for (const event of sorted) {
+        const current = groups.at(-1);
+        if (!current || Math.abs(event.distance - current.distance) > SPATIAL_QUERY_EPSILON) {
+            groups.push({ distance: event.distance, normals: [] });
+        }
+        if (event.normal) {
+            groups.at(-1).normals.push({ edgeOrder: event.edgeOrder, normal: event.normal });
+        }
+    }
+    return groups.map((group) => ({
+        distance: group.distance,
+        normals: group.normals.sort((a, b) => a.edgeOrder - b.edgeOrder),
+    }));
+}
+function pointAlongRay(origin, direction, distance) {
+    return [
+        origin[0] + direction[0] * distance,
+        origin[1] + direction[1] * distance,
+    ];
+}
+function selectVertexNormal(normals, direction, crossing) {
+    const first = normals[0];
+    if (!first)
+        return null;
+    let selected = first.normal;
+    let selectedDot = selected[0] * direction[0] + selected[1] * direction[1];
+    for (const candidate of normals.slice(1)) {
+        const dot = candidate.normal[0] * direction[0] + candidate.normal[1] * direction[1];
+        const isBetter = crossing === 'entry'
+            ? dot < selectedDot - SPATIAL_QUERY_EPSILON
+            : dot > selectedDot + SPATIAL_QUERY_EPSILON;
+        if (isBetter) {
+            selected = candidate.normal;
+            selectedDot = dot;
+        }
+    }
+    return selected;
+}
+function polygonRay(body, origin, direction, maxDistance) {
+    const polygon = collisionVertices(body);
+    if (!polygon.every(([x, y]) => Number.isFinite(x) && Number.isFinite(y)))
+        return null;
+    const area = signedArea(polygon);
+    if (Math.abs(area) <= SPATIAL_QUERY_EPSILON)
+        return null;
+    const winding = area > 0 ? 1 : -1;
+    const events = [];
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = polygon[index];
+        const b = polygon[(index + 1) % polygon.length];
+        const normal = edgeNormal(a, b, winding);
+        if (!normal)
+            continue;
+        events.push(...edgeEvents(origin, direction, maxDistance, a, b, normal, index));
+    }
+    const groups = groupEvents(events);
+    const originLocation = polygonPointLocation(polygon, origin);
+    const scale = Math.max(Math.abs(body.width), Math.abs(body.height), 1);
+    const terminalProbe = Math.max(SPATIAL_QUERY_EPSILON * 4, Math.min(scale * 1e-6, 1e-3));
+    for (let index = 0; index < groups.length; index += 1) {
+        const group = groups[index];
+        if (group.distance > maxDistance + SPATIAL_QUERY_EPSILON)
+            break;
+        const previous = groups[index - 1];
+        const next = groups[index + 1];
+        const beforeLocation = group.distance === 0
+            ? originLocation
+            : polygonPointLocation(polygon, pointAlongRay(origin, direction, previous ? (previous.distance + group.distance) / 2 : group.distance / 2));
+        const afterLocation = polygonPointLocation(polygon, pointAlongRay(origin, direction, next ? (group.distance + next.distance) / 2 : group.distance + terminalProbe));
+        let crossing = null;
+        if ((beforeLocation === 'outside' ||
+            (group.distance === 0 && beforeLocation === 'boundary')) &&
+            afterLocation === 'inside') {
+            crossing = 'entry';
+        }
+        else if (beforeLocation === 'inside' && afterLocation === 'outside') {
+            crossing = 'exit';
+        }
+        if (!crossing)
+            continue;
+        const normal = selectVertexNormal(group.normals, direction, crossing);
+        if (!normal)
+            continue;
+        const point = pointAlongRay(origin, direction, group.distance);
+        return {
+            distance: group.distance,
+            point: { x: point[0], y: point[1] },
+            normal: { x: normal[0], y: normal[1] },
+        };
+    }
+    return null;
+}
+function ellipseNormal(body, radiusX, radiusY, point) {
+    const gradientX = ((point[0] - body.x) / radiusX) / radiusX;
+    const gradientY = ((point[1] - body.y) / radiusY) / radiusY;
+    const length = Math.hypot(gradientX, gradientY);
+    if (!Number.isFinite(length) || length === 0)
+        return null;
+    return [cleanUnitValue(gradientX / length), cleanUnitValue(gradientY / length)];
+}
+function ellipseRay(body, origin, direction, maxDistance) {
+    const radiusX = Math.abs(body.width) / 2;
+    const radiusY = Math.abs(body.height) / 2;
+    if (radiusX === 0 || radiusY === 0)
+        return null;
+    const originX = (origin[0] - body.x) / radiusX;
+    const originY = (origin[1] - body.y) / radiusY;
+    const directionX = direction[0] / radiusX;
+    const directionY = direction[1] / radiusY;
+    const directionScale = Math.max(Math.abs(directionX), Math.abs(directionY));
+    if (![originX, originY, directionX, directionY, directionScale].every(Number.isFinite) ||
+        directionScale === 0) {
+        return null;
+    }
+    const scaledDirectionX = directionX / directionScale;
+    const scaledDirectionY = directionY / directionScale;
+    const directionLengthSquared = scaledDirectionX * scaledDirectionX + scaledDirectionY * scaledDirectionY;
+    const closestParameter = -(originX * scaledDirectionX + originY * scaledDirectionY) / directionLengthSquared;
+    const perpendicular = originX * scaledDirectionY - originY * scaledDirectionX;
+    const radialGap = 1 - (perpendicular * perpendicular) / directionLengthSquared;
+    if (!Number.isFinite(closestParameter) || radialGap <= 0)
+        return null;
+    const halfChordParameter = Math.sqrt(radialGap / directionLengthSquared);
+    const halfChordDistance = halfChordParameter / directionScale;
+    if (!Number.isFinite(halfChordParameter) ||
+        halfChordDistance <= SPATIAL_QUERY_EPSILON) {
+        return null;
+    }
+    const roots = [
+        (closestParameter - halfChordParameter) / directionScale,
+        (closestParameter + halfChordParameter) / directionScale,
+    ];
+    const rawDistance = roots[0] >= -SPATIAL_QUERY_EPSILON
+        ? roots[0]
+        : roots[1] > SPATIAL_QUERY_EPSILON
+            ? roots[1]
+            : undefined;
+    if (rawDistance === undefined || !inRayRange(rawDistance, maxDistance))
+        return null;
+    const distance = snappedDistance(rawDistance, maxDistance);
+    const point = pointAlongRay(origin, direction, distance);
+    const normal = ellipseNormal(body, radiusX, radiusY, point);
+    if (!normal)
+        return null;
+    return {
+        distance,
+        point: { x: point[0], y: point[1] },
+        normal: { x: normal[0], y: normal[1] },
+    };
+}
+/** First strict crossing against one resolved body. Direction must be normalized. */
+export function collisionBodyRay(body, x, y, dx, dy, maxDistance) {
+    if (!finiteCollisionBody(body))
+        return null;
+    const origin = [x, y];
+    const direction = [dx, dy];
+    return body.shape === 'circle'
+        ? ellipseRay(body, origin, direction, maxDistance)
+        : polygonRay(body, origin, direction, maxDistance);
+}

package/dist/spatial-query.d.ts

@@ -0,0 +1,96 @@
+import { type CollisionBody, type CollisionBounds } from './collision-shape.js';
+import type { Component, ComponentClass } from './component.js';
+import { Hitbox } from './components/hitbox.js';
+import { Solid } from './components/solid.js';
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+type ComponentClasses = readonly ComponentClass[];
+type QueryEntity<Classes extends ComponentClasses> = Classes extends readonly [] ? Entity : EntityWith<Classes>;
+/** An Entity whose required component classes return non-optional instances. */
+export interface EntityWith<Classes extends ComponentClasses> extends Entity {
+    get<Class extends Classes[number]>(component: Class): InstanceType<Class>;
+    get<T extends Component>(component: ComponentClass<T>): T | undefined;
+}
+/** Declarative eligibility shared by area, point, and ray queries. */
+export interface SpatialQueryFilter<Classes extends ComponentClasses = readonly []> {
+    /** Every listed component class must be present. */
+    with?: Classes;
+    /** A candidate carrying any listed class is rejected. */
+    without?: readonly ComponentClass[];
+    /** Entity identities omitted from the result. */
+    exclude?: Entity | readonly Entity[] | ReadonlySet<Entity>;
+    /** Final eligibility predicate. */
+    where?: (entity: QueryEntity<Classes>) => boolean;
+}
+export interface NearestQueryContext {
+    readonly distance: number;
+}
+/** Entity eligibility plus an optional inclusive logical-space radius. */
+export interface NearestSpatialQueryFilter<Classes extends ComponentClasses = readonly []> {
+    with?: Classes;
+    without?: readonly ComponentClass[];
+    exclude?: Entity | readonly Entity[] | ReadonlySet<Entity>;
+    where?: (entity: QueryEntity<Classes>, context: NearestQueryContext) => boolean;
+    /** Inclusive logical-space radius; omitted or positive Infinity is unlimited. */
+    maxDistance?: number;
+}
+/** One query-time crossing paired with the live Solid and owning Entity. */
+export interface RayHit<T extends Entity = Entity> {
+    readonly entity: T;
+    readonly solid: Solid;
+    readonly distance: number;
+    readonly point: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    readonly normal: Readonly<{
+        x: number;
+        y: number;
+    }>;
+}
+type SpatialGuardFilter<Classes extends ComponentClasses, Narrowed extends QueryEntity<Classes>> = Omit<SpatialQueryFilter<Classes>, 'where'> & {
+    where: (entity: QueryEntity<Classes>) => entity is Narrowed;
+};
+type NearestGuardFilter<Classes extends ComponentClasses, Narrowed extends QueryEntity<Classes>> = Omit<NearestSpatialQueryFilter<Classes>, 'where'> & {
+    where: (entity: QueryEntity<Classes>, context: NearestQueryContext) => entity is Narrowed;
+};
+/** Public logical-space spatial-query service owned by every Game. */
+export interface SpatialQuery {
+    /** Hitbox owners with positive interior overlap, mask-agnostic and in Entity order. */
+    area<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(body: CollisionBody, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
+    area<Classes extends ComponentClasses = readonly []>(body: CollisionBody, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
+    area(body: CollisionBody, filter?: SpatialQueryFilter): Entity[];
+    /** Hitbox owners that strictly contain a point, mask-agnostic and in Entity order. */
+    point<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
+    point<Classes extends ComponentClasses = readonly []>(x: number, y: number, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
+    point(x: number, y: number, filter?: SpatialQueryFilter): Entity[];
+    /** Closest filtered logical transform; equal distances retain Entity order. */
+    nearest<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, filter: NearestGuardFilter<Classes, Narrowed>): Narrowed | null;
+    nearest<Classes extends ComponentClasses = readonly []>(x: number, y: number, filter: NearestSpatialQueryFilter<Classes>): QueryEntity<Classes> | null;
+    nearest(x: number, y: number, filter?: NearestSpatialQueryFilter): Entity | null;
+    /** First strict crossing of direct or source-derived Solid geometry. */
+    ray<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, dx: number, dy: number, maxDistance: number, filter: SpatialGuardFilter<Classes, Narrowed>): RayHit<Narrowed> | null;
+    ray<Classes extends ComponentClasses = readonly []>(x: number, y: number, dx: number, dy: number, maxDistance: number, filter: SpatialQueryFilter<Classes>): RayHit<QueryEntity<Classes>> | null;
+    ray(x: number, y: number, dx: number, dy: number, maxDistance: number, filter?: SpatialQueryFilter): RayHit | null;
+}
+export interface HitboxCandidate {
+    readonly entity: Entity;
+    readonly hitbox: Hitbox;
+}
+export interface SolidCandidate {
+    readonly entity: Entity;
+    readonly solid: Solid;
+}
+/** Package-internal candidate boundary used by the Game-owned broadphase. */
+export interface SpatialQueryCandidateProviders {
+    hitboxes(bounds: CollisionBounds): readonly HitboxCandidate[];
+    transforms(): readonly Entity[];
+    solids(bounds: CollisionBounds): readonly SolidCandidate[];
+}
+/** Package-internal deterministic candidate-count seam for tests. */
+export interface SpatialQueryInstrumentation {
+    onCandidates(domain: 'hitbox' | 'solid', count: number): void;
+}
+/** Package-internal constructor; only the SpatialQuery interface is public. */
+export declare function createSpatialQuery(game: Game, candidates?: SpatialQueryCandidateProviders, instrumentation?: SpatialQueryInstrumentation): SpatialQuery;
+export {};

package/dist/spatial-query.js

@@ -0,0 +1,168 @@
+import { collisionBody } from './collision-body.js';
+import { collisionBounds, collisionOverlap, } from './collision-shape.js';
+import { Hitbox } from './components/hitbox.js';
+import { Solid } from './components/solid.js';
+import { createHitboxBroadphase, createSolidBroadphase, } from './spatial-broadphase.js';
+import { collisionBodyContainsPoint, collisionBodyRay, SPATIAL_QUERY_EPSILON, usableCollisionBody, } from './spatial-query-geometry.js';
+function indexedCandidateProviders(game) {
+    return {
+        hitboxes(bounds) {
+            return createHitboxBroadphase(game).candidates(bounds);
+        },
+        transforms() {
+            return [...game.entities].filter((entity) => entity.alive);
+        },
+        solids(bounds) {
+            return createSolidBroadphase(game).candidates(bounds);
+        },
+    };
+}
+function isReadonlyEntitySet(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (typeof candidate.size === 'number' &&
+        typeof candidate.has === 'function' &&
+        typeof candidate[Symbol.iterator] === 'function');
+}
+function isExcluded(entity, exclude) {
+    if (!exclude)
+        return false;
+    if (Array.isArray(exclude))
+        return exclude.includes(entity);
+    if (isReadonlyEntitySet(exclude))
+        return exclude.has(entity);
+    return exclude === entity;
+}
+function matchesCommonFilter(entity, filter) {
+    if (!filter)
+        return true;
+    if (filter.with?.some((component) => !entity.has(component)))
+        return false;
+    if (filter.without?.some((component) => entity.has(component)))
+        return false;
+    return !isExcluded(entity, filter.exclude);
+}
+function matchesFilter(entity, filter) {
+    return (matchesCommonFilter(entity, filter) &&
+        (!filter?.where || filter.where(entity)));
+}
+class LinearSpatialQuery {
+    candidates;
+    instrumentation;
+    constructor(candidates, instrumentation) {
+        this.candidates = candidates;
+        this.instrumentation = instrumentation;
+    }
+    area(body, filter) {
+        if (!usableCollisionBody(body))
+            return [];
+        const candidates = [...this.candidates.hitboxes(collisionBounds(body))].filter(({ entity }) => entity.alive);
+        this.instrumentation?.onCandidates('hitbox', candidates.length);
+        const result = [];
+        for (const { entity, hitbox } of candidates) {
+            if (!matchesFilter(entity, filter))
+                continue;
+            const candidateBody = collisionBody(hitbox);
+            if (usableCollisionBody(candidateBody) && collisionOverlap(body, candidateBody)) {
+                result.push(entity);
+            }
+        }
+        return result;
+    }
+    point(x, y, filter) {
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            return [];
+        const candidates = [
+            ...this.candidates.hitboxes({ left: x, right: x, bottom: y, top: y }),
+        ].filter(({ entity }) => entity.alive);
+        this.instrumentation?.onCandidates('hitbox', candidates.length);
+        const result = [];
+        for (const { entity, hitbox } of candidates) {
+            if (!matchesFilter(entity, filter))
+                continue;
+            if (collisionBodyContainsPoint(collisionBody(hitbox), x, y))
+                result.push(entity);
+        }
+        return result;
+    }
+    nearest(x, y, filter) {
+        const maxDistance = filter?.maxDistance ?? Infinity;
+        if (!Number.isFinite(x) ||
+            !Number.isFinite(y) ||
+            Number.isNaN(maxDistance) ||
+            maxDistance < 0 ||
+            (maxDistance !== Infinity && !Number.isFinite(maxDistance))) {
+            return null;
+        }
+        const candidates = [...this.candidates.transforms()].filter((entity) => entity.alive);
+        let result = null;
+        let nearestDistance = Infinity;
+        for (const entity of candidates) {
+            if (!matchesCommonFilter(entity, filter))
+                continue;
+            const distance = Math.hypot(entity.position.x - x, entity.position.y - y);
+            if (Number.isNaN(distance) || distance > maxDistance)
+                continue;
+            if (filter?.where &&
+                !filter.where(entity, { distance })) {
+                continue;
+            }
+            if (result === null || distance < nearestDistance) {
+                result = entity;
+                nearestDistance = distance;
+            }
+        }
+        return result;
+    }
+    ray(x, y, dx, dy, maxDistance, filter) {
+        const directionScale = Math.max(Math.abs(dx), Math.abs(dy));
+        if (!Number.isFinite(x) ||
+            !Number.isFinite(y) ||
+            !Number.isFinite(dx) ||
+            !Number.isFinite(dy) ||
+            !Number.isFinite(maxDistance) ||
+            directionScale === 0 ||
+            maxDistance < 0) {
+            return null;
+        }
+        const scaledX = dx / directionScale;
+        const scaledY = dy / directionScale;
+        const scaledLength = Math.hypot(scaledX, scaledY);
+        const unitX = scaledX / scaledLength;
+        const unitY = scaledY / scaledLength;
+        const endX = x + unitX * maxDistance;
+        const endY = y + unitY * maxDistance;
+        const candidates = [
+            ...this.candidates.solids({
+                left: Math.min(x, endX) - SPATIAL_QUERY_EPSILON,
+                right: Math.max(x, endX) + SPATIAL_QUERY_EPSILON,
+                bottom: Math.min(y, endY) - SPATIAL_QUERY_EPSILON,
+                top: Math.max(y, endY) + SPATIAL_QUERY_EPSILON,
+            }),
+        ].filter(({ entity }) => entity.alive);
+        this.instrumentation?.onCandidates('solid', candidates.length);
+        let result = null;
+        for (const { entity, solid } of candidates) {
+            if (!matchesFilter(entity, filter))
+                continue;
+            const hit = collisionBodyRay(collisionBody(solid), x, y, unitX, unitY, maxDistance);
+            if (!hit)
+                continue;
+            if (result && hit.distance >= result.distance - SPATIAL_QUERY_EPSILON)
+                continue;
+            result = {
+                entity,
+                solid,
+                distance: hit.distance,
+                point: { x: hit.point.x, y: hit.point.y },
+                normal: { x: hit.normal.x, y: hit.normal.y },
+            };
+        }
+        return result;
+    }
+}
+/** Package-internal constructor; only the SpatialQuery interface is public. */
+export function createSpatialQuery(game, candidates = indexedCandidateProviders(game), instrumentation) {
+    return new LinearSpatialQuery(candidates, instrumentation);
+}

package/package.json

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