A-Maze-ing

A-Maze-ing is a Python project focused on maze generation, pathfinding, visualization, and reusable design.

The program reads a configuration file, generates a maze according to the given parameters, optionally creates a perfect maze, computes the shortest path from entry to exit, exports the result in the required hexadecimal format, and displays an interactive ASCII visualization in the terminal.

The project also includes a reusable package, mazegen, which contains the maze generation logic as a standalone installable module.

• Random maze generation from a configuration file
• Support for perfect and non-perfect mazes
• Reproducible generation through a seed
• Shortest path solving using Breadth-First Search (BFS)
• Hexadecimal export format
• Interactive ASCII renderer in the terminal
• Reusable installable package: mazegen

• Python 3.10 or later
• flake8
• mypy

make install

python3 a_maze_ing.py config.txt

or:

make run

make debug

make lint

make clean

The configuration file uses one KEY=VALUE pair per line. Lines starting with # are ignored.

# Example configuration
WIDTH=20
HEIGHT=15
ENTRY=0,0
EXIT=19,14
OUTPUT_FILE=maze.txt
PERFECT=True
SEED=42

The maze is exported using one hexadecimal digit per cell, where each bit represents a closed wall:

After the maze grid, the output file also contains:

1. entry coordinates
2. exit coordinates
3. the shortest valid path using N, E, S, W

The maze is generated using Randomized Depth-First Search (Recursive Backtracker).

This algorithm was chosen because it is:

• simple and efficient
• well suited for generating perfect mazes
• visually effective, producing long and interesting corridors

The shortest path is computed with Breadth-First Search (BFS).

The reusable part of the project is the mazegen package.

Its core class, MazeGenerator, can be used independently from the CLI, config parser, exporter, and renderer.

from mazegen import MazeGenerator

maze = MazeGenerator(
    width=20,
    height=15,
    entry=(0, 0),
    exit_pos=(19, 14),
    perfect=True,
    seed=42,
)

maze.generate()
solution = maze.solve()

print("Solution:", "".join(solution))

.
├── a_maze_ing.py
├── config.txt
├── Makefile
├── pyproject.toml
├── requirements.txt
├── README.md
├── LICENSE
└── src/
    ├── __init__.py
    ├── maze_exporter.py
    ├── parse_config.py
    ├── renderer.py
    └── mazegen/
        ├── __init__.py
        └── maze_generator.py

• Python dataclasses documentation
• Python pathlib documentation
• Python collections.deque documentation
• Maze generation algorithm references
• Breadth-First Search references

AI was used as a support tool for:

• reviewing structure and organization ideas
• checking possible edge cases
• improving README presentation

All implementation and final technical decisions were fully reviewed and understood.

This project is licensed under the MIT License. See the LICENSE file for details.