amaze − GUI to generate and print mazes


amaze [−x columns] [−y rows] [−wall wall-width] [−path path-width] [−stay count] [−cuts count] [−s] [−creep ms] [−option
... ]


The settings, such as colors, can be changed in the GUI. To find out where they are saved between sessions, use: amaze −init
To restore all defaults, and ignore the saved settings, use the −no−restore option.


amaze is a graphical application to generate and print simple mazes. The maze properties (size and look) can be set in the GUI, or preset using command line arguments.

We say a maze consists of a grid of tiles, and a set of walls between those tiles. Between each two neighboring tiles there either is a wall or there is none; if there is none, then the two tiles are said to be connected. When a tile A is connected to tile B, and B to C, then A and C are also connected (through B). We call the sequence of tiles A-B-C a path from A to C. Each maze has a departure tile and a destination tile; the path between these two tiles is called the solution path of the maze (there can only be one such path). The joy and challenge of a maze, traditionally, is to find the solution path through the maze.

The graphical interface shows a set of maze controls and a single maze. The maze is randomly generated each time the maze grid dimensions change (see the "Width" and "Height" controls), and whenever you select the File > New menu item. With the Edit > Show path toggle you can choose whether to display the solution path (the "trail of bread-crumbs", if you will) in the maze on the screen or not. Every time that you switch it on, the path display mode will alternate between steady and animated ("creeping" through the maze). See also option −creep. When you print the maze (using File > Print...) two pages are produced: first the maze without the solution path indicated, and then the maze with a dotted line to show the solution path.

You can use an outline image (a.k.a. "mask") to define the shape of the maze. By default, the maze will fill all of the rectangular grid of available tiles. A mask consist of an image, and a "dead" color. Currently, the dead color is that of the (0,0) pixel of the image. Any pixel in the mask with that color is called a dead pixel. When you define a mask, it is stretched to cover that rectangle, and then all tiles whose middle pixel position corresponds to a dead pixel in the mask are excluded from the maze. So if the mask image is a picture of a cat on a (monochrome!) white background, the maze will have the shape of a cat. You can define the outline image using File > Open outline, or just drag an image (must be a local file) onto the canvas.

Internally, the maze is represented as a set of cells. For square and triangle shaped tiles, one tile equals one cell; for hexagon shaped tiles, each tile is two cells tall; for octagon, one or three. Some notes in the documentation may be unclear if you are not aware of this distinction.

The version of amaze that runs on MS Windows, runs a pure GUI application, without an attached console window. This implies there is no "standard output", so if you want the result of e.g. −init you need to use the −out file option preceding it on the command line.


−x columns

specifies the number of columns of tiles in the maze grid. You can later adjust this in the GUI using the "Width" spin-box or slider.

−y rows

specifies the number of rows of tiles in the maze grid. You can later adjust this in the GUI using the "Height" spin-box or slider.

−p/−path pixels

sets the width, in pixels, of the solution path through the maze, when it is displayed in the GUI (see option −s). You can later adjust this in the GUI using the "Path" spin-box or slider. If the display area is too small, the path may be drawn narrower than this.

−wall pixels

sets the width, in pixels, of the walls in the maze. You can later adjust this in the GUI using the "Wall" spin-box or slider. If the display area is too small, the walls may be drawn narrower than this.

−stay factor

determines how long each step in the maze tries to stay in the same direction. Set to 1, the direction is fully random at each tile; set to N, the chance is 1 in N of being random. Note that fully random mazes tend to have comparatively long solution paths.

−cuts count

will try to add the given number of extra cross-cuts between adjacent cells not on the path. Zero cuts means the maze will not contain loops in paths, and non-zero means some walls may not be attached to the border. The count is an upper bound, the maze may end up with fewer cuts.

−tile shape

shape of maze tiles: triangle, square, hexagon or octagon.

−mask file

will use the image in the file to mask off part of the grid, using the (0,0) pixel’s color as the transparent color. So if you have a picture of something on a monochrome background, you get a maze in the same shape. Special cases for file are "[total]" (no mask), "[round]" (built-in circular shape), and "[heart]" (for Valentine’s Day). If you really must use a file with a name literally starting with "[", prefix it with "[image]".

−path-color color

sets the solution path color. For a detailed discussion of color name formats, see Examples: "steelblue", "#112233".

−tile-color color

sets the tile color. Cf. option −path-color.

−text-color color

sets the message text color. Cf. option −path-color.

−text text

sets the message text. This text will be strung along the solution path (one letter per tile, with random spacing), so that finding the solution will also let you read back the message.

−wall-color color

sets the maze wall color. Cf. option −tile-color.


shows the solution path as a dotted line in the maze display in the GUI.

−cover 0-100

determines what percentage of the path is shown at most during path animation. The path starts growing from the departure point, adding the increment at each step (see option −steps). Once this percentage is hit, the tail end starts retracting towards the destination point.

−creep ms

specifies the interval (in milliseconds) between path animation steps. If the value is zero, the path is not animated at all.

−steps count

will animate the path to move from departure to destination in this many steps. The effective increment per step will be at least one cell.

−out path

redirects the standard normal output to the given file. On MS Windows, you will need this to get any output from e.g. −help or −init.

−err path

redirects the standard error output to the given file. On MS Windows, you will need this to get any non-GUI error messages.

−std path

redirects both the standard normal and error output to the given file. Using both −out and −err on the same file instead is not good, it will cause one to overwrite the other.

−locale locale

explicitly selects a localization string locale. Currently (partially) supported are: "da", "de", "en_GB", "en_US" (= English, USA spelling), "eo", "es", "fr", "nl", and "zh_CN".


strips down the UI to fit on a smaller screen. With this, you can use amaze effectively down to about 320×200 pixels.


shows a splash screen when starting up.


does not show a splash screen when starting up.


ignores any saved settings, reverting to the built-in defaults.


suppresses saving any changes to saved settings.


prints the path to the file where the settings are saved.

Qt Common Options
These come with use of the Qt 4.7 widget libraries.

sets the application GUI style. Possible values are motif, windows, and platinum. If you compiled Qt with additional styles or have additional styles as plug-ins these will be available to the −style command line option.


sets the application stylesheet. The value must be a path to a file that contains the Style Sheet. Note: Relative URLs in the Style Sheet file are relative to the Style Sheet file’s path.


restores the application from an earlier session.


prints debug message at the end about number of widgets left undestroyed and maximum number of widgets existed at the same time


sets the application’s layout direction to Qt::RightToLeft


sets the back-end to be used for on-screen widgets and QPixmaps. Available options are raster and opengl.


tells Qt that it must never grab the mouse or the keyboard. (Qt with QT_DEBUG only.)


running under a debugger can cause an implicit −nograb, use −dograb to override. (Qt with QT_DEBUG only; only under X11.)


switches to synchronous mode for debugging. See Debugging Techniques for a more detailed explanation. (Qt with QT_DEBUG only; only under X11.)


will make the Direct3D paint engine the default widget paint engine in Qt. This functionality is experimental. (On Microsoft Windows only).

X11 Common Options
The X11 version of Qt supports some traditional X11 command line options.

sets the X display (default is $DISPLAY).

−geometry geometry

sets the client geometry of the first window that is shown.

−fn font

defines the application font. The font should be specified using an X logical font description.

−bg color

sets the default background color and an application palette (light and dark shades are calculated).

−fg color

sets the default foreground color.

−btn color

sets the default button color.

−name name

sets the application name.

−title title

sets the application title.

−visual TrueColor

forces the application to use a TrueColor visual on an 8-bit display.

−ncols count

limits the number of colors allocated in the color cube on an 8-bit display, if the application is using the QApplication::ManyColor color specification. If count is 216 then a 6×6×6 color cube is used (i.e. 6 levels of red, 6 of green, and 6 of blue); for other values, a cube approximately proportional to a 2×3×1 cube is used.


causes the application to install a private color map on an 8-bit display.


sets the input method server (equivalent to setting the XMODIFIERS environment variable)


defines how the input is inserted into the given widget, e.g., onTheSpot makes the input appear directly in the widget, while overTheSpot makes the input appear in a box floating over the widget and is not inserted until the editing is done.


Amaze returns non-zero only on fatal internal errors or invalid command line parameters.


Command line argument errors are reported to standard error output. User problems while using the GUI are normally displayed in localized modal dialog windows.


No environment variables are used to configure the application part of this program. The linked libraries (for Qt, and X11 under Linux) may have environment variable dependencies.


Note the file paths given here are for Ubuntu, and may be different on other platforms.


− the Qt localization files


− for the desktop menu


− copyright and such


− desktop and application menu icons


− this manual page


− the executable


− the settings saved between runs for this user

− where the update check looks for the current version and release number

See option −init for the system-specific, per-user file used to save settings between sessions.


This is the second version, 1.1. (The first version, 1.0, is now obsolete.) It is available at as source (via CVS), as an Ubuntu/Debian package, and as a Windows XP MSI file.


Amaze tries to follow the GUI guidelines and Qt samples in the Qt 4.5-4.7 documentation, the Gnome guidelines for the ".desktop" file, and the WiX recommendations for the MSI installer.


Also, generating mazes is not exactly a new or challenging topic in itself, but fun enough to use as the subject of a project for me.

For more details on open issues and ongoing changes, visit the project tracker at, or retrieve the sources through CVS there and look at the file amaze/TODO.

To do
− Move printing job to separate thread, with progress bar. Currently it runs on the main thread, which could hang if the printing process is blocked.
− We force the maze to fit in the display area. This makes it easy to resize, but limits the user to making mazes that will fit on the screen.
− This manual page is only available with the Ubuntu package, we should include a PDF for the Windows MSI.

− I’ve got partial localization done for [da], [de], [eo], [es], [fr], [nl], [zh_CN] but I’m sure the translations don’t follow all conventions, and some are incomplete.
− The non-"Comment" entries in the amaze.desktop file have not been localized yet. Ditto for the text printed by the "-help" option.

Output formats
− Output to animated GIF with the solution path winding through the maze. Or ditto but to sequence of files, for later composition. We now support path animation on the screen, but not in export.

− Currently the user has no control over the dot and dash pattern of the solution path.


− File>Export is a bit weird: it has no "All files (*.*)" filter, leaves a transparent border if the screen area is bigger than the maze picture, and could use more polish.
− File>Blend, File>Maya and File>Virtual are experimental and not quite complete; they export a Blender Python script, a Maya MEL script, and an X3D/VRML file respectively. These lack tile floors, don’t show the solution path, and for MEL lose the colors.
− The exported images include the empty space in the canvas window, instead of being neatly trimmed down.
− If you pick the departure point to be right next to the destination, the solution path may not enter the maze at all. If they are on opposite sides of the same corner, the corner can appear invisible because it has no border wall on the outside.
− In PostScript print, the line caps stick out a bit. We should probably rewrite the wall drawing code a lot; currently it just draws each segment separately, which means the corners are not drawn according to the pen join mode (bevel, miter, whatever).
− To get better solutions, we prune any loops in the solution after generating the initial maze. This improves the average solution (70-90% reduction in length) but may make small mazes boring. Maybe the loop reduction factor should be adjustable.
− The loop pruning does not eliminate horizontal loops in hexagon or octagon mazes unless the top and bottom part run in immediately adjacent cell rows.
− Mazes with hexagon-shaped tiles may run off the page when printing them.
− For mazes with triangle tiles, the "stay" does not work well; currently a continuous diagonal line of tiles equals an alternating path of horizontal and vertical steps in the cell grid, which gets low probability for a higher stay value. So, you just get more horizontal lines.
− Mazes with exactly one column or one row of tiles may turn out strange.
− Further bugs and blemishes can be found recorded in the bug reports and feature request tickets at


amaze −no−splash −s


tinco at SourceForge