Class GameGrid

Stateful 2‑D lattice with collision rules and optional HTMLElement projection.

Remarks

Implements IGameGrid. Coordinates are column-major tuples [x,y] (matrix[y][x]).
Methods stay flat. Docs group them by job: Matrix, Movement, View, State, Options, Zoom — not DOM vs data.
GameGrid.setCell / GameGrid.setMatrix write the matrix only; GameGrid.refreshCells / GameGrid.refresh / GameGrid.render paint.
DOM notification uses bubbling CustomEvents; IGameGridEventDetail describes detail. Event names live on gridEventsEnum.

Example: Render + keyboard handlers

import GameGrid, { gridEventsEnum, type GameGridDOMEvent } from "@tamb/gamegrid";

const grid = new GameGrid(
  { matrix, options: { wasdControls: true } },
  document.querySelector("#stage")!,
);

window.addEventListener(gridEventsEnum.MOVE_LAND, (e: Event) => {
  const { gameGridInstance } = (e as GameGridDOMEvent).detail;
  console.log(gameGridInstance.getState().activeCoords);
});

Example: Headless state machine without calling render

const grid = new GameGrid({ matrix });
grid.moveRight(); // mutates internal state without touching the DOM
grid.render(document.querySelector("#stage")!); // mount later

Implements

IGameGrid

Index

Matrix

Logical grid data. GameGrid.setCell and GameGrid.setMatrix do not paint. Call a View method when mounted nodes should catch up. GameGrid.getActiveCell / GameGrid.getPreviousCell read matrix fields immediately and overlay current from refs.

getActiveCell getAllCellsByType getCell getMatrix getPreviousCell setCell setMatrix

Movement

Focus and history. Updates IState, fires callbacks and gridEventsEnum events, and highlights the active cell when rendered. Not a matrix write.

moveDown moveLeft moveRight moveTo moveUp rewind rewindTo setActiveCell unrewind unrewindTo

View

Mount, paint, and tear down markup. Optional — omit the constructor container and skip GameGrid.render for headless use. GameGrid.refreshCells also writes the matrix when cell is provided.

refs destroy refresh refreshCells render

State

Authoritative IState. GameGrid.setStateSync runs middleware and does not emit grid CustomEvents.

getState setStateSync

Options

Runtime behaviour toggles. GameGrid.setOptions does not swap the matrix or re-render.

options getOptions setOptions

Zoom

Viewport window and region tiles. Applying zoom rebuilds the visible window when mounted.

clearZoom getActiveRegion getFractionZoom getQuadrantZoom getRegionAt getZoom getZoomAround setZoom zoomAround zoomFraction zoomQuadrant

Constructors

constructor

Matrix

getActiveCell

getActiveCell(): ICell
Cell at IState.activeCoords: matrix data (same source as GameGrid.getCell) plus mounted current / coords from refs when rendered.

Returns ICell
Remarks
After GameGrid.setCell, type and other data fields match the matrix immediately. The painted node on current stays stale until GameGrid.refreshCells / GameGrid.refresh.
Example
```
const tile = grid.getActiveCell();
console.log(tile.type, tile.current);
```
Implementation of IGameGrid.getActiveCell
- Defined in index.ts:910

getAllCellsByType

getAllCellsByType(type: string): ICell[]
Accumulate every ICell.type matching type scanning row-major from GameGrid.getMatrix.
Parameters
- type: string
Returns ICell[]
Example
```
const barriers = grid.getAllCellsByType(cellTypeEnum.BARRIER);
```
Implementation of IGameGrid.getAllCellsByType
- Defined in index.ts:984

getCell

getCell(coords: number[] | readonly [number, number]): ICell
Logical cell from GameGrid.getMatrix: matrix[coords[1]][coords[0]] — raw matrix lookup (bounds unchecked).
Parameters
- coords: number[] | readonly [number, number]
  [x, y].
Returns ICell
Example
```
const cell = grid.getCell([2, 1]); // column 2, row 1
```
Implementation of IGameGrid.getCell
- Defined in index.ts:955

getMatrix

getMatrix(): ICell[][]
Logical matrix backing the grid (matrix[row][column] ⇒ matrix[y][x]).

Returns ICell[][]
Example
```
const rows = grid.getMatrix();
const cell = rows[1][2]; // same as getCell([2, 1])
```
Implementation of IGameGrid.getMatrix
- Defined in index.ts:1801

getPreviousCell

getPreviousCell(): ICell
Cell at IState.prevCoords: matrix data (same source as GameGrid.getCell) plus mounted current / coords from refs when rendered.

Returns ICell
Example
```
const prev = grid.getPreviousCell();
console.log(prev.type, prev.coords);
```
Implementation of IGameGrid.getPreviousCell
- Defined in index.ts:923

setCell

setCell(coords: number[] | readonly [number, number], cell: ICell): void
Replace the logical cell at coords (matrix[y][x]). Does not render, refresh, or patch DOM/refs.
Parameters
- coords: number[] | readonly [number, number]
  [x, y].
- cell: ICell
  Stored by reference, same as GameGrid.setMatrix.
Returns void
Remarks
Bounds unchecked, matching GameGrid.getCell. Data-only: does not patch DOM, refs, or emit events. Movement / blockOnType read the new cell immediately. Call GameGrid.refreshCells with { coords } (or { coords, cell } instead of this method) to update mounted nodes; use GameGrid.refresh / GameGrid.render when the grid shape changes.
Example
```
grid.setCell([2, 1], { type: cellTypeEnum.INTERACTIVE });
grid.refreshCells({ coords: [2, 1] });
```
Implementation of IGameGrid.setCell
- Defined in index.ts:970

setMatrix

setMatrix(m: ICell[][]): void
Replace logical matrix reference; callers must GameGrid.refresh or GameGrid.render to reconcile DOM when mounted.
Parameters
- m: ICell[][]
Returns void
Remarks
Headless grids also alias IRefsObject.cells to the new matrix so GameGrid.getActiveCell stays in sync.
Example
```
grid.setMatrix(nextRows);
if (grid.getState().rendered) grid.refresh();
```
Implementation of IGameGrid.setMatrix
- Defined in index.ts:1785

Movement

moveDown

moveDown(): void
Returns void
Remarks
Dispatches gridEventsEnum.MOVE_DOWN (with IMoveEventDetail) before GameGrid.setActiveCell.
Example
```
grid.moveDown();
```
Implementation of IGameGrid.moveDown
- Defined in index.ts:1087

moveLeft

moveLeft(): void
Returns void
Remarks
Dispatches gridEventsEnum.MOVE_LEFT (with IMoveEventDetail) before GameGrid.setActiveCell.
Example
```
grid.moveLeft();
```
Implementation of IGameGrid.moveLeft
- Defined in index.ts:1109

moveRight

moveRight(): void
Returns void
Remarks
Dispatches gridEventsEnum.MOVE_RIGHT (with IMoveEventDetail) before GameGrid.setActiveCell.
Example
```
grid.moveRight();
```
Implementation of IGameGrid.moveRight
- Defined in index.ts:1065

moveTo

moveTo(
    coordsOrPath:
        | number[]
        | readonly [number, number]
        | (number[] | readonly [number, number])[],
): void
Walk to one cell, or along an explicit list of cells, through GameGrid.setActiveCell.
Parameters
- coordsOrPath: number[] | readonly [number, number] | (number[] | readonly [number, number])[]
  A single [x, y] or an array of [x, y] steps. Not pathfinding (no A*): gaps teleport.
Returns void
Remarks
Each step uses the existing block / collide / wrap / zoom-edge rules. Stops when a step does not land on the requested cell (blocked, finite-edge clamp, or wrap to a different cell). Skips steps that are already the active cell. Not rate-limited by IOptions.moveDebounce. Does not dispatch directional gridEventsEnum.MOVE_UP / MOVE_RIGHT / MOVE_DOWN / MOVE_LEFT (same as a cell click).
Example: One cell
```
grid.moveTo([2, 1]);
```
Example: Explicit path
```
grid.moveTo([
  [0, 1],
  [0, 2],
  [1, 2],
]);
```
Implementation of IGameGrid.moveTo
- Defined in index.ts:1139

moveUp

moveUp(): void
Directional move: invokes the onMove member of IOptions.callbacks → dispatches gridEventsEnum.MOVE_UP (with IMoveEventDetail) → GameGrid.setActiveCell.

Returns void
Example
```
grid.moveUp();
```
Implementation of IGameGrid.moveUp
- Defined in index.ts:1046

rewind

rewind(steps?: number): void
Step back steps entries in IState.moves (default 1).
Parameters
- steps: number = 1
Returns void
Remarks
No-op when there is no earlier position, or steps is not a positive finite number. Extra steps clamp to the oldest remaining entry. Not rate-limited by IOptions.moveDebounce. Dispatches gridEventsEnum.REWIND (with detail.steps / detail.index plus IMoveEventDetail) then gridEventsEnum.MOVE_LAND. Dropped coords are pushed onto IState.future so GameGrid.unrewind can replay them.
Example
```
grid.moveDown();
grid.moveRight();
grid.rewind();
grid.rewind(2);
```
Implementation of IGameGrid.rewind
- Defined in index.ts:1170

rewindTo

rewindTo(index: number): void
Jump to index in IState.moves (0 = oldest remaining).
Parameters
- index: number
Returns void
Remarks
No-op when index is not an integer in range, or it is already the current (last) entry. Truncates history after the chosen index (later entries move to IState.future). Same events as GameGrid.rewind.
Example
```
grid.rewindTo(0);
```
Implementation of IGameGrid.rewindTo
- Defined in index.ts:1190

setActiveCell

setActiveCell(x: number, y: number, direction?: string): void
Move focus (x,y) when IOptions.blockOnType, IOptions.collideOnType, IOptions.moveOnType, and bounds/wrap rules allow.
Parameters
- x: number
- y: number
- Optionaldirection: string
Returns void
Remarks
Dispatch order (subset may apply): gridEventsEnum.MOVE_BLOCKED if blocked; gridEventsEnum.MOVE_COLLISION when entering a collide-type cell; gridEventsEnum.MOVE_DETTACH when leaving a collide-type cell for a non-collide cell; ICell.eventTypes onExit then onEnter when the active cell changes; axis gridEventsEnum.WRAP_X / gridEventsEnum.WRAP_Y / gridEventsEnum.BOUNDARY_X / gridEventsEnum.BOUNDARY_Y; aggregate gridEventsEnum.WRAP / gridEventsEnum.BOUNDARY; finally gridEventsEnum.MOVE_LAND (pairs with the onLand member of IOptions.callbacks) only when the active cell actually changes. Move events carry IMoveEventDetail (from, to, direction, blocked). GameGrid.render does not call this method.
Example
```
grid.setActiveCell(2, 1, directionEnum.RIGHT);
```
Implementation of IGameGrid.setActiveCell
- Defined in index.ts:710

unrewind

unrewind(steps?: number): void
Replay steps entries from IState.future (default 1). Redo after GameGrid.rewind.
Parameters
- steps: number = 1
Returns void
Remarks
No-op when the forward stack is empty, or steps is not a positive finite number. Extra steps clamp to the newest remaining future entry. Not rate-limited by IOptions.moveDebounce. Dispatches gridEventsEnum.UNREWIND (with detail.steps / detail.index plus IMoveEventDetail) then gridEventsEnum.MOVE_LAND.
Example
```
grid.rewind();
grid.unrewind();
```
Implementation of IGameGrid.unrewind
- Defined in index.ts:1210

unrewindTo

unrewindTo(index: number): void
Jump forward to index in the combined trail (moves then future).
Parameters
- index: number
Returns void
Remarks
index is counted from the oldest remaining IState.moves entry (0), through the current cell, into IState.future. No-op when index is not an integer strictly ahead of the current entry, or past the newest future coord. Same events as GameGrid.unrewind.
Example
```
grid.rewind(3);
grid.unrewindTo(2);
```
Implementation of IGameGrid.unrewindTo
- Defined in index.ts:1231

View

refs

refs: IRefsObject

After GameGrid.render, hydrated rows/cells and container. Headless grids mirror cells onto the logical matrix until mount.

Example

const root = grid.refs.container; // HTMLElement after render, null while headless

destroy

destroy(): void
Detach listeners when rendered and clear injected structure; resets rendered in state via GameGrid.setStateSync.

Returns void
Remarks
Idempotent-friendly: always dispatches gridEventsEnum.DESTROYED whether or not DOM was present. Middleware pre / post run for the rendered: false patch.
Example
```
grid.destroy();
```
Implementation of IGameGrid.destroy
- Defined in index.ts:1756

refresh

refresh(): void
Tear down handlers, wipe container, rebuild rows/cells from GameGrid.getMatrix, reattach handlers.

Returns void
Remarks
Does not dispatch gridEventsEnum.RENDERED; that event is emitted from GameGrid.render. Honors IOptions.injectStyles the same way as GameGrid.render.
Example: After swapping the matrix
```
grid.setMatrix(nextRows);
grid.refresh();
```
Implementation of IGameGrid.refresh
- Defined in index.ts:332

refreshCells

refreshCells(cells: ICellRefresh | ICellRefresh[]): void
Write optional cell data and rebuild one or more cell nodes from the current matrix.
Parameters
- cells: ICellRefresh | ICellRefresh[]
  A single ICellRefresh or an array. cell is written with GameGrid.setCell when provided; omit it to re-render the existing matrix entry.
Returns void
Remarks
Flow: GameGrid.setCell is data-only (movement reads the new type immediately; DOM/refs stay stale). Call this afterward with { coords } to paint those tiles, or pass { coords, cell } to write and paint in one step. Headless grids update matrix data only. Off-screen cells under zoom stay current: null. Does not rebuild the whole grid — use GameGrid.refresh when dimensions or the zoom window change. Dispatches gridEventsEnum.CELLS_REFRESHED once with detail.cells.
Example: Two-step write then paint
```
grid.setCell([2, 0], { type: cellTypeEnum.OPEN });
grid.refreshCells({ coords: [2, 0] });
```
Example: One-step write and paint
```
grid.refreshCells({ coords: [1, 1], cell: { type: cellTypeEnum.BARRIER } });
```
Implementation of IGameGrid.refreshCells
- Defined in index.ts:354

render

render(container: HTMLElement): void
Mount markup into container, wire keyboard/pointer handlers, and highlight the current active cell.
Parameters
- container: HTMLElement
Returns void
Remarks
Clears/rebuilds refs for this mount. Prefer GameGrid.refresh after the first paint when rebuilding from the same host. Dispatches gridEventsEnum.RENDERED once the container is patched and listeners attach. Does not call GameGrid.setActiveCell — no move / collide / land / ICell.eventTypes events, and currentDirection is left as-is. Skips stylesheet injection when IOptions.injectStyles is false.
Example: Headless first, then mount
```
const grid = new GameGrid({ matrix });
grid.moveRight();
grid.render(document.querySelector("#stage")!);
```
Implementation of IGameGrid.render
- Defined in index.ts:478

State

getState

getState(): IState
Authoritative IState backing movement callbacks and renders.

Returns IState
Example
```
const { activeCoords, moves, future } = grid.getState();
```
Implementation of IGameGrid.getState
- Defined in index.ts:309

setStateSync

setStateSync(obj: StatePatch): void
Apply partial state with MiddlewareFn pre (mutate patch) → merge → post.
Parameters
- obj: StatePatch
Returns void
Remarks
Middleware runs around the merge inside this call; does not emit grid CustomEvents.
Example
```
grid.setStateSync({ activeCoords: [1, 0], myScore: 3 });
```
Implementation of IGameGrid.setStateSync
- Defined in index.ts:288

Options

options

options: IOptions

Runtime toggles: input, collisions, middleware, callbacks, styling. Merged from ctor defaults and GameGrid.setOptions.

Example

grid.options.wasdControls;
grid.setOptions({ wasdControls: true });

getOptions

getOptions(): IOptions
Snapshot merged IOptions — updates after GameGrid.setOptions.

Returns IOptions
Example
```
const { wasdControls, moveDebounce } = grid.getOptions();
```
Implementation of IGameGrid.getOptions
- Defined in index.ts:1728

setOptions

setOptions(newOptions: IOptions): void
Shallow-merge behaviours into IGameGrid.options without swapping the matrix snapshot or re-rendering.
Parameters
- newOptions: IOptions
Returns void
Example: Speed power-up
```
grid.setOptions({ moveDebounce: 40, wasdControls: true });
```
Implementation of IGameGrid.setOptions
- Defined in index.ts:1739

Zoom

clearZoom

clearZoom(options?: IZoomOptions): void
Clear the zoom window. Dispatches gridEventsEnum.ZOOM_CLEARED.
Parameters
- Optionaloptions: IZoomOptions
Returns void
Example
```
grid.clearZoom({ animate: true });
```
Implementation of IGameGrid.clearZoom
- Defined in index.ts:1888

getActiveRegion

getActiveRegion(): IRegionTile | null
IState.region or computed from the active cell when region tracking is enabled.

Returns IRegionTile | null
Example
```
const current = grid.getActiveRegion();
```
Implementation of IGameGrid.getActiveRegion
- Defined in index.ts:2046

getFractionZoom

getFractionZoom(divisions: number, tileX: number, tileY: number): IZoomBounds
Compute zoom bounds for a fraction tile (divisions×divisions grid).
Parameters
- divisions: number
- tileX: number
- tileY: number
Returns IZoomBounds
Example
```
const tile = grid.getFractionZoom(3, 1, 1);
```
Implementation of IGameGrid.getFractionZoom
- Defined in index.ts:1969

getQuadrantZoom

getQuadrantZoom(quadrant: ZoomQuadrant): IZoomBounds
Compute zoom bounds for a quadrant (divisions === 2).
Parameters
- quadrant: ZoomQuadrant
Returns IZoomBounds
Example
```
const se = grid.getQuadrantZoom("se");
```
Implementation of IGameGrid.getQuadrantZoom
- Defined in index.ts:1957

getRegionAt

getRegionAt(
coords: number[] | readonly [number, number],
divisions?: number,
): IRegionTile
Region tile for coords; divisions defaults to IOptions.regionDivisions.
Parameters
- coords: number[] | readonly [number, number]
- Optionaldivisions: number
Returns IRegionTile
Example
```
const region = grid.getRegionAt([4, 1], 2);
```
Implementation of IGameGrid.getRegionAt
- Defined in index.ts:2027

getZoom

getZoom(): IZoomBounds | null
Current zoom bounds or null when no zoom is active.

Returns IZoomBounds | null
Example
```
const zoom = grid.getZoom();
```
Implementation of IGameGrid.getZoom
- Defined in index.ts:1813

getZoomAround

getZoomAround(
    center: number[] | readonly [number, number],
    radiusX: number,
    radiusY?: number,
): IZoomBounds
Compute zoom bounds around a center cell ± radii, clipped to the matrix.
Parameters
- center: number[] | readonly [number, number]
- radiusX: number
- OptionalradiusY: number
Returns IZoomBounds
Example
```
const bounds = grid.getZoomAround([2, 2], 1);
```
Implementation of IGameGrid.getZoomAround
- Defined in index.ts:1941

setZoom

setZoom(bounds: IZoomBounds, options?: IZoomOptions): void
Apply a zoom window in world coordinates.
Parameters
- bounds: IZoomBounds
- Optionaloptions: IZoomOptions
Returns void
Remarks
Clamps activeCoords into bounds when outside. Dispatches gridEventsEnum.ZOOM_SET.
Example
```
grid.setZoom({ minX: 0, minY: 0, maxX: 3, maxY: 3 }, { animate: true });
```
Implementation of IGameGrid.setZoom
- Defined in index.ts:1825

zoomAround

zoomAround(
    center: number[] | readonly [number, number],
    radiusX: number,
    radiusY?: number,
    options?: IZoomOptions,
): void
Compute bounds then GameGrid.setZoom.
Parameters
- center: number[] | readonly [number, number]
- radiusX: number
- OptionalradiusY: number
- Optionaloptions: IZoomOptions
Returns void
Example
```
grid.zoomAround([2, 2], 1, 1, { animate: true });
```
Implementation of IGameGrid.zoomAround
- Defined in index.ts:1981

zoomFraction

zoomFraction(
    divisions: number,
    tileX: number,
    tileY: number,
    options?: IZoomOptions,
): void
Compute fraction bounds then GameGrid.setZoom.
Parameters
- divisions: number
- tileX: number
- tileY: number
- Optionaloptions: IZoomOptions
Returns void
Example
```
grid.zoomFraction(3, 0, 1);
```
Implementation of IGameGrid.zoomFraction
- Defined in index.ts:2010

zoomQuadrant

zoomQuadrant(quadrant: ZoomQuadrant, options?: IZoomOptions): void
Compute quadrant bounds then GameGrid.setZoom.
Parameters
- quadrant: ZoomQuadrant
- Optionaloptions: IZoomOptions
Returns void
Example
```
grid.zoomQuadrant("se");
```
Implementation of IGameGrid.zoomQuadrant
- Defined in index.ts:1998

Constructors

constructor

new GameGrid(config: IConfig, container?: HTMLElement): GameGrid
Copies matrix/config, merges IConfig.state, runs GameGrid.render when container is passed, then dispatches gridEventsEnum.CREATED.
Parameters
- config: IConfig
  Logical matrix plus optional IConfig.options / IConfig.state.
- Optionalcontainer: HTMLElement
  When provided, behaves like invoking GameGrid.render synchronously afterward.
Returns GameGrid
Example: Immediate render
```
const grid = new GameGrid({ matrix, options: { wasdControls: true } }, root);
```
Example: Headless, then mount
```
const grid = new GameGrid({ matrix, state: { activeCoords: [1, 0] } });
grid.moveDown();
grid.render(root);
```
- Defined in index.ts:232

Class GameGrid

Remarks

Example: Render + keyboard handlers

Example: Headless state machine without calling render

Implements

Index

Matrix

Movement

View

State

Options

Zoom

Constructors

Matrix

getActiveCell

Returns ICell

Remarks

Example

getAllCellsByType

Parameters

Returns ICell[]

Example

getCell

Parameters

Returns ICell

Example

getMatrix

Returns ICell[][]

Example

getPreviousCell

Returns ICell

Example

setCell

Parameters

Returns void

Remarks

Example

setMatrix

Parameters

Returns void

Remarks

Example

Movement

moveDown

Returns void

Remarks

Example

moveLeft

Returns void

Remarks

Example

moveRight

Returns void

Remarks

Example

moveTo

Parameters

Returns void

Remarks

Example: One cell

Example: Explicit path

moveUp

Returns void

Example

rewind

Parameters

Returns void

Remarks

Example

rewindTo

Parameters

Returns void

Remarks

Example

setActiveCell

Parameters

Returns void

Remarks

Example

unrewind