Knossos
Knossos is a simple and flexible Rust library and CLI tool for generating mazes using various algorithms. It includes built-in utilities for rendering mazes as ASCII, images, or game maps and supports saving them in multiple formats.
Reference
In Greek mythology, King Minos dwelt in a palace at Knossos. He hired the Athenian architect, mathematician, and inventor Daedalus to design his palace and so cleverly was it constructed that no one who entered could find their way back out without a guide. In other versions of this same story it was not the palace itself which was designed in this way but the labyrinth within the palace which was built to house the half-man/half-bull the Minotaur. In order to keep Daedalus from telling the secrets of the palace, Minos locked him and his son Icarus in a high tower at Knossos and kept them prisoner. Daedalus fashioned wings made of wax and bird's feathers for himself and his son, however, and escaped their prison but Icarus, flying too close to the sun, melted his wings and fell to his death.
Source: https://www.worldhistory.org/knossos
Overview
Knossos currently supports only one type of mazes: orthogonal, which is a standard maze layout of rectangular passages.
The library supports the following generation algorithms:
- Aldous-Broder
- Binary Tree
- Eller's
- Growing Tree
- Hunt-and-Kill
- Kruskal's
- Prim's
- Recursive Backtracking
- Recursive Division
- Sidewinder
Knossos supports the following output types:
-
ASCII With the ASCII output option, you can effortlessly display a maze on the console or save it to a file to visualize its appearance.
-
Game map If you are looking to create your own game featuring pseudo 3D graphics or testing your ray casting algorithm implementation, you can transform a maze into a game map using this formatter. It offers various configuration options, including the
spanvalue for specifying the distance between opposing walls, the characterswallandpassagefor map construction, and the ability to randomly place startSand goalGpoints along the borders. -
Image Utilizing the Image output feature, you have the capability to render a maze into PNG or JPG formats (simply utilize the appropriate filename extension). This output type offers extensive customization options, enabling you to define custom margins, wall and passage widths, as well as background and foreground colors.
Installation
Run the following Cargo command in your project directory:
cargo add knossos
Or add the following line to your Cargo.toml:
[dependencies]
knossos = "1.2.0"
Usage
Knossos is designed to be super easy and convenient to use. Here are some usage examples of how to generate, display and save mazes:
Generate with Default Parameters
use *;
let maze = new.build;
Generate with Custom Parameters
use *;
let maze = new
.height
.width
.algorithm
.build;
Display Mazes
use *;
let maze = new.build;
println!;
Save to File
use *;
let maze = new.build;
// Save as ASCII text
maze.save.unwrap;
// Save as a game map (with adjustable span size)
maze.save.unwrap;
// Save as a PNG image (adjusting wall and passage sizes)
maze.save.unwrap;
Format for Further Processing or Logging
use *;
let maze = new.build;
// Convert to ASCII text
let ascii = maze.format.into_inner;
// Convert to a game map
let game_map = maze.format.into_inner;
// Convert to an RGB image buffer
let rgb_image = maze.format.into_inner;
You can find more examples in the examples directory. To run the example:
Seeding for Deterministic Mazes
By default, each generated maze is randomized, producing a different layout every time. However, you can use a seed value to ensure that the same maze is generated consistently across runs. This is useful for debugging, testing, or sharing the exact same maze with others.
use *;
// Generate a maze with a fixed seed
let maze = new.seed.build;
Passing None as the seed (or omitting the .seed() method) will result in a random maze each time.
Benchmarks
Knossos uses Criterion.rs for statistical benchmarking.
Running Benchmarks
To run benchmarks locally:
This generates both terminal output and an HTML report in:
📂 target/criterion/report/index.html (Open in a browser for graphs and analysis)
Summary of Recent Benchmarks
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
(Benchmarks were run on an Apple M1 Max, Rust 1.84.0, Criterion 0.5.1)
CLI
A command-line interface for generating mazes in the terminal uses the library's public API.
Examples
| | | |
| | | | |
| | | | |
| | | | | |
| | |
#######S########
#..#...........#
#..#...........#
#..#..#######..#
#..#........#..#
#..#........#..#
#..#........#..#
#..#........#..#
#..#..####..#..#
#.....#.....#..#
#.....#.....#..#
#######..####..#
#..............#
#..............#
################
Installation
Debian package:
- Download the latest binary
dpkg -i <binary-name>will install it
Or from crates.io:
Or from source:
Usage
)
Using generate command:
)
)
--bias[=<BIAS>]
--growing-method[=<GROWING_METHOD>]
)
For more info, run