A-Maze-ing

A configurable maze generation and solving tool built in Python

This project has been performed by @Edugs94 and @mpadronrz.

📝 Description

A-Maze-ing is a Python-based application designed to generate, visualize, and solve complex mazes. Built with performance and modularity in mind, the program offers multiple generation algorithms, customization options for maze density and size, and an interactive graphical interface.

Beyond simple generation, the tool provides real-time animated solvers using Breadth-First Search (BFS) and features a "Play Mode" where users can attempt to navigate the generated labyrinths manually. The core logic is encapsulated in a reusable Python package (mazegen), allowing developers to integrate these algorithms into their own projects.

---

✨ Key Features

• Algorithmic Variety: Choose between Prim’s Algorithm (organic, short branches) or DFS / Recursive Backtracker (long, winding corridors).
• Deterministic Generation: Support for Seeds to reproduce specific mazes exactly.
• Customizable Topology:
  • Perfect Mazes: Standard generation ensuring a single unique path between any two points.
  • Density Control: Adjustable internal wall density (0% to 95%) to create open spaces or strictly confined corridors.
• Dual Visualization:
  • ASCII Renderer: Lightweight terminal-based view.
  • MLX Interface: High-performance graphical display using MiniLibX.
• Intelligent Solver: Implements BFS (Breadth-First Search) to guarantee finding the shortest path.
  • Includes an animated visualization of the solving process with adjustable speed (Blocks Per Second).
• Interactive Play Mode: Navigate the maze yourself within the MLX interface.
• Hexadecimal Output: Exports maze structure to files for external validation or processing.

---

📸 Visuals

Visualization Modes

Below are examples of the two rendering engines available in the application.

ASCII (Terminal)	MLX (Graphical)

BFS Visualizer

Solving Prim's generated Maze	Solving DFS generated Maze

Density Control

The DENSITY parameter allows for the removal of internal walls, creating loops and open areas.

Interactive Play Mode

Jump into the maze and solve it manually.

---

🛠️ Installation

Prerequisites

• Python 3.10 or higher.
• make utility.
• pip package installer.
• MiniLibX (MLX) dependencies (if using graphical mode).

Setup

Use the provided Makefile to set up the environment and dependencies.

🚀 Usage

The easiest way to run the project is using the Makefile.

1. Configure: Edit the config.txt file to set your desired maze parameters (size, algorithm, display mode, etc.).

2. Run: Execute the command make. This single command will automatically:

   • Install all necessary dependencies.
   • Set up the virtual environment.
   • Execute the project with your configuration.

   Alternative manual execution, after creating a venv : python3 a_maze_ing.py config.txt from your venv

Configuration File Format

The config.txt defines the maze parameters using KEY=VALUE pairs. Lines starting with # are ignored.

Key	Description	Example
WIDTH	Number of columns (maze width).	WIDTH=40
HEIGHT	Number of rows (maze height).	HEIGHT=30
ENTRY	Coordinates of the start point (x,y).	ENTRY=0,0
EXIT	Coordinates of the end point (x,y).	EXIT=39,29
OUTPUT_FILE	Filename for the hexadecimal output.	OUTPUT_FILE=maze.txt
PERFECT	True for a perfect maze (no loops), False otherwise.	PERFECT=True
DISPLAY_MODE	(Optional) Choose visualization interface: ascii or mlx.	DISPLAY_MODE=mlx
SEED	(Optional) Integer for reproducible results.	SEED=12345
ALGORITHM	(Optional) Generation algorithm: prim or dfs.	ALGORITHM=dfs
DENSITY	(Optional) 0-95. % of walls kept after generation.	DENSITY=70

🛡️ File Safety

The application includes a safety mechanism to prevent accidental data loss. Output files are automatically redirected to a dedicated folder and the system prevents overwriting any existing source code or critical project files if the OUTPUT_FILE parameter shares a name with them.

📦 Code Reusability (mazegen package)

The core logic of this project has been extracted into a standalone Python package named mazegen. This allows other developers to generate, solve, and customize mazes (including features like the "42" logo overlay) without using our UI.

Installation & Usage

The package is located at the root of the repository.

1. Install:

   pip install mazegen-1.0.0.tar.gz

2. Implementation:

   from mazegen import MazeGenerator
   
   # Instantiate with configuration
   maze = MazeGenerator(
       width=20, height=15,
       entry=(0, 0), exit=(19, 14),
       perfect=True,        # True = unique path
       algorithm="prim",    # "prim" or "dfs"
       seed=42,             # Optional for reproducibility
       ft_logo=True         # Overlays '42' logo (min size 12x10)
   )
   
   # Generate maze and solve
   maze.generate_maze()
   
   # Access Data
   print(maze.solution) # List of (x, y) coordinates
   print(maze.edges)    # 2D Grid of bit-flags

Data Structure

The maze.edges attribute contains the raw maze structure as a 2D list of integers. Each integer uses bit flags to denote walls (1 = closed, 0 = open):

Bit	Direction	Value (Binary)
0	North	0001
1	East	0010
2	South	0100
3	West	1000

Example: A cell value of 3 (0011) means walls are closed to the North and East.

---

👥 Team Roles

• @Edugs94: Responsible for input data validation and parsing, BFS solver logic and its animated visualization, the density algorithm for wall removal, and the ASCII terminal renderer.
• @mpadronrz: Responsible for the core generative algorithms (Prim and DFS), the MLX graphical interface and its interactive Play Mode, output file generation and file safety/protection mechanism, as well as the mazegen package creation.

---

Tools Used

• Language: Python 3.10
• Linter: Flake8
• Type Checking: MyPy
• Graphics: MiniLibX (MLX)

---

📚 Resources

References

• Breadth First Search (BFS): Visualized and Explained by Reducible