Class

Cell

Extends Point

A single addressable position in a Grid, carrying both gameplay data and the metadata the grid's algorithms read.

Cell is-a Point

Cell extends Point, so its x/y are its column/row in the grid and every read-only point query works between cells out of the box — Point.distanceTo, Point.angleTo, Point.equals, Point.dot, and so on. For grid-native step counts, prefer Cell.manhattanDistanceTo / Cell.chebyshevDistanceTo over the inherited Euclidean Point.distanceTo.

Coordinates are immutable

A cell's coordinate is its identity within the grid index, so it cannot change. Writing cell.x/cell.y — or calling any of Point's in-place vector mutators (add, scale, forward, lerp, …), which assign through those setters — throws an EngineError with ErrorCode.GRID_CELL_IMMUTABLE. To do vector math, take a detached copy first: Point.clone returns a plain, mutable Point.

Data and metadata

Cell.data is the arbitrary gameplay payload (a wall, an actor, an item, …) — set it, read it, clear it to null.
Cell.passable and Cell.cost are the defaults Grid.findPath reads. Mark walls passable = false; raise cost to make the search route around difficult terrain.

Cells are created by their owning Grid; you never construct one directly. Resolve them with Grid.cellAt and navigate with Cell.neighbors / Cell.left and friends.

Example

const grid = new Grid<'wall' | 'floor'>(10, 10, () => 'floor');
const cell = grid.cellAt(2, 3)!;

cell.data = 'wall';
cell.passable = false;

const right = cell.right();        // Cell | null
const reach = cell.manhattanDistanceTo({ x: 5, y: 3 }); // 3

const detached = cell.clone().add(1, 0); // plain Point; cell is untouched

Properties

cost: number

The cost of stepping into this cell, read by Grid.findPath as the default movement cost (overridable per call via PathfindingOptions.cost). Must be positive. Defaults to DEFAULT_CELL_COST.

data: null | TData

The arbitrary gameplay payload occupying this cell, or null when the cell is empty. Mutable: assign to populate, set to null to clear.

readonly #

grid: Grid<TData>

The Grid this cell belongs to. Used to resolve neighbours and wrap coordinates; a cell can only ever be navigated within its own grid.

passable: boolean

Whether the cell may be stepped into. Consumed by Grid.findPath as the default walkability test (overridable per call via PathfindingOptions.isPassable). Defaults to DEFAULT_CELL_PASSABLE.

Accessors

readonly #

angle: number

Calculates the angle of this point in radians, measured from 0,0 as atan2(y, x). The result is in the range (-π, π].

readonly #

empty: boolean

Whether this cell holds no Cell.data (data === null).

readonly #

length: number

Calculates the length (magnitude) of this point measured as a vector from 0,0.

readonly #

lengthSquared: number

Calculates the squared length of this point measured from 0,0. Cheaper than Point.length (no square root) and sufficient when only comparing magnitudes.

x: number

The column (x coordinate) of this cell. Read-only — see the class docs on coordinate immutability.

y: number

The row (y coordinate) of this cell. Read-only — see the class docs on coordinate immutability.

Methods

add(x: number, y: number): this

Adds the input values to this point's coordinates.

Parameters

x number
y number

Returns

this

This point, for chaining.

add(point: PointPrimitive): this

Adds another point's coordinates to this point's coordinates.

Parameters

point PointPrimitive

Returns

this

This point, for chaining.

angleTo(target: PointPrimitive): number

Calculate the angle from this point to a target point.

Parameters

target PointPrimitive

Returns

number

chebyshevDistanceTo(target: PointPrimitive): number

The Chebyshev (chessboard) distance to a target — max(|dx|, |dy|). This is the step count between cells under 8-connected movement, where a diagonal step costs the same as an orthogonal one.

Parameters

target PointPrimitive

Returns

number

clone(): Point

Returns a clone of this point. Useful for producing a new point with displaced coordinates e.g.

const newPosition = originalPosition.clone().moveTowards(target, 10);

Returns

Point

cloneToImmutablePrimitive(): Readonly

Returns an immutable primitive clone of this point, where the x and y values are frozen at runtime and marked readonly by the compiler.

Returns

Readonly

cloneToNormalized(): Point

Produces a new point with normalized x and y values (a unit vector pointing in the same direction). Normalizing a zero-length point yields a new 0,0 point.

Returns

Point

cloneToPrimitive(): PointPrimitive

Returns a primitive clone of this point.

Returns

PointPrimitive

cloneToTuple(): [number, number]

Returns a tuple clone of this point expressed as [x, y].

Returns

[number, number]

copyFrom(source: PointPrimitive): this

Copies the coordinates from another point into this one.

Parameters

source PointPrimitive

Returns

this

This point, for chaining.

cross(target: PointPrimitive): number

Calculate the 2D cross product (the z-component of the 3D cross product) between this point and a target point, treating both as vectors from the origin 0,0. The sign indicates winding direction.

Parameters

target PointPrimitive

Returns

number

distanceSquaredTo(target: PointPrimitive): number

Calculate the squared distance from this point to a target point. Cheaper than Point.distanceTo (no square root) and sufficient when only comparing distances.

Parameters

target PointPrimitive

Returns

number

distanceTo(target: PointPrimitive): number

Calculate the distance from this point to a target point.

Parameters

target PointPrimitive

Returns

number

dot(target: PointPrimitive): number

Calculate the dot product between this point and a target point, treating both as vectors from the origin 0,0.

Parameters

target PointPrimitive

Returns

number

down(distance: number, wrap: boolean): null | Cell<TData>

The cell distance rows down (toward larger y).

Parameters

distance number
wrap boolean

Returns

null | Cell<TData>

The target cell, or null if out of bounds and not wrapping.

equals(target: PointPrimitive, precision: number): boolean

Determines whether this cell sits at the same grid coordinate as a target.

Overrides Point.equals to default precision to 0 (exact) rather than Point's deliberately-loose 1. Cell coordinates are discrete integers, so the inherited tolerance of 1 would report two adjacent cells as equal — almost never what grid code wants. Within a single grid, cells are stable singletons, so === identity is the cheapest exact test; this method is for comparing against a bare coordinate (e.g. a { x, y } target).

Parameters

target PointPrimitive
precision number

Returns

boolean

forward(distance: number): this

Move this point forward by a given distance along Point.angle — i.e. along the ray from the origin 0,0 through this point, treating the point as a vector.

Parameters

distance number

Returns

this

This point, for chaining.

left(distance: number, wrap: boolean): null | Cell<TData>

The cell distance columns to the left (toward smaller x).

Parameters

distance number
wrap boolean

Returns

null | Cell<TData>

The target cell, or null if out of bounds and not wrapping.

lerp(target: PointPrimitive, t: number): this

Linearly interpolates this point toward a target point by a fraction t, where 0 leaves this point unchanged and 1 moves it onto the target. Values outside 0..1 extrapolate.

Parameters

target PointPrimitive
t number

Returns

this

This point, for chaining.

manhattanDistanceTo(target: PointPrimitive): number

The Manhattan (taxicab) distance to a target — |dx| + |dy|. This is the step count between cells under 4-connected movement.

Parameters

target PointPrimitive

Returns

number

moveInDirection(angle: number, distance: number): this

Move this point in a given direction by a given distance.

Parameters

angle number
distance number

Returns

this

This point, for chaining.

moveTowards(target: PointPrimitive, distance: number): this

Move this point toward a target point by a given distance. The point will not overshoot: if the target is nearer than distance, this point lands exactly on the target.

Parameters

target PointPrimitive
distance number

Returns

this

This point, for chaining.

negate(): this

Negates this point's coordinates, producing the opposing vector.

Returns

this

This point, for chaining.

neighbors(options: NeighborOptions): Cell<TData>[]

The cells adjacent to this one. Orthogonal (4-connected) by default; pass { diagonal: true } for the 8-connected ring. Out-of-bounds neighbours are dropped unless { wrap: true } is given, in which case they wrap across edges (this cell itself is never returned).

Parameters

options NeighborOptions

Returns

Cell<TData>[]

The neighbouring cells, orthogonals first then diagonals.

Example

const orthogonal = cell.neighbors();                  // up to 4
const all = cell.neighbors({ diagonal: true });       // up to 8
const open = cell.neighbors().filter((c) => c.passable);

normalize(): this

string

up(distance: number, wrap: boolean): null | Cell<TData>

The cell distance rows up (toward smaller y, matching the engine's screen-space convention where "up" is -y).

Parameters

distance number
wrap boolean

Returns

null | Cell<TData>

The target cell, or null if out of bounds and not wrapping.

static #

angular(radians: number): Point

Creates a new point where the x and y values indicate a direction specified by input radians, starting from 1,0.

Parameters

radians number

Returns

Point

static #

down(): Point

Creates a new point of 0,1, representing a "downward facing" magnitude.

Returns

Point

static #

from(value: PointPrimitive | readonly [number, number]): Point

Creates a new point from an existing point primitive or an [x, y] tuple.

Parameters

value PointPrimitive | readonly [number, number]

Returns

Point

static #

left(): Point

Creates a new point of -1,0, representing a "left facing" magnitude.

Returns

Point

static #

right(): Point

Creates a new point of 1,0, representing a "right facing" magnitude.

Returns

Point

static #

up(): Point

Creates a new point of 0,-1, representing an "upward facing" magnitude.

Returns

Point

static #

zero(): Point

Creates a new point of 0,0.

Returns

Point