Smart Maze Solver

Smart Maze Solver is a local Pygame maze game where the player starts at the top-left corner and reaches the goal at the bottom-right corner. The game records the player's final visible path, computes the shortest path with BFS, and displays both paths on the same maze after the level is solved.

Features

• Four difficulty stages: easy, medium, hard, and extreme.
• Random maze generation with at least one valid route every time.
• Difficulty is based on grid size and exact possible path count:
  • Easy: 11x11, 4 possible paths
  • Medium: 15x15, 3 possible paths
  • Hard: 19x19, 2 possible paths
  • Extreme: 23x23, 1 possible path
• Arrow-key movement.
• Hint support while solving.
• Visible current path while playing.
• Backtracked path segments are removed from the visible path.
• End-of-level comparison:
  • Orange line: user's path
  • Green line: optimal shortest path
• Landscape 800x600 game window with a 4:3 aspect ratio.
• Saved session paths in saved_paths/session_paths.json.

Setup

Create a virtual environment, install dependencies, then run the game:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
python -m smart_maze_solver

If you do not use a virtual environment, install Pygame globally or in your active Python environment:

python -m pip install -e .
python -m smart_maze_solver

Controls

• Arrow keys: move through open passages.
• H: show the next best step from the current position.
• R: retry with a newly generated maze for the current difficulty.
• N: skip the comparison delay and move to the next difficulty after solving.
• Esc: quit.

After clearing a level, the game briefly compares your path against the shortest path, then automatically advances to the next difficulty. After clearing the extreme level, the game congratulates the player, waits briefly, and exits.

Tests

The core maze generation, pathfinding, path tracking, comparison, and save behavior are covered by unit tests.

python -m unittest discover -s tests

The tests do not require Pygame because the game logic is separated from the rendering layer.

Design Notes

The project keeps responsibilities separated:

• maze.py: maze model and random generation.
• pathfinding.py: BFS shortest path and path-count helpers.
• session.py: player path tracking, comparison, and persistence.
• game.py: Pygame UI and keyboard interaction.

The maze uses edge-based walls rather than blocked square cells. This keeps the visual grid clean, avoids visible grid lines, and lets the generator control the exact number of possible paths for each difficulty.