knossos/
lib.rs

1//! # Overview
2//!
3//! `knossos` is a simple and flexible library for generating mazes using various algorithms.
4//! It provides built-in utilities for rendering mazes as ASCII, images, or game maps, as well
5//! as saving them to files in multiple formats.
6//!
7//! # Installation
8//! Run the following Cargo command in your project directory:
9//! ```no_test
10//! cargo add knossos
11//! ```
12//!
13//! Or add the following line to your `Cargo.toml`:
14//! ```no_test
15//! [dependencies]
16//! knossos = "1.2.0"
17//! ```
18//!
19//! # Usage
20//!
21//! This crate is designed to be super easy to use. Here are some usage examples of how to generate,
22//! display and save mazes:
23//!
24//! ## Generate with Default Parameters
25//! ```rust,no_run
26//! use knossos::maze::*;
27//!
28//! let maze = OrthogonalMazeBuilder::new().build();
29//! ```
30//!
31//! ## Generate with Custom Parameters
32//! ```rust,no_run
33//! use knossos::maze::*;
34//!
35//! let maze = OrthogonalMazeBuilder::new()
36//!  .height(10)
37//!  .width(10)
38//!  .algorithm(Box::new(GrowingTree::new(Method::Random)))
39//!  .build();
40//! ```
41//!
42//! Read more about [maze builder API](maze::OrthogonalMazeBuilder)
43//!
44//! ## Display Mazes
45//! ```rust,no_run
46//! use knossos::maze::*;
47//!
48//! let maze = OrthogonalMazeBuilder::new().build();
49//! println!("{}", &maze);
50//! ```
51//!
52//! ## Save to File
53//! ```rust,no_run
54//! use knossos::maze::*;
55//!
56//! let maze = OrthogonalMazeBuilder::new().build();
57//!
58//! // Save as ASCII text
59//! maze.save("output/maze.txt", AsciiNarrow).unwrap();
60//! // Save as a game map (with adjustable span size)
61//! maze.save("output/maze_game_map.txt", GameMap::new().span(3)).unwrap();
62//! // Save as a PNG image (adjusting wall and passage sizes)
63//! maze.save("output/maze.png", Image::new().wall(10).passage(30)).unwrap();
64//! ```
65//!
66//! ## Format for Further Processing or Logging
67//! ```rust,no_run
68//! use knossos::maze::*;
69//!
70//! let maze = OrthogonalMazeBuilder::new().build();
71//!
72//! // Convert to ASCII text
73//! let ascii = maze.format(AsciiNarrow).into_inner();
74//! // Convert to a game map
75//! let game_map = maze.format(GameMap::new()).into_inner();
76//! // Convert to an RGB image buffer
77//! let rgb_image = maze.format(Image::new().wall(10).passage(30)).into_inner();
78//! ```
79//!
80//! Read more about [maze formatters](maze::formatters)
81//!
82//! ## Seeding for Deterministic Mazes
83//!
84//! By default, each generated maze is randomized, producing a different layout every time. However,
85//! you can use a seed value to ensure that the same maze is generated consistently across runs.
86//! This is useful for debugging, testing, or sharing the exact same maze with others.
87//!
88//! ```rust,no_run
89//! use knossos::maze::*;
90//!
91//! // Generate a maze with a fixed seed
92//! let maze = OrthogonalMazeBuilder::new().seed(Some(40)).build();
93//! ```
94//!
95//! Passing `None` as the seed (or omitting the `.seed()` method) will result in a random maze each time.
96//!
97//! # Algorithms
98//!
99//! You can find 10 different algorithms supported by this crate. Each of them has its own pros and
100//! cons: some of them are impressively efficient, some of them are slower but generate splendid
101//! mazes that look hard to puzzle out, and others are extremely flexible and customizable. Do give
102//! each of them a shot and find the best one that suits you:
103//!
104//! - [`AldousBroder`](maze::AldousBroder)
105//! - [`BinaryTree`](maze::BinaryTree)
106//! - [`Eller`](maze::Eller)
107//! - [`GrowingTree`](maze::GrowingTree)
108//! - [`HuntAndKill`](maze::HuntAndKill)
109//! - [`Kruskal`](maze::Kruskal)
110//! - [`Prim`](maze::Prim)
111//! - [`RecursiveBacktracking`](maze::RecursiveBacktracking)
112//! - [`RecursiveDivision`](maze::RecursiveDivision)
113//! - [`Sidewinder`](maze::Sidewinder)
114
115mod utils;
116
117pub mod maze;
118pub use utils::color::Color;
knossos/lib.rs

knossos/
lib.rs
