Theseus¶ ↑

Theseus is a library for generating and solving mazes. It also includes routines for rendering mazes (and their solutions) to both ASCII art, and to PNG image files.

There is also an included utility for generating mazes from the command-line.

Note that Theseus requires Ruby 1.9.2 or higher.

Theseus supports the following types of mazes:

• Orthogonal. This is the traditional maze layout of rectangular passages.

• Delta. This maze type tesselates the field into triangles.

• Sigma. The field is tesselated into hexagons.

• Upsilon. The maze field consists of tiled octogons and squares.

Mazes may be generated using any of the following features:

• Symmetry. The maze may be reflected in x, y, x and y, or radially. (Not all maze types support symmetry yet.)

• Randomness. A maze with low randomness will result in many long, straight corridors. Higher randomness gives a maze with more twists and turns.

• Weave. Mazes with high weave will frequently pass over or under existing passages. Low weave mazes will prefer to remain on the same plane.

• Braid. Mazes with high braid will trade dead-ends for circular loops in the maze. Thus, braided mazes will tend to have multiple possible solutions.

• Wrap. Mazes may wrap in x, y, or x and y together. A maze that wraps in any of its dimensions will allow the passages to go from one side of the maze to the other, by moving beyond the far edge of the maze. Another way to think of it is that a maze that wraps in one dimension may be mapped onto a cylinder, and a maze that wraps in both dimensions may be mapped onto a torus.

• Masks. Mazes may be constrained with masks, which are basically boolean grids that define where a passage is allowed to exist. With masks, you can create mazes that fit pre-defined geometry, or wrap around text.

Theseus supports the following output types:

• ASCII. Using the ASCII output, you can simply print a maze to the console to see what it looks like. Not all features can be displayed well in ASCII mode, but it works well enough to see what the maze will be like.

• PNG. Mazes that are rendered to PNG may be highly customized, and even allow you to specify custom paths to be rendered.

Theseus supports the following solution algorithms:

• Recursive Backtracking. This is a fast, efficient algorithm for solving mazes that have no circular loops (e.g. unbraided mazes).

• A* Search. The A* search algorithm really shines with mazes that are highly braided, and is guaranteed to provide you with the shortest path through the maze.

Orthogonal mazes may be converted to their unicursal equivalent. A unicursal maze is one which has only a single path that covers every cell in the field exactly once. This style is maze is often called a “labyrinth”. See Theseus::OrthogonalMaze#to_unicursal for more information.

Theseus is also designed to allow you to step through both the generation of the maze, as well as the computation of the solution. This lets you (for instance) animate the construction (and solution) of the maze by drawing individual PNG frames for each step! And since Theseus includes an implementation of A* Search, this gives you an interesting way to visualize (among other things) how that algorithm works.

Lastly, Theseus can be used to manually build mazes (or any other grid-based structure) by hand. See Theseus::Maze for more information.

Theseus is designed to be super simple to use. Here are some examples:

require 'theseus'

# generate a 10x10 orthogonal maze and print it to the console
maze = Theseus::OrthogonalMaze.generate(width: 10)
puts maze

# render a triangular delta maze to a PNG file
maze = Theseus::DeltaMaze.generate(mask: Theseus::TriangleMask.new(10))
File.open("triangle.png", "w") { |f| f.write(maze.to(:png)) }

# render a highly braided, hexagonally-tiled maze, with its solution
maze = Theseus::SigmaMaze.generate(width: 20, height: 20, braid: 100)
File.open("sigma.png", "w") do |f|
  f.write(maze.to(:png, solution: true))
end

# poor-man's animation of the generation of an octogon/square-tiled maze
maze = Theseus::UpsilonMaze.new(width: 10)
while maze.step
  puts maze
  sleep 0.05
end
puts maze

# emit animation frames showing the solution of a maze
maze = Theseus::OrthogonalMaze.generate(width: 10)
solver = maze.new_solver
step = 0
solver.each do
  File.open("frame-%04d.png" % step, "w") do |f|
    path = solver.to_path(color: 0xff0000ff)
    f.write(maze.to(:png, paths:[path]))
  end
  step += 1
end

See the documentation for Theseus::Maze for information on all of these features.

To use the command-line utility, simply pass the -h flag to the “theseus” utility on the command-line:

$ theseus -h

Theseus requires Ruby 1.9.2, and the ChunkyPNG library.

To install, simply type:

gem install theseus

This will install both the library, as well as the command-line “theseus” tool.

Theseus is created by Jamis Buck. It is made available in the public domain, completely unencumbered by rules, restrictions, or any other nonsense.

Please prefer good over evil.