ecspresso 0.16.0 → 0.16.2

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

@@ -12,14 +12,30 @@ 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;
 }
 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, SpatialEntry3D[]>;
+    /**
+     * 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,10 +49,11 @@ 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.
+ * Bumps the alive-generation counter so entries inserted prior to this call
+ * are implicitly stale (any access via `getLiveEntry3D` / `liveEntryCount3D`
+ * filters by the current gen). Existing `SpatialEntry3D` objects remain in
+ * the `entries` array for in-place reuse by the next `insertEntity3D`, so
+ * steady-state rebuilds allocate zero entries.
  *
  * Cell buckets are cleared in place — keys are retained so subsequent
  * inserts hit the existing array rather than allocating a fresh one.
@@ -48,13 +65,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 +100,8 @@ 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;
 }

package/package.json

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