Interface IGameGrid

Public contract implemented by GameGrid.

Remarks

Methods stay flat on the instance. Docs group them by job (not DOM vs data): Matrix (logical cells), Movement (focus and history), View (optional markup), State, Options, and Zoom.

GameGrid.setCell / GameGrid.setMatrix write the matrix only. GameGrid.refreshCells / GameGrid.refresh / GameGrid.render paint. Movement updates state and events; it highlights when mounted.

For DOM events (CustomEvents), see IGameGridEventDetail and gridEventsEnum.

Example: Construct, move, and listen

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

const matrix = [
  [{ type: cellTypeEnum.OPEN }, { type: cellTypeEnum.BARRIER }],
  [{ type: cellTypeEnum.OPEN }, { type: cellTypeEnum.OPEN }],
];

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

grid.moveDown();
window.addEventListener(gridEventsEnum.MOVE_LAND, (e: Event) => {
  const { gameGridInstance } = (e as GameGridDOMEvent).detail;
  console.log(gameGridInstance.getActiveCell().type);
});

interface IGameGrid {
    options: IOptions;
    refs: IRefsObject;
    clearZoom(options?: IZoomOptions): void;
    destroy(): void;
    getActiveCell(): ICell;
    getActiveRegion(): IRegionTile | null;
    getAllCellsByType(type: string): ICell[];
    getCell(coords: number[] | readonly [number, number]): ICell;
    getFractionZoom(
        divisions: number,
        tileX: number,
        tileY: number,
    ): IZoomBounds;
    getMatrix(): ICell[][];
    getOptions(): IOptions;
    getPreviousCell(): ICell;
    getQuadrantZoom(quadrant: ZoomQuadrant): IZoomBounds;
    getRegionAt(
        coords: number[] | readonly [number, number],
        divisions?: number,
    ): IRegionTile;
    getState(): IState;
    getZoom(): IZoomBounds | null;
    getZoomAround(
        center: number[] | readonly [number, number],
        radiusX: number,
        radiusY?: number,
    ): IZoomBounds;
    moveDown(): void;
    moveLeft(): void;
    moveRight(): void;
    moveTo(
        coordsOrPath:
            | number[]
            | readonly [number, number]
            | (number[] | readonly [number, number])[],
    ): void;
    moveUp(): void;
    refresh(): void;
    refreshCells(cells: ICellRefresh | ICellRefresh[]): void;
    render(container: HTMLElement): void;
    rewind(steps?: number): void;
    rewindTo(index: number): void;
    setActiveCell(x: number, y: number, direction?: string): void;
    setCell(coords: number[] | readonly [number, number], cell: ICell): void;
    setMatrix(matrix: ICell[][]): void;
    setOptions(newOptions: IOptions): void;
    setStateSync(obj: StatePatch): void;
    setZoom(bounds: IZoomBounds, options?: IZoomOptions): void;
    unrewind(steps?: number): void;
    unrewindTo(index: number): void;
    zoomAround(
        center: number[] | readonly [number, number],
        radiusX: number,
        radiusY?: number,
        options?: IZoomOptions,
    ): void;
    zoomFraction(
        divisions: number,
        tileX: number,
        tileY: number,
        options?: IZoomOptions,
    ): void;
    zoomQuadrant(quadrant: ZoomQuadrant, options?: IZoomOptions): void;
}

Implemented by

GameGrid

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

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); // current is the mounted node when rendered
```
- Defined in interfaces.ts:379

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);
```
- Defined in interfaces.ts:401

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
```
- Defined in interfaces.ts:436

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]; // row 1, column 2 — same as getCell([2, 1])
```
- Defined in interfaces.ts:412

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);
```
- Defined in interfaces.ts:366

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] }); // paint if mounted
```
- Defined in interfaces.ts:451

setMatrix

setMatrix(matrix: ICell[][]): void
Replace logical matrix reference; callers must GameGrid.refresh or GameGrid.render to reconcile DOM when mounted.
Parameters
- matrix: 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();
```
- Defined in interfaces.ts:425

Movement

moveDown

moveDown(): void
Returns void
Remarks
Dispatches gridEventsEnum.MOVE_DOWN (with IMoveEventDetail) before GameGrid.setActiveCell.
Example
```
grid.moveDown();
```
- Defined in interfaces.ts:513

moveLeft

moveLeft(): void
Returns void
Remarks
Dispatches gridEventsEnum.MOVE_LEFT (with IMoveEventDetail) before GameGrid.setActiveCell.
Example
```
grid.moveLeft();
```
- Defined in interfaces.ts:523

moveRight

moveRight(): void
Returns void
Remarks
Dispatches gridEventsEnum.MOVE_RIGHT (with IMoveEventDetail) before GameGrid.setActiveCell.
Example
```
grid.moveRight();
```
- Defined in interfaces.ts:503

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],
]);
```
- Defined in interfaces.ts:544

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();
```
- Defined in interfaces.ts:493

rewind

rewind(steps?: number): void
Step back steps entries in IState.moves (default 1).
Parameters
- Optionalsteps: number
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();  // back one step
grid.rewind(2); // back two steps (clamps to the oldest remaining)
```
- Defined in interfaces.ts:567

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); // jump to the oldest remaining history entry
```
- Defined in interfaces.ts:580

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);
```
- Defined in interfaces.ts:391

unrewind

unrewind(steps?: number): void
Replay steps entries from IState.future (default 1). Redo after GameGrid.rewind.
Parameters
- Optionalsteps: number
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(); // redo that step
```
- Defined in interfaces.ts:595

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); // jump forward in the combined moves + future trail
```
- Defined in interfaces.ts:610

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();
```
- Defined in interfaces.ts:345

refresh

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

Returns void
Throws
When IRefsObject.container is missing (never rendered successfully).

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();
```
- Defined in interfaces.ts:315

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 } });
```
- Defined in interfaces.ts:333

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")!);
```
- Defined in interfaces.ts:301

State

getState

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

Returns IState
Example
```
const { activeCoords, moves, future } = grid.getState();
```
- Defined in interfaces.ts:471

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 });
```
- Defined in interfaces.ts:483

Options

options

options: IOptions

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

Example

grid.options.wasdControls; // current merged value
grid.setOptions({ wasdControls: true });

getOptions

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

Returns IOptions
Example
```
const { wasdControls, moveDebounce } = grid.getOptions();
```
- Defined in interfaces.ts:355

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 });
```
- Defined in interfaces.ts:461

Zoom

clearZoom

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

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();
```
- Defined in interfaces.ts:731

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); // center ninth
```
- Defined in interfaces.ts:676

getQuadrantZoom

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

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);
```
- Defined in interfaces.ts:721

getZoom

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

Returns IZoomBounds | null
Example
```
const zoom = grid.getZoom(); // { minX, minY, maxX, maxY } or null
```
- Defined in interfaces.ts:620

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); // 3×3 window around [2, 2]
```
- Defined in interfaces.ts:652

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 });
```
- Defined in interfaces.ts:632

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 });
```
- Defined in interfaces.ts:686

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);
```
- Defined in interfaces.ts:711

zoomQuadrant

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

Interface IGameGrid

Remarks

Example: Construct, move, and listen

Implemented by

Index

Matrix

Movement

View

State

Options

Zoom

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

Parameters

Returns void