Maze Generator

A configurable Python maze generator with step-by-step visualization and export.

A-Maze-ing is a Python project that implements a configurable maze generator. The program reads a configuration file, generates a random maze (perfect or imperfect), ensures structural constraints, embeds a visible "42" pattern, and exports the maze using a hexadecimal wall encoding format. A visual representation is also provided to help users explore the maze and its solution interactively.

This project focuses on algorithmic thinking, randomness, graph theory, clean software architecture, and code reusability.

Instructions

Setup

1. Install dependencies

make install

2. Install mlx manually if you need the graphics backend. The repository includes mlx_CLXV-2.2.tgz for convenience.

3. Run using

make run

Maze generation module mazegen

Installation

Install using

pip install mazegen-1.0.0-py3-none-any.whl

Rebuild from source

cd mazegen
pip install setuptools
python setup.py sdist bdist_wheel

Usage

Use either Custom0MazeGenerator or KruskalMazeGenerator from the mazegen module. Arguments:

• width: Maze width
• height: Maze height
• entry_coord: Entry point coordinate
• exit_coord: Exit point coordinate
• filepath: Output file path
• perfect: Generate a perfect maze (default: True)
• seed: Optional random seed for reproducibility

Maze Generation

• generate_step() Generate a single step of the maze

• generate() Generate the full maze in one run

Maze Solving

• solve_step() Solve a single step of the maze

• solve() Solve the maze completely

Access the raw maze data using attibute maze (2D ndarray of cells).

Visualisation controls

Key	Action
ESC / Q	Quit the application
S	Toggle single-step mode
SPACE	Pause / Resume maze generation
R	Reset the maze generator
W	Cycle wall colors
L	Cycle logo colors
P	Show / hide path drawing
D	Toggle disco mode

Resources

• https://chatgpt.com / https://duck.ai / Github Copilot Used for explaining barely documented mlx lib and as extended code completion
• https://docs.python.org/3/
• https://en.wikipedia.org/wiki/Kruskal%27s_algorithm
• https://www.geeksforgeeks.org/dsa/kruskals-minimum-spanning-tree-algorithm-greedy-algo-2/

Config file structure

Each field in the config file is defined as follows: key = value i.e. width = 20. Lines starting with # are comments and ignored. Blank lines are also ignored.

Field	Type	Required	Default	Constraints	Description
width	integer	✅	—	≥ 1	Width of the maze in cells
height	integer	✅	—	≥ 1	Height of the maze in cells
entry	tuple (x,y)	✅	—	0 ≤ x < width, 0 ≤ y < height	Entry coordinate of the maze
exit	tuple (x,y)	✅	—	0 ≤ x < width, 0 ≤ y < height	Exit coordinate of the maze
output_file	path	✅	—	Must be a valid file path	Output file for the generated maze
perfect	boolean	❌	True	—	Generate a perfect maze (no loops)
seed	integer	❌	None	—	Random seed for reproducible generation
algorithm	string	❌	kruskal	kruskal, custom0	Maze generation algorithm
window_margin	integer	❌	3	≥ 1, ≤ min(window_max_size)/2	Margin around the rendering window
window_max_size	tuple (w,h)	❌	(800,800)	w > 0, h > 0	Maximum render window size in pixels
fps	float	❌	60	≥ 1	Frames per second for visualization

Maze generation algorithms

• Kruskal's Algorithm (kruskal): Looked cool and fun to implement.
• Custom Algorithm 0 (custom0): The algorithm probably has a name, but we implemented it from our own logic. It starts with all possible connections between 2 cells as open and randomly closes walls while ensuring the maze remains connected. It stops when no 3x3 cavities are present or when the maze is perfect.

Reusable components

• The renderer and drawer are a few steps away from being reusable in other projects.
• The maze generation algorithms are modular and can be extended with new algorithms easily.