README

Maze Generator & Solver

A terminal CLI tool that generates random mazes using multiple algorithms, renders them as ASCII art, and solves them with animated pathfinding. Pure Node.js, zero npm dependencies.

Quick Start

bash

# Generate a maze
node src/cli.js generate

# Solve a maze with animation
node src/cli.js solve --animate

Installation

No installation required. Just clone and run:

bash

cd projects/018-maze-generator/3-development

Verify it works:

bash

node src/cli.js generate --width 10 --height 10

Usage

Commands

shell

maze generate [options]    Generate a new maze
maze solve [options]       Solve a maze (generates new if no input)
maze export [format]       Export maze to file (json or txt)

Options

Flag	Alias	Description	Default
`--width`	`-w`	Maze width in cells	20
`--height`	`-h`	Maze height in cells	10
`--algorithm`	`-a`	Generation algorithm: `backtrack`, `prim`, `kruskal`	backtrack
`--solver`	`-s`	Solving algorithm: `bfs`, `dfs`, `astar`	bfs
`--seed`		Random seed for reproducibility	None
`--animate`		Show solving animation	false
`--delay`		Animation delay in ms	50
`--no-color`		Disable colored output	false
`--format`	`-f`	Output format: `json`, `txt`	json
`--input`	`-i`	Input file (for solve/export)	None
`--output`	`-o`	Output file	stdout

Examples

Generate a 15x15 maze with a seed:

bash

node src/cli.js generate --width 15 --height 15 --seed 42

Generate a maze with Prim's algorithm:

bash

node src/cli.js generate --algorithm prim --width 20 --height 10

Solve a maze using A* algorithm:

bash

node src/cli.js solve --solver astar --width 15 --height 15

Solve with animated output:

bash

node src/cli.js solve --solver bfs --animate --delay 50

Save maze to file:

bash

node src/cli.js generate --width 20 --height 10 --output maze.txt

Load a maze from file and solve:

bash

node src/cli.js solve --input maze.json --solver astar --output solution.txt

Export to JSON:

bash

node src/cli.js generate --width 10 --height 10 --format json --output maze.json

Sample Output

shell

$ node src/cli.js generate --width 5 --height 5
+---+---+---+---+---+
| S |   |   |   |   |
+---+   +   +   +   +
|   |   |   |   |   |
+---+---+   +   +   +
|   |   |   |   |   |
+---+   +---+   +   +
|   |   |   |   |   |
+---+---+   +---+   +
|   |   |   |   | E |
+---+---+---+---+---+

Algorithms

Generation

Recursive Backtracking: Creates mazes with long, winding passages
Prim's Algorithm: Creates mazes with more branching
Kruskal's Algorithm: Creates mazes with many cycles (more open)

Solving

BFS (Breadth-First Search): Always finds the shortest path
DFS (Depth-First Search): Finds a path quickly but not necessarily optimal
A* (A-Star): Uses heuristics to find shortest path efficiently

Error Messages

Invalid Algorithm

shell

Error: Invalid algorithm: invalid. Valid options: backtrack, prim, kruskal

Cause: The specified generation algorithm is not recognized. Resolution: Use one of: backtrack, prim, or kruskal.

Invalid Solver

shell

Error: Invalid solver: invalid. Valid options: bfs, dfs, astar

Cause: The specified solving algorithm is not recognized. Resolution: Use one of: bfs, dfs, or astar.

Invalid Dimensions

shell

Error: Width and height must be at least 1

Cause: Width or height is set to 0 or negative. Resolution: Set both width and height to at least 1.

Invalid Input File

shell

Error: Failed to load maze from input.json: ENOENT: no such file or directory

Cause: The specified input file doesn't exist. Resolution: Check that the file path is correct.

Invalid Format

shell

Error: Invalid format: xml. Valid options: json, txt

Cause: The specified export format is not supported. Resolution: Use json or txt.