Maze API

The Maze interface coordinates one grid and its active generation or solving player. Create an instance with createMaze() rather than constructing the lower-level runtime class.

createMaze()

Creates a maze with an optional seed and configurable grid topology.

declare function createMaze(options?: CreateMazeOptions): Maze

interface CreateMazeOptions {
  grid?: MazeGridOptions
  seed?: string | number
}

Example

import { createMaze } from 'mazely'

const maze = createMaze({
  grid: {
    type: 'square',
    rows: 15,
    cols: 25,
  },
  seed: 'example',
})

When grid is omitted, the factory creates a 21 × 21 square grid.

Grid Options

type MazeGridOptions
  = | {
    type: 'square'
    rows: number
    cols: number
    mask?: readonly (readonly boolean[])[]
  }
  | {
    type: 'triangle'
    layout: 'triangle'
    size: number
    mask?: readonly (readonly boolean[])[]
  }
  | {
    type: 'triangle'
    layout: 'rectangle'
    rows: number
    cols: number
    mask?: readonly (readonly boolean[])[]
  }

All dimensions must be positive integers. A triangular boundary's size is the number of smallest triangles on every outer side and produces size² cells within a triangular boundary. A rectangular boundary uses rows and cols for a grid made from triangular cells. When provided, mask is indexed as mask[row][column] and must leave at least one active cell.

maze.grid

The grid owned by the instance:

interface Maze {
  readonly grid: MazeGrid<GridCell>
}

The object remains stable for the lifetime of the maze. Algorithms and editing methods change edge state and cell metadata inside it.

maze.generate()

Starts a generation algorithm and returns its player:

interface MazelyGenerateOptions {
  start?: MazePoint
}

interface Maze {
  generate: (
    algorithm: MazeGenerationAlgorithm,
    options?: MazelyGenerateOptions,
  ) => StepPlayer<MazeGenerationStep>
}

const player = maze.generate('dfs', {
  start: { x: 0, y: 0 },
})

Starting generation clears previous solve state and initializes edges for the selected algorithm. A start point affects only algorithms whose capability has usesStart: true.

See Generation Algorithms for supported IDs and behavior.

maze.solve()

Starts a point-to-point solver:

interface Maze {
  solve: (
    algorithm: Exclude<MazeSolvingAlgorithm, 'flood'>,
    options: {
      start: MazePoint
      end: MazePoint
    },
  ) => StepPlayer<MazeSolvingStep>
}

const player = maze.solve('bfs', {
  start: { x: 0, y: 0 },
  end: { x: 20, y: 20 },
})

Flood fill uses an overload without an end point:

interface Maze {
  solve: (
    algorithm: 'flood',
    options: { start: MazePoint },
  ) => StepPlayer<MazeSolvingStep>
}

Generation playback must finish before solving begins. Starting a solver clears previous solve.* cell metadata.

Playback Shortcuts

The maze delegates these methods to its active player:

interface Maze {
  next: (count?: number) => boolean
  prev: (count?: number) => boolean
  reset: () => void
}

maze.next(5)
maze.prev(2)
maze.reset()

They throw when generation or solving has not created a player. Access the returned StepPlayer when you need its progress, steps, or finish() method.

maze.getState()

Returns a snapshot of the current lifecycle and playback state:

interface Maze {
  getState: () => MazelyState
}

See Events and State for the full shape and event behavior.

maze.getSolveResult()

Reads the current solve result:

interface Maze {
  getSolveResult: () => SolveMazeResult | undefined
}

Returns undefined before a solver is selected. Point-to-point results contain an ordered path from start to end. Flood results contain an empty path and the number of reachable cells visited.

Editing Methods

The instance exposes:

interface Maze {
  edit: (callback: (editor: MazeEditor) => void) => void
  setEdgeOpened: (edgeId: string, opened: boolean) => void
  setEdgeOpenedBetween: (
    from: MazePoint,
    to: MazePoint,
    opened: boolean,
  ) => void
  openCell: (point: MazePoint) => void
  closeCell: (point: MazePoint) => void
  openAllEdges: () => void
  closeAllEdges: () => void
  clearSolveState: () => void
}

See Editing for validation, transaction, and lifecycle rules.

Event Methods

interface Maze {
  on: (
    event: MazeEventName,
    handler: MazeEventHandler,
  ) => () => void
  off: (
    event: MazeEventName,
    handler: MazeEventHandler,
  ) => void
}

See Events and State for event names and payloads.