@waica/engine 0.14.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/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/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;

package/dist/game.js

@@ -1,5 +1,6 @@
 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';
@@ -14,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';
 /**
@@ -25,6 +27,7 @@ export class Game {
     camera;
     input;
     pointer;
+    query;
     entities = [];
     events = new Emitter();
     stats;
@@ -81,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({
@@ -602,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

@@ -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-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,92 @@
+import { type CollisionBody } 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, 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 logical point, 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 reserved for future acceleration. */
+export interface SpatialQueryCandidateProviders {
+    hitboxes(): readonly HitboxCandidate[];
+    transforms(): readonly Entity[];
+    solids(): readonly SolidCandidate[];
+}
+/** Package-internal constructor; only the SpatialQuery interface is public. */
+export declare function createSpatialQuery(game: Game, candidates?: SpatialQueryCandidateProviders): SpatialQuery;
+export {};

package/dist/spatial-query.js

@@ -0,0 +1,162 @@
+import { collisionBody } from './collision-body.js';
+import { collisionOverlap } from './collision-shape.js';
+import { Hitbox } from './components/hitbox.js';
+import { Solid } from './components/solid.js';
+import { sceneSolids } from './scene-solids.js';
+import { collisionBodyContainsPoint, collisionBodyRay, SPATIAL_QUERY_EPSILON, usableCollisionBody, } from './spatial-query-geometry.js';
+function linearCandidateProviders(game) {
+    return {
+        hitboxes() {
+            const result = [];
+            for (const entity of [...game.entities]) {
+                if (!entity.alive)
+                    continue;
+                const hitbox = entity.get(Hitbox);
+                if (hitbox)
+                    result.push({ entity, hitbox });
+            }
+            return result;
+        },
+        transforms() {
+            return [...game.entities].filter((entity) => entity.alive);
+        },
+        solids() {
+            return sceneSolids(game)
+                .filter((solid) => solid.entity.alive)
+                .map((solid) => ({ entity: solid.entity, solid }));
+        },
+    };
+}
+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;
+    constructor(candidates) {
+        this.candidates = candidates;
+    }
+    area(body, filter) {
+        if (!usableCollisionBody(body))
+            return [];
+        const candidates = [...this.candidates.hitboxes()].filter(({ entity }) => entity.alive);
+        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()].filter(({ entity }) => entity.alive);
+        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 candidates = [...this.candidates.solids()].filter(({ entity }) => entity.alive);
+        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 = linearCandidateProviders(game)) {
+    return new LinearSpatialQuery(candidates);
+}

package/package.json

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