Teach a tiny mouse to hunt cheese in trap-filled mazes.
Lil Cheese Hunter™ is a Python + Pygame playground where a Q-learning mouse learns to navigate custom maps you design. Create puzzle-like levels, train an RL brain, and watch your mouse adapt and learn.
- Build custom maps with walls, traps, and home.
- Train a Q-learning mouse across every safe tile.
- Observe training in real-time with stats & controls.
What’s inside Lil Cheese Hunter™
A modular RL toolkit built around experimentation.
GridWorld Environment
Handles walls, traps, home tiles, movement, and rewards. Every safe tile becomes a training target.
Q-learning Engine
Tabular Q-learning with ε-greedy exploration, episodic training, and persistent Q-table saving.
Pygame Viewer
Watch training live with movement animations, stats, and adjustable FPS.
Map Editor
Design maps visually. Enforces valid shapes and ensures exactly one home tile.
Launcher Menu
A simple hub to start training, open map tools, or quit.
How it works
Lil Cheese Hunter™ uses classic Q-learning to teach navigation through hazards.
State Representation
State = (agent_row, agent_col, goal_row, goal_col)
Rewards
Step = –1, Trap = –100, Goal = +100 to +200, Wall bumps give extra penalty.
Q-learning Loop
ε-greedy action → step → reward → Bellman update.
Workflow
1 — Create a Map
Use the Pygame editor to paint your maze. Save as a cleaned JSON map.
2 — Train the Mouse
Select a map, choose train vs reuse Q-table, and watch the mouse learn.
3 — Explore
Click any tile to set it as a goal. The mouse follows its learned policy.
4 — Iterate
Change the map, reward shaping, or hyperparameters to compare behaviors.
Tech Stack
Python
Core logic, RL, environment.
Pygame
Rendering, input, UI windows.
NumPy + Matplotlib
Logging, training curves, analysis.
JSON Maps
Lightweight, easy to edit and version-control.
Download the Source
Grab the full Lil Cheese Hunter™ source code, explore the modules, and tweak the project however you like.
GitHub Repository
The complete project — environment, agent, viewer, editor, and launcher — lives on GitHub. Clone it, fork it, or use it as a base for your own RL experiments.
⬇ View on GitHub