ecspresso 0.16.1 → 0.16.3

package/dist/utils/spatial-hash.d.ts

@@ -10,14 +10,40 @@ export interface SpatialEntry {
     y: number;
     halfW: number;
     halfH: number;
+    /** Generation stamp used by query functions to dedup multi-cell hits without a Set. Internal. */
+    _lastSeenGen: number;
+    /** Rebuild generation when this entry was last inserted. Internal. */
+    _aliveGen: number;
+}
+/**
+ * A cell bucket — entries plus the alive-gen at which the bucket was last
+ * filled. Buckets are reset lazily on the next insert in a new generation
+ * (see `insertEntity`); queries skip buckets whose `_gen` is stale.
+ *
+ * Internal — exposed only through `SpatialHashGrid.cells`.
+ */
+interface CellBucket extends Array<SpatialEntry> {
+    _gen: number;
 }
 export interface SpatialHashGrid {
     cellSize: number;
     invCellSize: number;
-    cells: Map<number, number[]>;
-    entries: Map<number, SpatialEntry>;
-    /** Previous-frame entries held for in-place reuse during rebuild. Internal. */
-    _entriesPrev: Map<number, SpatialEntry>;
+    cells: Map<number, CellBucket>;
+    /**
+     * Dense, indexed by entityId. Holes are `undefined`. Entries from previous
+     * rebuilds remain in place for in-place reuse (zero allocation in steady
+     * state); liveness is determined by `entry._aliveGen === grid._aliveGen`.
+     * Internal — read live entries via `getEntry` / `liveEntryCount` helpers.
+     *
+     * High-water-mark grows with max entityId ever inserted; despawned ids
+     * leave their slot occupied by a stale entry. Acceptable when the entity
+     * manager recycles ids or peak count is bounded.
+     */
+    entries: (SpatialEntry | undefined)[];
+    /** Monotonic counter bumped by each `clearGrid` call. Internal. */
+    _aliveGen: number;
+    /** Monotonic counter bumped on each query; entries record their last-seen gen for O(1) dedup. Internal. */
+    _queryGen: number;
 }
 /**
  * Hash a cell coordinate pair to a single integer key.
@@ -31,13 +57,15 @@ export declare function createGrid(cellSize: number): SpatialHashGrid;
 /**
  * Prepare the grid for a rebuild.
  *
- * Swaps `entries` with `_entriesPrev` so `insertEntity` can reuse existing
- * `SpatialEntry` objects in place (steady-state rebuilds allocate zero
- * entries). Any stale entries left in `_entriesPrev` from the previous
- * rebuild are dropped here.
+ * O(1): bumps the alive-generation counter so entries inserted prior to this
+ * call are implicitly stale. `getLiveEntry` / `liveEntryCount` filter
+ * entries by the current gen; queries skip buckets whose own `_gen` lags
+ * behind the alive gen; `insertEntity` resets a bucket's `length` lazily
+ * the first time it is touched in a new generation.
  *
- * Cell buckets are cleared in place — keys are retained so subsequent
- * inserts hit the existing array rather than allocating a fresh one.
+ * Existing `SpatialEntry` objects and `CellBucket` arrays remain in place
+ * for reuse, so steady-state rebuilds allocate zero entries and zero
+ * buckets, regardless of how many cells have ever been touched.
  */
 export declare function clearGrid(grid: SpatialHashGrid): void;
 /**
@@ -46,18 +74,37 @@ export declare function clearGrid(grid: SpatialHashGrid): void;
 export declare function insertEntity(grid: SpatialHashGrid, entityId: number, x: number, y: number, halfW: number, halfH: number): void;
 /**
  * Collect entity IDs from all cells overlapping the given rectangle.
+ *
+ * Appends to `result` (caller clears/truncates first if reusing). Multi-cell
+ * entries are deduplicated via a per-grid generation stamp on each
+ * `SpatialEntry`.
+ *
+ * When `minId` is provided, only entries with `entityId > minId` are added —
+ * used for symmetric broadphase pair generation.
+ */
+export declare function gridQueryRect(grid: SpatialHashGrid, minX: number, minY: number, maxX: number, maxY: number, result: number[], minId?: number): void;
+/**
+ * Collect entity IDs within a circle. AABB-to-point distance filter against
+ * the cells overlapping the circle's bounding rect. Appends to `result`.
+ */
+export declare function gridQueryRadius(grid: SpatialHashGrid, cx: number, cy: number, radius: number, result: number[]): void;
+/**
+ * Get the current-generation entry for an entityId, or `undefined` if the
+ * entity isn't in the index for this rebuild. Stale entries from previous
+ * rebuilds remain in `entries` for in-place reuse but are filtered here.
  */
-export declare function gridQueryRect(grid: SpatialHashGrid, minX: number, minY: number, maxX: number, maxY: number, result: Set<number>): void;
+export declare function getLiveEntry(grid: SpatialHashGrid, entityId: number): SpatialEntry | undefined;
 /**
- * Collect entity IDs within a circle. Uses rect broadphase then
- * AABB-to-point distance filter.
+ * Count entries inserted in the current rebuild generation. Linear scan —
+ * intended for tests and diagnostics, not hot paths.
  */
-export declare function gridQueryRadius(grid: SpatialHashGrid, cx: number, cy: number, radius: number, result: Set<number>): void;
+export declare function liveEntryCount(grid: SpatialHashGrid): number;
 export interface SpatialIndex {
     readonly grid: SpatialHashGrid;
     queryRect(minX: number, minY: number, maxX: number, maxY: number): number[];
-    queryRectInto(minX: number, minY: number, maxX: number, maxY: number, result: Set<number>): void;
+    queryRectInto(minX: number, minY: number, maxX: number, maxY: number, result: number[], minId?: number): void;
     queryRadius(cx: number, cy: number, radius: number): number[];
-    queryRadiusInto(cx: number, cy: number, radius: number, result: Set<number>): void;
+    queryRadiusInto(cx: number, cy: number, radius: number, result: number[]): void;
     getEntry(entityId: number): SpatialEntry | undefined;
 }
+export {};

package/dist/utils/spatial-hash3D.d.ts

@@ -12,14 +12,40 @@ export interface SpatialEntry3D {
     halfW: number;
     halfH: number;
     halfD: number;
+    /** Generation stamp used by query functions to dedup multi-cell hits without a Set. Internal. */
+    _lastSeenGen: number;
+    /** Rebuild generation when this entry was last inserted. Internal. */
+    _aliveGen: number;
+}
+/**
+ * A cell bucket — entries plus the alive-gen at which the bucket was last
+ * filled. Buckets are reset lazily on the next insert in a new generation
+ * (see `insertEntity3D`); queries skip buckets whose `_gen` is stale.
+ *
+ * Internal — exposed only through `SpatialHashGrid3D.cells`.
+ */
+interface CellBucket3D extends Array<SpatialEntry3D> {
+    _gen: number;
 }
 export interface SpatialHashGrid3D {
     cellSize: number;
     invCellSize: number;
-    cells: Map<number, number[]>;
-    entries: Map<number, SpatialEntry3D>;
-    /** Previous-frame entries held for in-place reuse during rebuild. Internal. */
-    _entriesPrev: Map<number, SpatialEntry3D>;
+    cells: Map<number, CellBucket3D>;
+    /**
+     * Dense, indexed by entityId. Holes are `undefined`. Entries from previous
+     * rebuilds remain in place for in-place reuse (zero allocation in steady
+     * state); liveness is determined by `entry._aliveGen === grid._aliveGen`.
+     * Internal — read live entries via `getLiveEntry3D` / `liveEntryCount3D` helpers.
+     *
+     * High-water-mark grows with max entityId ever inserted; despawned ids
+     * leave their slot occupied by a stale entry. Acceptable when the entity
+     * manager recycles ids or peak count is bounded.
+     */
+    entries: (SpatialEntry3D | undefined)[];
+    /** Monotonic counter bumped by each `clearGrid3D` call. Internal. */
+    _aliveGen: number;
+    /** Monotonic counter bumped on each query; entries record their last-seen gen for O(1) dedup. Internal. */
+    _queryGen: number;
 }
 /**
  * Hash a cell coordinate triple to a single integer key.
@@ -33,13 +59,15 @@ export declare function createGrid3D(cellSize: number): SpatialHashGrid3D;
 /**
  * Prepare the grid for a rebuild.
  *
- * Swaps `entries` with `_entriesPrev` so `insertEntity3D` can reuse existing
- * `SpatialEntry3D` objects in place (steady-state rebuilds allocate zero
- * entries). Any stale entries left in `_entriesPrev` from the previous
- * rebuild are dropped here.
+ * O(1): bumps the alive-generation counter so entries inserted prior to this
+ * call are implicitly stale. `getLiveEntry3D` / `liveEntryCount3D` filter
+ * entries by the current gen; queries skip buckets whose own `_gen` lags
+ * behind the alive gen; `insertEntity3D` resets a bucket's `length` lazily
+ * the first time it is touched in a new generation.
  *
- * Cell buckets are cleared in place — keys are retained so subsequent
- * inserts hit the existing array rather than allocating a fresh one.
+ * Existing `SpatialEntry3D` objects and `CellBucket3D` arrays remain in
+ * place for reuse, so steady-state rebuilds allocate zero entries and zero
+ * buckets, regardless of how many cells have ever been touched.
  */
 export declare function clearGrid3D(grid: SpatialHashGrid3D): void;
 /**
@@ -48,13 +76,31 @@ export declare function clearGrid3D(grid: SpatialHashGrid3D): void;
 export declare function insertEntity3D(grid: SpatialHashGrid3D, entityId: number, x: number, y: number, z: number, halfW: number, halfH: number, halfD: number): void;
 /**
  * Collect entity IDs from all cells overlapping the given 3D box.
+ *
+ * Appends to `result` (caller clears/truncates first if reusing). Multi-cell
+ * entries are deduplicated via a per-grid generation stamp on each
+ * `SpatialEntry3D`.
+ *
+ * When `minId` is provided, only entries with `entityId > minId` are added —
+ * used for symmetric broadphase pair generation.
+ */
+export declare function gridQueryBox3D(grid: SpatialHashGrid3D, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, result: number[], minId?: number): void;
+/**
+ * Collect entity IDs within a sphere. AABB-to-point distance filter against
+ * the cells overlapping the sphere's bounding box. Appends to `result`.
+ */
+export declare function gridQueryRadius3D(grid: SpatialHashGrid3D, cx: number, cy: number, cz: number, radius: number, result: number[]): void;
+/**
+ * Get the current-generation entry for an entityId, or `undefined` if the
+ * entity isn't in the index for this rebuild. Stale entries from previous
+ * rebuilds remain in `entries` for in-place reuse but are filtered here.
  */
-export declare function gridQueryBox3D(grid: SpatialHashGrid3D, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, result: Set<number>): void;
+export declare function getLiveEntry3D(grid: SpatialHashGrid3D, entityId: number): SpatialEntry3D | undefined;
 /**
- * Collect entity IDs within a sphere. Uses box broadphase then
- * 3D AABB-to-point distance filter.
+ * Count entries inserted in the current rebuild generation. Linear scan —
+ * intended for tests and diagnostics, not hot paths.
  */
-export declare function gridQueryRadius3D(grid: SpatialHashGrid3D, cx: number, cy: number, cz: number, radius: number, result: Set<number>): void;
+export declare function liveEntryCount3D(grid: SpatialHashGrid3D): number;
 /**
  * High-level spatial index API for 3D broadphase queries.
  *
@@ -65,8 +111,9 @@ export declare function gridQueryRadius3D(grid: SpatialHashGrid3D, cx: number, c
 export interface SpatialIndex3D {
     readonly grid: SpatialHashGrid3D;
     queryBox(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number[];
-    queryBoxInto(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, result: Set<number>): void;
+    queryBoxInto(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, result: number[], minId?: number): void;
     queryRadius(cx: number, cy: number, cz: number, radius: number): number[];
-    queryRadiusInto(cx: number, cy: number, cz: number, radius: number, result: Set<number>): void;
+    queryRadiusInto(cx: number, cy: number, cz: number, radius: number, result: number[]): void;
     getEntry(entityId: number): SpatialEntry3D | undefined;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ecspresso",
-	"version": "0.16.1",
+	"version": "0.16.3",
 	"main": "dist/index.js",
 	"module": "dist/index.js",
 	"types": "dist/index.d.ts",