HashGrid2D
Defined in: src/modules/spatial/hash-grid-2d.ts:27
Grid-based spatial index mapping integer (x, y) cells to sets of
entity IDs. Implements SpatialStructure with TPos = {x, y}.
Suitable for grid games (roguelikes, chess, tile strategy) and for
continuous-position games when paired with Math.floor(pos / cellSize)
cell hashing done by the caller.
Exposes the interface methods (queryAt/queryRect/queryNear/etc.)
plus grid-specific extras (getAt, findAt, findFirstAt, getInRect,
integer add(id, x, y) overloads). Cells live in a nested numeric
Map<y, Map<x, Set>> (row-major). Numeric keys avoid the per-access
string a flat Map<string, Set> would allocate on every cell touch —
this index is read for every cell of every broadphase query, so that
string churn dominated CPU and GC at high entity counts. The extras are
honest about the structure — they aren’t part of the
SpatialStructure contract.
Implements
Section titled “Implements”SpatialStructure<Pos>
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new HashGrid2D():
HashGrid2D
Returns
Section titled “Returns”HashGrid2D
Methods
Section titled “Methods”add(
id,posOrX,y?):void
Defined in: src/modules/spatial/hash-grid-2d.ts:32
Register an entity at a position. No-op if already present at that position.
Parameters
Section titled “Parameters”posOrX
Section titled “posOrX”number | Pos
number
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”clear()
Section titled “clear()”clear():
void
Defined in: src/modules/spatial/hash-grid-2d.ts:52
Remove all entries.
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”findAt()
Section titled “findAt()”findAt(
x,y,predicate):EntityId[]
Defined in: src/modules/spatial/hash-grid-2d.ts:63
Collect every entity at (x, y) for which predicate(id) returns true.
Returns an empty array when the cell is empty or no entity matches. The
predicate is application-defined — typical uses are “is a blocker”, “is
an item”, “is pickable up” — and carries the game-specific semantics,
keeping the spatial index itself domain-neutral.
Parameters
Section titled “Parameters”number
number
predicate
Section titled “predicate”(id) => boolean
Returns
Section titled “Returns”EntityId[]
findFirstAt()
Section titled “findFirstAt()”findFirstAt(
x,y,predicate):EntityId|undefined
Defined in: src/modules/spatial/hash-grid-2d.ts:81
Return the first entity at (x, y) for which predicate(id) returns
true, or undefined if none match. Iteration order follows the
underlying Set insertion order; callers needing a deterministic
preference should use findAt and sort the result.
Parameters
Section titled “Parameters”number
number
predicate
Section titled “predicate”(id) => boolean
Returns
Section titled “Returns”EntityId | undefined
getAt()
Section titled “getAt()”getAt(
x,y):ReadonlySet<EntityId> |undefined
Defined in: src/modules/spatial/hash-grid-2d.ts:98
Return all entity IDs at a given cell, or undefined if no entities
are present. Exposes the backing Set directly for zero-alloc
.has() / .size checks — a grid-specific escape hatch. Prefer
queryAt when writing backend-agnostic code.
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”ReadonlySet<EntityId> | undefined
getInRect()
Section titled “getInRect()”getInRect(
x1,y1,x2,y2):EntityId[]
Defined in: src/modules/spatial/hash-grid-2d.ts:103
Collect all entity IDs within an axis-aligned rectangle (inclusive bounds) as an array.
Parameters
Section titled “Parameters”number
number
number
number
Returns
Section titled “Returns”EntityId[]
move()
Section titled “move()”move(
id,fromOrOldX,toOrOldY,newX?,newY?):void
Defined in: src/modules/spatial/hash-grid-2d.ts:112
Update an entity’s position. Accepts either the interface shape
move(id, from, to) or the grid shorthand move(id, ox, oy, nx, ny).
Skips work if the cell hasn’t changed.
Parameters
Section titled “Parameters”fromOrOldX
Section titled “fromOrOldX”number | Pos
toOrOldY
Section titled “toOrOldY”number | Pos
number
number
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”queryAt()
Section titled “queryAt()”queryAt(
pos):Iterable<EntityId>
Defined in: src/modules/spatial/hash-grid-2d.ts:134
All entity IDs at pos. Empty iterable if none.
Parameters
Section titled “Parameters”Pos
Returns
Section titled “Returns”Iterable<EntityId>
Implementation of
Section titled “Implementation of”queryNear()
Section titled “queryNear()”queryNear(
pos,radius):Iterable<EntityId>
Defined in: src/modules/spatial/hash-grid-2d.ts:141
All entity IDs within radius of pos (Euclidean, inclusive).
radius is in the same units as the position coordinates.
Parameters
Section titled “Parameters”Pos
radius
Section titled “radius”number
Returns
Section titled “Returns”Iterable<EntityId>
Implementation of
Section titled “Implementation of”queryRect()
Section titled “queryRect()”queryRect(
min,max):Iterable<EntityId>
Defined in: src/modules/spatial/hash-grid-2d.ts:163
All entity IDs within an axis-aligned region (inclusive bounds). min / max are the region corners.
Parameters
Section titled “Parameters”Pos
Pos
Returns
Section titled “Returns”Iterable<EntityId>
Implementation of
Section titled “Implementation of”remove()
Section titled “remove()”remove(
id,posOrX,y?):void
Defined in: src/modules/spatial/hash-grid-2d.ts:177
Unregister an entity from a position. No-op if not present.
Parameters
Section titled “Parameters”posOrX
Section titled “posOrX”number | Pos
number
Returns
Section titled “Returns”void