Cheese Heist

Cheese Heist is a procedural maze game built with Python and Pygame.

The player controls a mouse, searches for the cheese, avoids traps, and must return home to complete the level. Each maze is generated automatically and validated before gameplay starts.

• Procedural maze generation using recursive backtracking
• Additional passages that create multiple possible routes
• BFS validation and shortest-path calculation
• Animated mouse movement in four directions
• Cheese collection and return-home objective
• Temporary trap penalty with countdown
• Start screen and victory overlay
• Move counter and route efficiency score
• Debug visualization for the shortest BFS path
• Easy, medium, and hard difficulty selection
• Genetic algorithm with selection, crossover, mutation, and elitism
• Level evolution toward a selected difficulty
• Q-learning agent with training statistics and saved Q-tables
• BFS and trained-agent path comparison
• Automated tests for the main gameplay rules

The objective is to:

1. Find and collect the cheese.
2. Return to the mouse home.
3. Complete the round trip using as few moves as possible.

The efficiency score compares the optimal round trip with the player's actual number of moves:

efficiency = (2 × shortest path) / player moves × 100

• Human Play generates a level for the selected difficulty.
• Watch Trained Agent trains and displays a Q-learning agent.
• Generate Random Level creates a playable procedural level.
• Evolve Level evolves a level toward easy, medium, or hard.

config/       Global settings
core/         Main game loop and gameplay logic
entities/     Mouse, cheese, traps, and entity management
generation/   Maze generation, level management, and BFS validation
graphics/     Asset loading and rendering
difficulty/   Adaptive difficulty components
learning/     Learning and AI components
tests/        Automated tests
data/         Generated levels, results, and saved Q-tables
main.py       Application entry point

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install the dependencies:

pip install -r requirements.txt

make run

Alternatively:

python3 main.py

Run the automated tests:

make test

Run all configured checks:

make check

The initial maze is generated by carving connected passages through a grid of walls.

Selected internal walls are removed after the base maze is generated. This creates loops and alternative routes while keeping the maze connected.

BFS verifies that the level is playable and calculates the shortest route between the mouse home and the cheese.

Each level is evaluated as an individual. Tournament selection, crossover, mutation, and elitism evolve the population toward the selected difficulty.

The state is (row, column, has_cheese). The agent learns from movement, wall, trap, cheese, and completion rewards using an epsilon-greedy policy.

Training results compare the untrained agent, trained agent, and optimal BFS route. Models are saved in data/saved_models/, while statistics are saved in data/results/.

The game includes procedural generation, adaptive difficulty, level evolution, Q-learning training, and a visual trained-agent mode.

• Andreea Radu
• David Silviu