@thewizardbear/maze_generator

maze_generator

maze_generator is a Javascript module for easily generating mazes.

---

⚠️ This module is work-in-progress, so much of it is unstable.

Feedback is welcome. The best way to provide feedback is to open an issue.

---

This module is heavily influenced by Jamis Buck's Coffeescript mazes. It is structured a little differently though and is written entirely in Javascript rather than Coffeescript. It also functions as a module, rather than a library. I aim to eventually add all the functionality that Jamis's CS maze library has.

Importing the module

In the browser and in Deno

If you are inside a Javascript module file or a type="module" script tag, then add the following to the top of your code:

import {Maze} from "https://x.nest.land/maze_generator@0.4.0/mod.js";

If not, you can use the dynamic import() function. For example:

let Maze;
import("https://x.nest.land/maze_generator@0.4.0/mod.js")
  .then(module => {
    Maze = module.Maze;
  })
  .catch(error => {
    console.log(`Error loading maze_generator module: ${error}`)
  })

You can also import the module from deno.land/x if you prefer: https://deno.land/x/maze_generator@v0.4.0/mod.js. (Note the v here, which is not present when importing from nest.land.)

In Node

Run:

npm install @thewizardbear/maze_generator

And then import the maze_generator module in your code by adding the following to the top of every file that uses it:

import {Maze} from "@thewizardbear/maze_generator";

Alternately, you can use require:

const {Maze} = require("@thewizardbear/maze_generator")

Please note that Node version 14+ is required as maze_generator makes use of some ES2020 features such as the nullish coalescing operator (??).

Example Usage

import {Maze} from "https://x.nest.land/maze_generator@0.4.0/mod.js"

const mazeSettings = {
  width: 12,
  height: 12,
  algorithm: "recursive backtracker"
}

//initialize the maze
const m = new Maze(mazeSettings);

//generate it
m.generate();

//print the maze to the console
m.printString();

Other examples

See the examples folder for more examples.

Also see this OpenProcessing sketch.

new Maze()

To create a new maze, use new Maze(). You can optionally pass in an object with the settings (see below).

Maze settings object

These are all the properties of the object you can pass in when you write new Maze(mazeSettings)

Property	Description	Valid Values	Default Value
width (or xSize)	The width of the maze. (How many columns there should be.)	A positive integer.	height or 30
height (or ySize)	The height of the maze. (How many rows there should be.)	A positive integer.	width or 30
algorithm	The algorithm to use.	Any one of the following: "recursive backtracker", "eller's", "sidewinder", "kruskal's", "simplified prim's", "modified prim's", "true prim's", "hunt and kill", "binary tree", "aldous broder", "recursive division", "wilson's", "10 print", "growing tree", "random" (random algorithm). This isn't case sensitive. Characters other than the letters a-z and digits 0-9 are ignored.	"recursive backtracker" ("prim's" defaults to "true prim's")
cellSelectionMethod	Cell selection method for "growing tree" algorithm.	An object with one or more of the following properties: newest (recursive backtracker), oldest, middle, random (simplified Prim's) with the weight (probability) as the values. Alternatively, you can just use one cell selection method, and pass in the string (e.g. "middle").	"random" (simplified Prim's)
start	Where to start the maze generation from (if there is an option).	An object with both an x and y property (both integers) or a string referencing a certain point ("random" or a certain side or corner such as "north east")	"random" for all algorithms except Eller's, binary tree and sidewinder, which are all {x: 0, y: 0}.
entrance	Where the solution should start from.	An object with both an x and y property (and an optional direction property: "N", "S", "E", or "W") or a string referencing a certain point ("random" or a certain side or corner such as "north east")	"top left"
exit	Where the solution should end.	An object with both an x and y property (and an optional direction property: "N", "S", "E", or "W") or a string referencing a certain point ("random" or a certain side or corner such as "north east")	"bottom right"
seed	The seed for the random number generator. Mazes with the same seed (and all the other settings that affect generation are the same) will always generate exactly the same.	A number or string	If no seed is given a unique one will be generated (using Date.now()).
prng	The pseudo-random number generator used during maze generation. This is useful if you want to use your own random number generator function. You can also set prng to Math.random.	A function that when given no arguments returns a number that is between 0 and 1 (including 0 but not including 1).	seedrandom(seed) (using David Bau's seedrandom package)
selectNeighbor	A function that picks which neighbor a cell should connect to. This can be used for direction bias (e.g. making it more likely to have horizontal connections rather than vertical connects). Currently it only works for some algorithms: 10 print, binary tree, hunt and kill, recursive backtracker/depth-first search, sidewinder (and wilson's and aldous-broder if the same direction isn't chosen too much)	A function that takes in the neighbors that can be connected to (each of them in the form of an object with x, y and direction properties), as well as the random function that should be used, and returns one of neighbors.	(neighbors, random) => neighbors[Math.floor(random() * (neighbors.length))]

You can also use the size property instead of width and height to set both dimentions.

.step()

Call .step() to advance the maze one step.

Returns true if the maze hasn't finished generating yet and false if there are no more steps left to take. You can also check if a maze has finished generating with .finishedGenerating, which is a boolean value.

.generate()

This method calls .step() repeatedly until the maze has finished generating (or it has given up). Returns the finished maze

.display()

This is the function which displays the maze.

Note that this function (currently) only works in a html document with a canvas element.

It optionally takes in an object with the properties listed below.

Property	Description	Valid Values	Default Value
canvas	The canvas to display the maze on.	A canvas element (e.g. document. getElementsByTagName("canvas")[0]).	The first canvas element in the html.
coloringMode	How the cells are colored.	"normal": regular coloring, "distance": each cell is colored by a distance from a point . More coloring modes coming soon hopefully. Anything other than the valid values specififed defaults to normal coloring.	"normal"
colorScheme	The color scheme to use when coloringMode is not "normal".	This can either be "grayscale", "rainbow" or an array or hex codes.	"rainbow"
mainColor	This is the color of the walls (or line).	A hex value as a string	"#000"
backgroundColor	Background color and color of the space between walls (unless colorMode isn't "normal")	A hex value as a string	"#FFF"
antiAliasing	Whether or not to apply anti-aliasing to the image drawn on the canvas (imageSmoothingEnabled). Setting it to false gives crisp edges but it can distort the output for small canvases where the cells do not line up with the canvas pixels well.	true or false	false
showSolution	Whether or not to show the solution when the maze is complete	true or false	false
solutionColor	The color of the solution if showSolution is true	A hex value as a string	"#F00"
lineThickness	The thickness of the lines drawn, as a proportion of the cell size	A number between 0 and 1	0.35
removeWallsAtEntranceAndExit	Whether or not the walls should be removed at the entrance and exit of the maze. Note that this doesn't change the maze, it just means these walls won't be displayed.	true or false	true
lineCap	Changes the lineCap canvas context property.	"butt", "round" or "square"	"square"
distanceFrom	Where the distance should be measured from if displayMode is set to "distance"	A valid cell position or "solution"	The start cell
asLine	Whether the maze should be displayed as a line or as walls.	true or false	false

.display() example usage

const kruskalMaze = new Maze({
  width: 20,
  height: 20,
  seed: 100,
  algorithm: "Kruskal's"
}).generate();

kruskalMaze.display({
  canvas: document.getElementById("maze-canvas"), //Replace this with your canvas element you want to display the maze on.
  lineThickness: 0.5 //this sets the walls to be the same size as the paths
})

This will display a maze that looks like this:

.printString()

Prints out the maze as a string to the console.

.printString() example usage

Basic code

new Maze({
  width: 10,
  height: 10
}).generate().printString()

Example output

 ___________________
|__  _____|   |  __ |
|   | ______|___| __|
| |_|__ |   |_  |__ |
|  _____| |__ | | __|
| |  _____|  _| |_  |
|_  |___  __| |  _| |
| | |   |____ | |  _|
|  _| | |_   ___| | |
| | |_|_  |_|  ____ |
|_______|_____|_____|

Maze.createWidget()

Maze.createWidget() is work-in-progress and particuarly unstable.

Call Maze.createWidget() somewhere with access to the document API (the browser) and it should add a little interactive animated HTML widget to your page that looks something like this:

It takes in three properties, all optional.

1. Maze settings object (see new Maze())
2. Display settings object (see .display())
3. Maze widget settings object (see below)

Maze widget settings object

Property	Description	Valid Values	Default Value
paused	Whether the generation should be animated when the maze starts.	true or false	false
imageButtons	Whether the buttons should be images (true) or text (false). This is still a bit dodgy at the moment.	true or false	false
containerElement	The element that the maze widget should be placed inside of	A HTML element	An element with the id or class maze-widget-container, or if none is found the body of the HTML document.

Example code

<div id="prims-demo"></div>
<script>
  import("https://x.nest.land/maze_generator@0.4.0/mod.js")
    .then(({Maze}) => {
      const mazeSettings = {
        algorithm: "true prims"
      }

      const widgetSettings = {
        paused: true,
        containerElement: document.getElementById("prims-demo")
      }

      Maze.createWidget(mazeSettings, {}, widgetSettings)
    })
    .catch(error => {
      document.getElementById("prims-demo").innerHTML = `Error loading maze_generator module: ${error}`
    })
</script>

.braid()

This method braids the maze, removing all dead ends. It returns the maze object so it can be chained.

Try:

import {Maze} from "https://x.nest.land/maze_generator@0.4.0/mod.js";

const mz = new Maze({algorithm: "modified prims", size: "10"}).generate();

//outputs a modified prims maze
mz.printString();

mz.braid();

//outputs the same maze but with all the dead ends removed
mz.printString();

.getSolution()

This is a method that returns the solution to the maze in the form of an array of cell positions.

You can optionally pass in a start and end point, but it will default to the top left and bottom right of the maze.

Try console.log(new Maze().generate().getSolution()).