Math Adventure: An Interactive Educational Math Game for Grades 1-5

Math Adventure is a dynamic, grade-progressive educational game that helps students practice math operations through an engaging interactive interface. The game adapts to student performance, automatically advancing through grade levels as players demonstrate mastery of mathematical concepts.

The game features a carefully designed difficulty progression system that introduces new mathematical operations and larger numbers as students advance through grades 1-5. Starting with simple addition and subtraction with numbers up to 10, it gradually incorporates multiplication and division with larger numbers up to 200. The game provides immediate feedback, tracks lives and scores, and includes visual rewards for correct answers and level progression.

Game Demo

Github Repository

pip install -r requirements.txt

python src/main.py

python -m pytest tests/

.
├── src/
│   ├── main.py
│   ├── game.py
│   ├── levels.py
│   └── utils.py
├── tests/
│   ├── test_game.py
│   └── test_levels.py
├── assets/
│   ├── fonts/
│   ├── images/
│   └── sounds/
├── requirements.txt
└── README.md

Repository Structure

math-adventure/
├── requirements.txt     # Python package dependencies (pygame, pytest)
├── src/
│   ├── game.py         # Core game logic, UI, and game state management
│   ├── levels.py       # Math problem generation and difficulty scaling
│   └── main.py         # Application entry point and pygame initialization
└── tests/              # Test suite directory
    ├── test_game.py    # Game mechanics and UI tests
    └── test_levels.py  # Math problem generation tests

Usage Instructions

Prerequisites

• Python 3.6 or higher
• pip (Python package installer)

Installation

Clone the repository:

git clone https://github.com/mohamednizzad/mathsadventure.git
cd math-adventure

Create and activate a virtual environment:

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Quick Start

Run the game:

python src/main.py

Game Controls:

• Enter numbers using the keyboard
• Press Enter to submit your answer
• Press Backspace to delete input
• Press 'R' to restart when game is over
• Press 'Q' to quit when game is over

More Detailed Examples

Grade 1 Problems:

• Addition and subtraction with numbers 1-10
• Example: "5 + 3 = ?"

Grade 2 Problems:

• Addition and subtraction with numbers 1-20
• Example: "15 - 7 = ?"

Grade 3 Problems:

• Addition, subtraction, and multiplication
• Numbers up to 50
• Example: "6 * 8 = ?"

Grade 4 Problems:

• All operations including division
• Numbers up to 100
• Example: "48 ÷ 6 = ?"

Grade 5 Problems:

• Advanced operations with larger numbers
• Numbers up to 200
• Example: "156 + 44 = ?"

Troubleshooting

Pygame Installation Issues:

# Windows
pip install --upgrade pip
pip install pygame --pre

# Linux
sudo apt-get install python3-pygame

Display Issues:

• Ensure your display resolution is at least 800x600
• Try updating your graphics drivers

Performance Issues:

• Check CPU usage with Task Manager/Activity Monitor
• Close other resource-intensive applications
• Verify pygame version is 2.1.0 or higher

Data Flow

The game processes math problems through a generate-solve-validate cycle, with progressive difficulty scaling based on player performance.

[User Input] -> [Problem Generator] -> [Game Logic] -> [UI Renderer]
     ^                                      |
     |                                     v
[Score/Lives Update] <- [Answer Validation] <- [Player Response]

Component Interactions:

1. Problem Generator creates grade-appropriate math problems
2. Game Logic manages game state and processes user input
3. UI Renderer displays problems and feedback
4. Answer Validation checks responses and updates game state
5. Score/Lives system tracks player progress
6. Grade progression system monitors score thresholds
7. Feedback system provides immediate response to player actions

Bonus

Checkout my article that won the Amazon Q Developer Challenge

💸 A Definite Guide to Develop Production Grade Applications with AWS Q Developer in 2025 [Video Demo Included] 🎥

Mohamed Nizzad ・ May 11

#devchallenge #awschallenge #ai #webdev