@waica/engine 0.14.1 → 0.16.0

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.16.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",