Interface IOptions

Runtime behaviour toggles, collision rules, middleware, callbacks, styling, and event routing.

Example

const grid = new GameGrid({
  matrix,
  options: {
    wasdControls: true,
    infiniteX: true,
    blockOnType: [cellTypeEnum.BARRIER],
    eventTarget: new EventTarget(),
  },
});

interface IOptions {
    activeClasses?: string[];
    animateZoom?: boolean;
    arrowControls?: boolean;
    blockOnType?: string[];
    callbacks?: {
        onBlock?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onBoundary?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onBoundaryX?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onBoundaryY?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onCollide?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onDettach?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onLand?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onMove?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onRegionChange?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onRewind?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onUnrewind?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onWrap?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onWrapX?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onWrapY?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onZoomCleared?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onZoomEdge?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onZoomExit?: (gamegridInstance: IGameGrid, newState: IState) => void;
        onZoomSet?: (gamegridInstance: IGameGrid, newState: IState) => void;
    };
    cellClasses?: string[];
    clickable?: boolean;
    collideOnType?: string[];
    constrainToZoom?: boolean;
    containerClasses?: string[];
    eventTarget?: EventTarget;
    id?: string;
    infiniteX?: boolean;
    infiniteY?: boolean;
    injectStyles?: boolean;
    middlewares?: { post?: MiddlewareFn[]; pre?: MiddlewareFn[] };
    moveDebounce?: number | [number, number, number, number];
    moveOnType?: string[];
    regionDivisions?: number;
    rewindLimit?: number;
    rowClasses?: string[];
    slideZoomOnEdge?: boolean;
    wasdControls?: boolean;
    zoomSlideDuration?: number;
    zoomViewportClasses?: string[];
}

Properties

`Optional`activeClasses

activeClasses?: string[]

`Optional`animateZoom

animateZoom?: boolean

Default whether zoom transitions animate. Overridden by IZoomOptions.animate. Default: false.

`Optional`arrowControls

arrowControls?: boolean

`Optional`blockOnType

blockOnType?: string[]

Cell type values that cannot be entered; movement snaps back to the previous cell.

`Optional`callbacks

callbacks?: {
    onBlock?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onBoundary?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onBoundaryX?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onBoundaryY?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onCollide?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onDettach?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onLand?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onMove?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onRegionChange?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onRewind?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onUnrewind?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onWrap?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onWrapX?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onWrapY?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onZoomCleared?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onZoomEdge?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onZoomExit?: (gamegridInstance: IGameGrid, newState: IState) => void;
    onZoomSet?: (gamegridInstance: IGameGrid, newState: IState) => void;
}

Example

new GameGrid({
  matrix,
  options: {
    callbacks: {
      onLand: (gg) => console.log("landed", gg.getState().activeCoords),
      onBlock: (gg) => console.log("blocked at", gg.getActiveCell().type),
    },
  },
});

`Optional`cellClasses

cellClasses?: string[]

`Optional`clickable

clickable?: boolean

`Optional`collideOnType

collideOnType?: string[]

Cell types that emit collision events upon entry (movement still succeeds unless blocked).

`Optional`constrainToZoom

constrainToZoom?: boolean

When zoom is set, keep movement inside the zoom window.

Remarks

true (default): clamp/wrap to zoom; attempts past the window emit gridEventsEnum.ZOOM_EDGE. false: full-matrix movement; leaving the window emits gridEventsEnum.ZOOM_EXIT.

`Optional`containerClasses

containerClasses?: string[]

`Optional`eventTarget

eventTarget?: EventTarget

Target for dispatched CustomEvents carrying grid detail; defaults to window when available.

Remarks

Use a standalone EventTarget (or HTMLElement) when hosting multiple grids.

Example

const bus = new EventTarget();
const grid = new GameGrid({ matrix, options: { eventTarget: bus } });
bus.addEventListener(gridEventsEnum.MOVE_LAND, handler);

`Optional`id

id?: string

`Optional`infiniteX

infiniteX?: boolean

`Optional`infiniteY

infiniteY?: boolean

`Optional`injectStyles

injectStyles?: boolean

When true (default), GameGrid.render and GameGrid.refresh inject bundled layout CSS into document.head once (guarded by style[data-gamegrid-styles]). Set false to skip injection and style .gamegrid yourself.

Example

new GameGrid({ matrix, options: { injectStyles: false } }, root);

`Optional`middlewares

middlewares?: { post?: MiddlewareFn[]; pre?: MiddlewareFn[] }

Type Declaration

Optionalpost?: MiddlewareFn[]

Invoked after merge; inspect merged state via GameGrid.getState.
Optionalpre?: MiddlewareFn[]

Invoked synchronously before the patch merges into IState (see MiddlewareFn).

Example

new GameGrid({
  matrix,
  options: {
    middlewares: {
      pre: [(_gg, patch) => { patch.myTick = Date.now(); }],
      post: [(gg) => console.log(gg.getState())],
    },
  },
});

`Optional`moveDebounce

moveDebounce?: number | [number, number, number, number]

Milliseconds to wait before accepting another directional move.

number: shared cooldown for any direction
[Top, Right, Down, Left]: per-direction cooldowns (UP, RIGHT, DOWN, LEFT)

Remarks

Update at runtime via GameGrid.setOptions (no re-render required). Useful for temporary speed boosts such as power-ups.

Example: Shared cooldown

new GameGrid({ matrix, options: { moveDebounce: 120 } });

Example: Per-direction cooldown

grid.setOptions({ moveDebounce: [80, 40, 80, 40] }); // UP, RIGHT, DOWN, LEFT

`Optional`moveOnType

moveOnType?: string[]

Allow-list of enterable ICell.type values when non-empty.

Remarks

Omit or supply [] to allow any cell that passes blockOnType.

`Optional`regionDivisions

regionDivisions?: number

Opt-in region tracking. 2 = quadrants, 3 = ninths, etc.

Remarks

Moves that change tile emit gridEventsEnum.REGION_CHANGE and update IState.region.

Example

const grid = new GameGrid({ matrix, options: { regionDivisions: 2 } });
grid.zoomQuadrant("se");

`Optional`rewindLimit

rewindLimit?: number

Max length of IState.moves. Oldest entries drop first. Values below 1 are treated as 1 (always keep the current cell). Default: 20.

`Optional`rowClasses

rowClasses?: string[]

`Optional`slideZoomOnEdge

slideZoomOnEdge?: boolean

When true with IOptions.regionDivisions, gridEventsEnum.ZOOM_EDGE auto-zooms to the adjacent region tile. Default: false.

Example

new GameGrid({
  matrix,
  options: { regionDivisions: 2, slideZoomOnEdge: true, animateZoom: true },
});

`Optional`wasdControls

wasdControls?: boolean

`Optional`zoomSlideDuration

zoomSlideDuration?: number

CSS transition duration (ms) for zoom slide. Default: 300.

`Optional`zoomViewportClasses

zoomViewportClasses?: string[]

Appended to .gamegrid__viewport whenever zoom is active.

Interface IOptions

Example

Index

Properties

Properties

OptionalactiveClasses

OptionalanimateZoom

OptionalarrowControls

OptionalblockOnType

Optionalcallbacks

Example

OptionalcellClasses

Optionalclickable

OptionalcollideOnType

OptionalconstrainToZoom

Remarks

OptionalcontainerClasses

OptionaleventTarget

Remarks

Example

Optionalid

OptionalinfiniteX

OptionalinfiniteY

OptionalinjectStyles

Example

Optionalmiddlewares

Type Declaration

Optionalpost?: MiddlewareFn[]

Optionalpre?: MiddlewareFn[]

Example

OptionalmoveDebounce

Remarks

Example: Shared cooldown

Example: Per-direction cooldown

OptionalmoveOnType

Remarks

OptionalregionDivisions

Remarks

Example

OptionalrewindLimit

OptionalrowClasses

OptionalslideZoomOnEdge

Example

OptionalwasdControls

OptionalzoomSlideDuration

OptionalzoomViewportClasses

Settings

On This Page

`Optional`activeClasses

`Optional`animateZoom

`Optional`arrowControls

`Optional`blockOnType

`Optional`callbacks

`Optional`cellClasses

`Optional`clickable

`Optional`collideOnType

`Optional`constrainToZoom

`Optional`containerClasses

`Optional`eventTarget

`Optional`id

`Optional`infiniteX

`Optional`infiniteY

`Optional`injectStyles

`Optional`middlewares

`Optional`post?: MiddlewareFn[]

`Optional`pre?: MiddlewareFn[]

`Optional`moveDebounce

`Optional`moveOnType

`Optional`regionDivisions

`Optional`rewindLimit

`Optional`rowClasses

`Optional`slideZoomOnEdge

`Optional`wasdControls

`Optional`zoomSlideDuration

`Optional`zoomViewportClasses