<p align="center"> <img src="assets/daedalus.png?raw=true" width="400" height="400"> </p>

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 span value for specifying the distance between opposing walls, the characters wall and passage for map construction, and the ability to randomly place start S and goal G points 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 knossos::maze::*;

let maze = OrthogonalMazeBuilder::new().build();

Generate with Custom Parameters

use knossos::maze::*;

let maze = OrthogonalMazeBuilder::new()
 .height(10)
 .width(10)
 .algorithm(Box::new(GrowingTree::new(Method::Random)))
 .build();

Display Mazes

use knossos::maze::*;

let maze = OrthogonalMazeBuilder::new().build();
println!("{}", &maze);

Save to File

use knossos::maze::*;

let maze = OrthogonalMazeBuilder::new().build();

// Save as ASCII text
maze.save("output/maze.txt", AsciiNarrow).unwrap();
// Save as a game map (with adjustable span size)
maze.save("output/maze_game_map.txt", GameMap::new().span(3)).unwrap();
// Save as a PNG image (adjusting wall and passage sizes)
maze.save("output/maze.png", Image::new().wall(10).passage(30)).unwrap();

Format for Further Processing or Logging

use knossos::maze::*;

let maze = OrthogonalMazeBuilder::new().build();

// Convert to ASCII text
let ascii = maze.format(AsciiNarrow).into_inner();
// Convert to a game map
let game_map = maze.format(GameMap::new()).into_inner();
// Convert to an RGB image buffer
let rgb_image = maze.format(Image::new().wall(10).passage(30)).into_inner();

You can find more examples in the examples directory. To run the example:

cargo run --example mazes

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 knossos::maze::*;

// Generate a maze with a fixed seed
let maze = OrthogonalMazeBuilder::new().seed(Some(40)).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:

cargo bench

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

aldous_broder/generate_10_x_10
                        time:   [43.817 µs 43.930 µs 44.047 µs]
Found 2 outliers among 100 measurements (2.00%)
  1 (1.00%) high mild
  1 (1.00%) high severe

aldous_broder/generate_100_x_100
                        time:   [13.019 ms 13.353 ms 13.691 ms]

binary_tree/generate_10_x_10
                        time:   [4.0313 µs 4.0335 µs 4.0364 µs]
Found 4 outliers among 100 measurements (4.00%)
  4 (4.00%) high severe

binary_tree/generate_100_x_100
                        time:   [396.58 µs 396.83 µs 397.15 µs]
Found 9 outliers among 100 measurements (9.00%)
  1 (1.00%) high mild
  8 (8.00%) high severe

sidewinder/generate_10_x_10
                        time:   [1.6094 µs 1.6107 µs 1.6122 µs]
Found 10 outliers among 100 measurements (10.00%)
  4 (4.00%) high mild
  6 (6.00%) high severe

sidewinder/generate_100_x_100
                        time:   [144.00 µs 144.46 µs 145.25 µs]
Found 12 outliers among 100 measurements (12.00%)
  7 (7.00%) high mild
  5 (5.00%) high severe

growing_tree_method_oldest/generate_10_x_10
                        time:   [11.093 µs 11.102 µs 11.111 µs]
Found 7 outliers among 100 measurements (7.00%)
  3 (3.00%) high mild
  4 (4.00%) high severe

growing_tree_method_oldest/generate_100_x_100
                        time:   [1.1500 ms 1.1513 ms 1.1528 ms]
Found 7 outliers among 100 measurements (7.00%)
  4 (4.00%) high mild
  3 (3.00%) high severe

growing_tree_method_newest/generate_10_x_10
                        time:   [10.468 µs 10.475 µs 10.483 µs]
Found 10 outliers among 100 measurements (10.00%)
  3 (3.00%) high mild
  7 (7.00%) high severe

growing_tree_method_newest/generate_100_x_100
                        time:   [996.60 µs 1.0059 ms 1.0166 ms]
Found 7 outliers among 100 measurements (7.00%)
  3 (3.00%) high mild
  4 (4.00%) high severe

growing_tree_method_middle/generate_10_x_10
                        time:   [11.239 µs 11.249 µs 11.260 µs]
Found 3 outliers among 100 measurements (3.00%)
  2 (2.00%) high mild
  1 (1.00%) high severe

growing_tree_method_middle/generate_100_x_100
                        time:   [1.1787 ms 1.1901 ms 1.2028 ms]
Found 8 outliers among 100 measurements (8.00%)
  2 (2.00%) high mild
  6 (6.00%) high severe

growing_tree_method_random/generate_10_x_10
                        time:   [12.823 µs 12.937 µs 13.075 µs]
Found 5 outliers among 100 measurements (5.00%)
  2 (2.00%) high mild
  3 (3.00%) high severe

growing_tree_method_random/generate_100_x_100
                        time:   [1.5642 ms 1.5756 ms 1.5882 ms]
Found 7 outliers among 100 measurements (7.00%)
  3 (3.00%) high mild
  4 (4.00%) high severe

kruskal/generate_10_x_10
                        time:   [10.254 µs 10.359 µs 10.506 µs]
Found 5 outliers among 100 measurements (5.00%)
  2 (2.00%) high mild
  3 (3.00%) high severe

kruskal/generate_100_x_100
                        time:   [46.782 ms 47.199 ms 47.617 ms]

prim/generate_10_x_10   time:   [10.027 µs 10.035 µs 10.044 µs]
Found 2 outliers among 100 measurements (2.00%)
  1 (1.00%) high mild
  1 (1.00%) high severe

prim/generate_100_x_100 time:   [2.6863 ms 2.6995 ms 2.7130 ms]
Found 1 outliers among 100 measurements (1.00%)
  1 (1.00%) high mild

eller/generate_10_x_10  time:   [23.493 µs 23.535 µs 23.589 µs]

eller/generate_100_x_100
                        time:   [2.2557 ms 2.2606 ms 2.2661 ms]
Found 2 outliers