a-maze-ing

Python project · algorithms, terminal

Maze generator with multiple algorithms, pathfinding solvers and terminal visualization.

• 25unit tests
• 6structural checks

The problem

Generate a valid maze from a config file, write it in a hexadecimal wall format and show it in the terminal. Built as a duo with luispais.

What I built

• Recursive backtracking with an explicit stack (depth-first), with an option to open extra walls for mazes with loops.
• Breadth-first search for the shortest path, since the maze graph is unweighted.
• Seeded generation, so a maze can be reproduced exactly.
• A terminal renderer that can show or hide the solution, regenerate from the UI, and draws a "42" of blocked cells in the middle of big mazes.
• The generator packaged as a reusable mazegen library (wheel and sdist).

The hard part

A cached path that went stale. During the animated generation the terminal UI redraws its info panel and asks for the path length, so the solver ran on a half-carved maze, found no way through and cached that empty result: after animating a new maze the panel read 0 moves and showing the path did nothing. The generator now drops the cached path when each attempt starts and again once the maze passes validation, which checks matching walls, closed borders, full connectivity, no open 3x3 area and a sealed "42", and regenerates on failure.

Built with

• Python 3.10+
• mypy
• flake8
• setuptools packaging

More projects

• metro · Lisbon metro sim in pixel art: watch the four lines run, step into any station, board a train and ride it.
• pac-man · Pac-Man in Python, built as a duo with sylvzzz: a new maze every level and four ghosts that each hunt you differently.
• call_me_maybe · Turns a sentence into a JSON function call with a 0.6B model using constrained decoding — parseable by construction, not by luck.
• codexion · Multithreaded twist on the Dining Philosophers: coders compete for shared dongles, with FIFO/EDF scheduling.
• dbaltaza.pt · A game-console portfolio where every project is a pre-rendered disc: Vite + TypeScript, no framework, and a paint budget the tests measure.
• fly-in · Drone fleet routing: Dijkstra pathfinding, turn-based scheduling and a pygame replay.
• push_swap · Highly optimized sorting with two stacks and a tiny set of allowed operations.
• ft_printf · printf rebuilt from scratch: chars, strings, pointers, decimals, unsigned and hex.
• get_next_line · Reads a file descriptor one line at a time with careful dynamic memory handling.
• Libft · My own C standard library — the foundation every later 42 project is built on.