Repository files navigation

There are a lot of different maze algorithms out there, each with differentproperties, strengths, weaknesses, and interesting points. The aim of thisproject is to develop a library of these algorithms in a format that allowsthe inner structure and behavior of them to be studied and observedvisually, by animating them and allowing students to step through them.

You'll needCoffeeScript installed. Once you'vegot that, you can run:

cake build

This will convert the CoffeeScript sources in the "src" directory, toJavascript files in the "lib" directory.

At this point you should be able to open the demo in examples/maze.html.(A possibly-out-of-date version of the demo can be seenhere, if you want to get an idea of whatcsMazes can do.)

If you want to do a piecemeal installation of your own, you'll need at leastthese files, included in this order:

• mersenne.js
• maze.js

Further, the "widget.js" includes a script for easily embedding maze animationson your page; you just need to add the CSS definitions. (See examples/maze.htmlfor the CSS definitions.)

Once you've included those files, you can include any of the algorithm-specificfiles you want.

Also, these files may be safely combined and minified, if you want to reduceeverything to a single file.

Using the included widget, embedding a maze is as simple as this:

<script type="text/javascript">  Maze.createWidget("Prim", 10, 10)</script>

This would embed a 10x10 grid that will animate Prim's algorithm. You can alsopass an optional object (hash) with properties to customize how the algorithmruns, or how the grid is displayed. These properties are supported:

• id : used to set the id of the created HTML elements. If not specified,the lower-cased algorithm name will be used.
• class : the HTML class attribute to add to the outermost generateddiv. This is in addition to any other classes that the widget itselfassigns (e.g. "maze").
• input : data that should be passed to the maze object upon creation.This should be either a string, in which case it is passed directly to themaze constructor, or a function, in which case it is invoked first andthe return value used as the value passed to the maze. The actual formatof the string is dependent on the algorithm used.
• interval : the delay (in milliseconds) between steps when the mazeis in "run" mode. Defaults to 50ms.
• wallwise : a boolean value indicating whether the maze is to bedisplayed as a passage carver (false) or a wall adder (true). The meaningof the wall queries is inverted when wallwise is true. Most mazesneed to have wallwise set to false (the default), but the RecursiveDivisionalgorithm is a wall adder and needs to be rendered with wallwise set totrue.
• seed : an integer value to use as a seed for the random number generated.Using the same seed for different animation runs (where the algorithm anddimensions are otherwise the same) will always result in the same mazebeing generated.
• rng : the random number generator object to use to generate numbers.You'll almost never need to use this; but it could be handy if you want togenerate a series of mazes with the same original seed. If used, this shouldbe an instance of MersenneTwister (defined in mersenne.coffee), or shouldat least conform to the same interface.
• padded : if true, adds space around each cell. The default is false.
• weave : if true, generates a "weave" maze (where passages move overand under other passages). This is not supported by all algorithms. Forbest results, use withpadded set to true.
• weaveMode : either, "onePhase" (the default), or "twoPhase". OnlyKruskal's algorithm currently supports this setting.
• weaveDensity : A number between 0 and 100 (default 80), with 100meaning "maximum" density". Only used whenweaveMode is set to"twoPhase".

If you're determined to do things the hard way, you can always instantiatethe mazes yourself, setting up the callbacks and rendering things manually.To instantiate a maze:

var maze = new Maze(10, 10, Maze.Algorithms.Prim)

This would create a blank 10x10 grid that will generate a maze using Prim'salgorithm. Mazes are generated either step-wise:

maze.step() // returns false when the maze is completed

Or they can be generated all at once:

maze.generate() // calls step() repeatedly until done

As with the widget helper, the maze constructor accepts an optional finalparameter, an object, whose properties can be used to customize how themaze is built. The following properties are understood (and have the samemeaning as their counterparts in the widget helper):

• input : a string used as input to the algorithm, which can be used tocustomize its behavior. Not all algorithms use this parameter.
• seed
• rng
• weave
• weaveMode
• weaveDensity

To indicate interest in the progress of the maze, you can use the onUpdate andonEvent methods to register callbacks that will be invoked. The onUpdatecallback is triggered every time a cell is changed. The onEvent callback istriggered whenever an algorithm-dependent "event" occurs (e.g. the recursivebacktracker hits a dead-end and has to backtrack). Both callbacks accept threeparameters: the maze object that caused the callback, and the x and y coordinatesthat are relevant.

maze.onUpdate(function(m, x, y) {  // update the display, etc.});maze.onEvent(function(m, x, y) {  // pause the animation, etc.});

csMazes is written by Jamis Buck (jamis@jamisbuck.org) and is made availablein the public domain. Do with it what you will.

But please prefer good over evil.