da7e/amazing

Fork 0

mirror of https://github.com/maoakeEnterprise/amazing.git synced 2026-04-28 16:04:35 +02:00

Files

T

da7e b54e49122c README

2026-04-02 14:15:40 +02:00

12 KiB

Raw Blame History

This project has been created as part of the 42 curriculum by mteriier, dgaillet

A-Maze-ing

Description

A-Maze-ing is a Python project that generates, solves, exports, and displays mazes.

The program:

reads a configuration file,
generates a maze according to the requested parameters,
optionally enforces a perfect maze property,
solves the maze from entry to exit,
writes the maze to an output file using the required hexadecimal wall encoding,
and displays the maze visually through an MLX graphical window.

This project was designed with code reusability in mind.
The maze generation and solving logic is exposed through a reusable Python package named mazegen, which can be built and installed independently for use in future projects.

Features

Maze generation from a config file
Multiple generation algorithms:
- DFS (depth-first search / recursive backtracking style)
- Kruskal
Multiple solving algorithms:
- AStar
- DFS
Perfect and imperfect maze support
Maze export using hexadecimal wall encoding
Graphical rendering with MLX
Animated generation
Animated solution path display
Wall color switching
Reserved visual “42” pattern using fully closed cells when the maze is large enough
Reusable mazegen package

Project Structure

.
├── a_maze_ing.py          # Main executable script and MLX display
├── config.txt             # Default configuration file
├── Makefile
├── README.md
├── src/
│   ├── AMazeIng.py
│   ├── mazegen/
│   │   ├── __init__.py
│   │   ├── Cell.py
│   │   ├── Maze.py
│   │   ├── MazeGenerator.py
│   │   └── MazeSolver.py
│   └── parsing/
│       └── Parsing.py
└── tests/

Instructions

Requirements

Python 3.10+
uv, pip
MLX Python binding used by the project

Installation

Using the provided Makefile:

make install

This installs project dependencies and the MLX wheel used by the graphical display.

Run

make run

Debug

make debug

Lint

Mandatory lint target:

make lint

Strict lint target:

make lint-strict

Clean

make clean

Full cleanup:

make fclean

Configuration File Format

The configuration file contains one KEY=VALUE pair per line.

Mandatory keys

Key	Description	Example
`WIDTH`	Maze width in cells	`WIDTH=20`
`HEIGHT`	Maze height in cells	`HEIGHT=15`
`ENTRY`	Entry coordinates `(x,y)`	`ENTRY=1,1`
`EXIT`	Exit coordinates `(x,y)`	`EXIT=20,15`
`OUTPUT_FILE`	Output filename	`OUTPUT_FILE=maze.txt`
`PERFECT`	Perfect maze or not	`PERFECT=True`
`GENERATOR`	Generation algorithm	`GENERATOR=DFS`
`SOLVER`	Solving algorithm	`SOLVER=AStar`

Supported values

GENERATOR

DFS
Kruskal

SOLVER

AStar
DFS

PERFECT

True
False

Example config

WIDTH=20
HEIGHT=15
ENTRY=1,1
EXIT=20,15
OUTPUT_FILE=maze.txt
PERFECT=True
GENERATOR=DFS
SOLVER=AStar
SEED=31766516

Notes

Coordinates are handled as tuples in the form x,y.
In the current implementation, coordinates are expected to be inside maze bounds.
Entry and exit must be valid cells.
The parser validates required keys and converts values to the correct Python types.
You can add a SEED value

Output File Format

The generated maze is written row by row using one hexadecimal digit per cell.

Each cell stores wall information using this bitmask:

Bit	Direction
`1`	North
`2`	East
`4`	South
`8`	West

A bit set to 1 means the wall is closed.

Example

3 = 0011 → north and east closed
A = 1010 → east and west closed

Output layout

<maze row 1>
<maze row 2>
...
<maze row n>

<entry coordinates>
<exit coordinates>
<solution path>

Example:

FFFF
9A63
8C47
FFFF

1,1
4,4
EESSEN

Visual Representation

This project provides a graphical rendering through MLX.

The display shows:

maze walls,
entry cell,
exit cell,
optional shortest path,
reserved “42” pattern when present.

Controls

In the MLX window:

1 / mapped equivalent: regenerate maze
2 / mapped equivalent: show/hide path
3 / mapped equivalent: change wall color
4 / mapped equivalent: quit

The code includes two key mappings to handle platform/layout differences.

Visual Features

animated generation,
animated path display,
color cycling for walls,
separate color cycling for the “42” cells.

Maze Generation Algorithm

This project supports two generation algorithms.

1. Depth-First Search (DFS)

This algorithm starts from a cell and repeatedly visits an unvisited neighbour, removing walls as it advances. When it reaches a dead end, it backtracks until it finds a cell with an unvisited neighbour.

Why this algorithm was chosen

simple to implement,
naturally produces connected mazes,
works well for animation,
produces visually interesting long corridors,
easy to adapt for perfect mazes.

2. Kruskal

This algorithm treats each cell as its own set and removes walls between cells only when it connects two different sets. This avoids cycles and guarantees connectivity.

Why this algorithm was included

classic maze generation algorithm,
good complement to DFS,
demonstrates modularity and algorithm interchangeability,
naturally fits the reusable package requirement.

Why These Algorithms Were Chosen

We chose DFS and Kruskal because together they provide:

two well-known and complementary approaches,
good pedagogical value,
simple integration into a reusable class-based architecture,
deterministic structure when used with a seed,
compatibility with perfect maze generation.

DFS is particularly suitable for progressive visual rendering.
Kruskal is useful to show a different construction logic based on set merging.

Perfect and Imperfect Mazes

When PERFECT=True:

the maze is generated as a perfect maze,
there is exactly one path between any two reachable cells,
in particular, entry and exit have a unique valid path.

When PERFECT=False:

additional walls may be removed after initial generation,
loops can appear,
the maze remains connected,
the solver still computes a valid path.

The “42” Pattern

For sufficiently large mazes, the generator reserves a group of fully closed cells to draw a visible “42” pattern in the visual rendering.

Behaviour

the pattern is added only if the maze is large enough,
if the maze is too small, the pattern may be omitted,
this should be reported to the user with a console message.

Current implementation note

The current code includes support for reserving and rendering the “42” pattern using cells with value 15 (all walls closed).
The pattern is drawn in the central area when dimensions are large enough.

Error Handling

The project is designed to fail gracefully and provide clear messages for common problems such as:

missing configuration file,
empty file,
missing or invalid keys,
invalid boolean values,
invalid coordinates,
invalid maze dimensions,
solving an uninitialized maze.

The parser catches several common exceptions and prints user-friendly messages before exiting.

Reusable Code

The reusable part of the project is the mazegen package.

It contains:

Cell: wall bitmask representation,
Maze: maze container and textual/ascii rendering,
MazeGenerator: abstract generator interface,
DepthFirstSearch: DFS-based maze generator,
Kruskal: Kruskal-based maze generator,
MazeSolver: abstract solver interface,
AStar: shortest-path solver,
DepthFirstSearchSolver: DFS-based path solver.

This package can be built as a wheel and reused independently of the MLX application.

How to Use the Reusable Module

Basic example

from mazegen import Maze
from mazegen import DepthFirstSearch, AStar

generator = DepthFirstSearch(start=(1, 1), end=(10, 10), perfect=True)
solver = AStar(start=(1, 1), end=(10, 10))

maze = Maze()

for grid in generator.generator(height=10, width=10, seed=42):
    maze.set_maze(grid)

path = solver.solve(maze, height=10, width=10)

print(maze)
print(path)

With Kruskal

from mazegen import Maze, Kruskal, AStar

generator = Kruskal(start=(1, 1), end=(20, 15), perfect=True)
solver = AStar(start=(1, 1), end=(20, 15))

maze = Maze()

for grid in generator.generator(height=15, width=20, seed=123):
    maze.set_maze(grid)

print(solver.solve(maze, height=15, width=20))

Accessing the generated structure

maze_array = maze.get_maze()

Each element of maze_array is a Cell object exposing:

get_north()
get_est()
get_south()
get_west()
get_value()

Accessing a solution

solution = solver.solve(maze, height=15, width=20)
print(solution)  # Example: "EESSWN..."

Packaging

The reusable package is distributed as mazegen-*.

Example expected artifact:

mazegen-1.0.0-py3-none-any.whl

Build with:

make build

This produces a wheel suitable for later installation with pip/uv.

Tests

Unit tests are recommended and partially integrated through pytest targets in the Makefile.

Start test with:

make run_test

These tests are useful to validate:

parsing,
generation,
solver behavior,
edge cases.

Technical Choices

Language

Python 3.10+

Libraries

numpy for grid storage
pydantic for model validation
mlx for graphical rendering
pytest for tests
mypy for static typing
flake8 for style checking

Architecture

The project is separated into three main parts:

Main application
- parsing,
- orchestration,
- MLX rendering,
- user interaction.
Domain model
- AMazeIng,
- maze configuration and lifecycle.
Reusable package
- generation,
- solving,
- maze structure.

This separation makes the generation logic portable to other projects.

Team and Project Management

Team roles

mteriier
- Parsing
- DFS generator / solver
- Makefile
- some pytest
- Fix of mazegen package generation
- MLX
dgaillet
- AMazeIng config class
- AStar solver
- Kruskal generator
- some pytest
- mazegen package generation
- MLX
- Cell / Maze class

Initial planning

Our initial plan was:

define the maze data model,
implement one working generation algorithm,
export the maze to the required format,
implement solving,
add graphical rendering,
package reusable code,
write tests and documentation.

How planning evolved

In practice:

the reusable package structure had to be stabilized earlier than expected,
coordinate handling between parser, generator, solver, and renderer required extra work,
rendering and animation took longer than planned,
algorithm modularity made later integration easier.

What worked well

clean separation between generation and display,
abstract base classes for generator and solver,
Makefile automation,
packaging the reusable module.

What could be improved

stricter normalization of coordinate conventions,
seed support should be exposed directly from configuration,
more tests for edge cases and invalid inputs,

Tools used

Git
uv
flake8
mypy
pytest
MLX
optionally AI assistance for docstrings, README

Resources

Documentation and references

How AI was used

AI was used as an assistant for:

improving docstrings,
helping structure the README,

Reusable Module Summary

If you only want the reusable maze engine:

build/install mazegen,
import a generator and a solver,
generate a maze,
solve it,
access the grid through Maze.get_maze().

This part is intended for reuse in future Python projects.

12 KiB Raw Blame History