🎯 Solving Puzzles with Code: A Math Adventure Game Built with Amazon Q CLI
#devchallenge#awschallenge#ai#webdev
Mohamed Nizzad

Mohamed Nizzad @mohamednizzad

About: Data Scientist / AWS Certified (2X) ML Specialist | AWS ABW Grant Recipient '24 | 2 (Masters + Bachelors) | Researcher - NLP (Bias & Fairness) | Attorney-at-Law | Supervised 100+

Location:
Colombo, Sri Lanka
Joined:
Jan 9, 2025

🎯 Solving Puzzles with Code: A Math Adventure Game Built with Amazon Q CLI

Publish Date: May 28
16 0

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

GitHub logo mohamednizzad / mathsadventure

This is a simple project for Amazon Q CLI Game Challenge Developed along with my kid

Math Adventure - Educational Game

A fun and educational math game designed for students in grades 1-5, built with Pygame.

Features

  • Progressive difficulty levels matching grades 1-5
  • Interactive and engaging gameplay
  • Various math operations (addition, subtraction, multiplication, division)
  • Colorful graphics and sound effects
  • Score tracking and achievements

Requirements

  • Python 3.7+
  • Pygame

Installation

  1. Clone this repository
  2. Install requirements:
pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

Running the Game

python src/main.py
Enter fullscreen mode Exit fullscreen mode

Testing

python -m pytest tests/
Enter fullscreen mode Exit fullscreen mode

Project Structure

.
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ main.py
β”‚   β”œβ”€β”€ game.py
β”‚   β”œβ”€β”€ levels.py
β”‚   └── utils.py
β”œβ”€β”€ tests/
β”‚   β”œβ”€β”€ test_game.py
β”‚   └── test_levels.py
β”œβ”€β”€ assets/
β”‚   β”œβ”€β”€ fonts/
β”‚   β”œβ”€β”€ images/
β”‚   └── sounds/
β”œβ”€β”€ requirements.txt
└── README.md

View on GitHub


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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Create and activate a virtual environment: 

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

# macOS/Linux
python3 -m venv venv
source venv/bin/activate
Enter fullscreen mode Exit fullscreen mode

Install dependencies: 

pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

Quick Start

Run the game: 

python src/main.py
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

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

mohamednizzad

πŸ’Έ 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

Comments 0 total

    Add comment