@waica/engine 0.14.1 → 0.15.0

package/README.md

@@ -6,6 +6,52 @@ 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:
@@ -45,7 +91,7 @@ Calls eagerly snapshot candidates that are alive at call start. Results preserve
 
 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.
+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
 

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

@@ -49,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.
@@ -137,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,10 +1,8 @@
 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 { 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';
@@ -181,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
@@ -595,28 +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(collisionBody(ha), collisionBody(hb));
-                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/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.d.ts

@@ -1,4 +1,4 @@
-import { type CollisionBody } from './collision-shape.js';
+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';
@@ -56,11 +56,11 @@ type NearestGuardFilter<Classes extends ComponentClasses, Narrowed extends Query
 };
 /** Public logical-space spatial-query service owned by every Game. */
 export interface SpatialQuery {
-    /** Hitbox owners with positive interior overlap, in Entity order. */
+    /** 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 logical point, in Entity order. */
+    /** 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[];
@@ -81,12 +81,16 @@ export interface SolidCandidate {
     readonly entity: Entity;
     readonly solid: Solid;
 }
-/** Package-internal candidate boundary reserved for future acceleration. */
+/** Package-internal candidate boundary used by the Game-owned broadphase. */
 export interface SpatialQueryCandidateProviders {
-    hitboxes(): readonly HitboxCandidate[];
+    hitboxes(bounds: CollisionBounds): readonly HitboxCandidate[];
     transforms(): readonly Entity[];
-    solids(): readonly SolidCandidate[];
+    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): SpatialQuery;
+export declare function createSpatialQuery(game: Game, candidates?: SpatialQueryCandidateProviders, instrumentation?: SpatialQueryInstrumentation): SpatialQuery;
 export {};

package/dist/spatial-query.js

@@ -1,29 +1,19 @@
 import { collisionBody } from './collision-body.js';
-import { collisionOverlap } from './collision-shape.js';
+import { collisionBounds, collisionOverlap, } from './collision-shape.js';
 import { Hitbox } from './components/hitbox.js';
 import { Solid } from './components/solid.js';
-import { sceneSolids } from './scene-solids.js';
+import { createHitboxBroadphase, createSolidBroadphase, } from './spatial-broadphase.js';
 import { collisionBodyContainsPoint, collisionBodyRay, SPATIAL_QUERY_EPSILON, usableCollisionBody, } from './spatial-query-geometry.js';
-function linearCandidateProviders(game) {
+function indexedCandidateProviders(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;
+        hitboxes(bounds) {
+            return createHitboxBroadphase(game).candidates(bounds);
         },
         transforms() {
             return [...game.entities].filter((entity) => entity.alive);
         },
-        solids() {
-            return sceneSolids(game)
-                .filter((solid) => solid.entity.alive)
-                .map((solid) => ({ entity: solid.entity, solid }));
+        solids(bounds) {
+            return createSolidBroadphase(game).candidates(bounds);
         },
     };
 }
@@ -59,13 +49,16 @@ function matchesFilter(entity, filter) {
 }
 class LinearSpatialQuery {
     candidates;
-    constructor(candidates) {
+    instrumentation;
+    constructor(candidates, instrumentation) {
         this.candidates = candidates;
+        this.instrumentation = instrumentation;
     }
     area(body, filter) {
         if (!usableCollisionBody(body))
             return [];
-        const candidates = [...this.candidates.hitboxes()].filter(({ entity }) => entity.alive);
+        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))
@@ -80,7 +73,10 @@ class LinearSpatialQuery {
     point(x, y, filter) {
         if (!Number.isFinite(x) || !Number.isFinite(y))
             return [];
-        const candidates = [...this.candidates.hitboxes()].filter(({ entity }) => entity.alive);
+        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))
@@ -135,7 +131,17 @@ class LinearSpatialQuery {
         const scaledLength = Math.hypot(scaledX, scaledY);
         const unitX = scaledX / scaledLength;
         const unitY = scaledY / scaledLength;
-        const candidates = [...this.candidates.solids()].filter(({ entity }) => entity.alive);
+        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))
@@ -157,6 +163,6 @@ class LinearSpatialQuery {
     }
 }
 /** Package-internal constructor; only the SpatialQuery interface is public. */
-export function createSpatialQuery(game, candidates = linearCandidateProviders(game)) {
-    return new LinearSpatialQuery(candidates);
+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.1",
+  "version": "0.15.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",