Micromouse Maze File Collection

Over the years, I have collected quite a lot of micromouse maze files. These are all for the 16×16 classic contest. Several people have asked for copies of these so I have put the entire collection on github. https://github.com/micromouseonline/micromouse_maze_tool

File Formats

There are three types of maze file here, each in their own subdirectory.

Binary

Binary mazes have the file extension .maz are exactly 256 bytes in size. Each byte holds the wall information for a single cell. Each wall is represented by one bit using the following masks:

Thus, a cell with walls in the WEST and SOUTH directions would have the value 0x0C.

Note that internal walls are stored twice. If a cell has a wall to the East, the neighbour in that direction has a wall to the West. This redundancy greatly simplifies the use of the information and can be used to validate the maze data. When adding or removing a wall from the maze array, care must be taken to ensure both ‘sides’ get updated.

Conventionally, the start cell in a classic maze is in the bottom left corner with a single exit heading North. In the binary maze format, this is cell 0, the next byte is cell 1, the cell immediately to the North of the start cell. The cell to the East of the start cell is numbered cell 16.

There are other formats in use. If you come across a maze file from another source, take care to examine it for its layout. In a valid maze, using the definitions above the start cell always has the value 0x0E.

A fairly common alternative places the start cell in the top left with the exit facing East. For tese files, the first cell might contain 0x0D. There is no guarantee, however, that the bit values for each direction are the same. Generate a hex dump of the file and look at the values. It should be possible to figure out the format without too much effort.

A hex dump of a typical binary maze file, using the ‘standard’ format, looks like this:

Text

Text mazes have the extension .txt. They are a directly printable view of the mazestored as ASCII text. For convenience, they have the start cell in the lower left corner. Printing a maze with a single character for each wall makes it very difficult to read because of the aspect ratio of typical printed text. The text files in this repository all use three characters for horizontal walls. The files all have at least 2178 characters. Optionally, it would be possible to store descriptive text after the maze walls. that is not done in these files.

A text version of the maze data above looks like this:

C definitions

To use the maze data in a program, it would be inconvenient to have to read it in from a file. For convenience, each maze is also available as a C language file. The folder cfiles holds all the mazes in this form. You can include the file directly into code or add one or more of the cfiles to your program build. The data is stored as an array of unsigned characters which should be 8 bits wide on most systems. The byte order is exactly the same as it the corresponding binary maze file. that is, the first byte is the start cell, the next is the cell immediately to the North. The array name is derived from the name of the original binary maze. The cfile version includes a text representation in a comment so that you can easily visualise the data. here is the same maze data again, as found in the file 1stworld.c

mazetool

The mazetool program is used to read, check and convert maze files. It will read the binary maze format described above and it will try to read text format maze files with up to 3 characters used for horizontal walls. No attempt is made to read the C definition files.

The name of one maze file must be provided on the command line. If wildcards are used, only the first named file is processed.

Its default behaviour is to read the file and convert to text format, sending the output to stdout. So you could use a line like

to display a binary maze on the terminal in human-readable, printable format.

Command line options are used to determine the output format:

Because output is sent to stdout, it can be redirected to a file. For example:

will read the text maze and create a C definition file.

Creating binary files requires an output file name since dumping raw binary to the terminal is rarely a good thing. To generate a binary maze from a text maze, you might use:

Other operations (NOT IMPLEMENTED)

TODO: mazetool can also inspect the data in a maze file to try and determine its validity and display some other information about the maze. Currently, the inspection verifies that

• there are walls around the edge of the maze
• the start cell has one exit to the North
• the goal area is not walled in
• every wall is present from both sides

finding duplicate mazes

If you have a collection of maze files and wish to check for duplicates, you do not need mazetool. The simplest way to do this, if your operating system has the appropriate tool installed, is to generate a SHA1 checksum for each maze file, sort the results on the checksum and look for duplicate checksum values.

On linux and mac systems you might use:

A partial output from that, on my system gives:

It is clear that the japan2007ef and uk2011f mazes are the same.

You can’t fool shasum. If they are different by even one bit, the sha1 checksum will be different.

I will need suggestions from others for a suitable method on Windows systems.

Bulk Conversions

The bash scripth convert.sh will process al the binary maze files in a folder and convert them to both text and cfile format.

The destination folder names are hard-coded into the script and will need editing before use. Windows users will, I am afraid have to make their own arrangements. Anyone reading this who would like to contribute Windows scripts should feel free to do so.