A space exploration game designed to teach 3rd grade students spelling through engaging gameplay with progress tracking.
Word Quest is an educational game where students pilot a rocket ship through different planets, each representing a spelling word challenge. Correctly spelling words fuels the rocket and helps it travel further through space.
- Space Exploration Theme: Journey through planets, solar systems, and galaxies
- Engaging Gameplay: Type words to progress, with Captain Cosmos as your guide
- Progress Tracking: Detailed analytics for students and parents
- Motivation Systems: Streaks, stickers, badges, and positive reinforcement
- Parent Dashboard: Monitor progress, customize word lists, receive weekly reports
- Custom Word Lists: Import your child's school spelling lists via CSV
- Grade Level: 3rd grade (ages 8-9)
- Session Length: 8-12 minutes per session
- Learning Objective: Master spelling words through active practice
Comprehensive documentation is available in the /docs directory:
| Document | Description |
|---|---|
docs/01-overview.md |
Game design overview and learning objectives |
docs/02-mechanics.md |
Core gameplay mechanics and input methods |
docs/03-motivation-tracking.md |
Motivation systems and progress tracking details |
docs/04-design-tech-appendix.md |
Technical design, UI guidelines, and implementation notes |
- Python 3.8 or higher
- pip package manager
- A display capable of running Pygame (800x600 minimum)
-
Clone the repository
git clone <repository-url> cd word-quest
-
Create a virtual environment (required)
python -m venv .venv
-
Activate the virtual environment
- Windows:
.venv\Scripts\activate
- macOS/Linux:
source .venv/bin/activate
- Windows:
-
Install dependencies
pip install -r requirements.txt
-
Configure email notifications (optional)
cp .env.example .env
Edit
.envand add your SMTP credentials for weekly progress reports.
Once installed, run the game with:
python -m srcOr if a main entry point exists:
python main.py- Student Mode: Play spelling challenges and track progress
- Parent Dashboard: Configure word lists and view analytics
- Student Settings: Customize avatar, difficulty, and preferences
- Keyboard typing: Type letters to spell words
- On-screen keyboard: Visual reference for letter keys
- Space bar: Skip animations
- Mouse: Click interactive elements
- Word Reveal: Rocket approaches a planet with a mystery word
- Word Presentation: Word is spoken aloud, definition shown, starter letters displayed
- Spelling Challenge: Type the remaining letters
- Feedback:
- Correct: Rocket engines ignite, celebration animation, points awarded
- Incorrect: Gentle hints revealed, try again (no penalty)
- Progression: Complete 5 words to fuel the rocket and travel to the next planet
| Level | Word Length | Hints |
|---|---|---|
| 1-3 | 4-5 letters | Full letter count |
| 4-7 | 5-6 letters | First 3 letters |
| 8-12 | 6-7 letters | First 2 letters |
| 13+ | 7+ letters | First 2 letters |
- Planets: Each planet = 5-word set
- Solar Systems: 3 planets = 1 solar system (15 words)
- Galaxies: 4 solar systems = 1 galaxy (60 words)
- Pass: 4/5 words correct on first attempt โ unlock next planet
- Practice: 2-3/5 correct โ replay planet with same words
- Struggle: 0-1/5 correct โ parent notification, recommended review
- Words mastered (cumulative counter)
- Accuracy rate with trend indicators
- Words needing practice
- Longest streak achieved
- Session duration statistics
- Weekly Email Reports: Summary of progress sent via email
- Dashboard: View detailed analytics and word performance
- Word List Management: Import, edit, or manually add spelling words
- Progress Visualizations: Graphs and heat maps showing improvement
- Theme: Bright, friendly space exploration
- Colors: Deep space blue, starlight yellow, success green
- Typography: Large, readable fonts (24pt minimum for game text, 48pt for spelling)
- Background Music: Ambient space music (toggleable)
- Sound Effects: Success chimes, gentle feedback for incorrect answers
- Voice Lines: Captain Cosmos provides encouraging commentary
- Color-blind safe palette
- Text-to-speech for all words
- Keyboard navigation support
- Dyslexia-friendly font option
# Run all tests
pytest
# Run with coverage report
pytest --cov=src
# Run specific test file
pytest tests/test_word_manager.pyword-quest/
โโโ src/ # Main source code
โ โโโ components/ # Core game components
โ โ โโโ word_manager.py # Word list management
โ โ โโโ input_handler.py # Keyboard/input handling
โ โ โโโ progress_tracker.py # Progress data collection
โ โ โโโ planet_manager.py # Level/planet management
โ โ โโโ audio_system.py # Audio playback
โ โ โโโ captain_cosmos.py # Game mascot/character
โ โ โโโ sticker_manager.py # Reward system
โ โโโ screens/ # Game screens
โ โ โโโ spelling_challenge.py # Main spelling gameplay
โ โ โโโ planet_results.py # Results after word set
โ โ โโโ planet_transition.py # Travel animations
โ โ โโโ parent_dashboard.py # Parent configure/view
โ โ โโโ student_settings.py # Student customization
โ โโโ models/ # Data models
โ โโโ ui/ # UI components
โ โโโ animations/ # Animation systems
โ โโโ utils/ # Utility functions
โ โโโ analytics/ # Analytics and reporting
โโโ docs/ # Documentation
โ โโโ 01-overview.md
โ โโโ 02-mechanics.md
โ โโโ 03-motivation-tracking.md
โ โโโ 04-design-tech-appendix.md
โ โโโ stories/ # Development stories
โโโ tests/ # Unit and integration tests
โโโ data/ # Game data
โ โโโ badges/ # Badge definitions
โ โโโ word_lists/ # Custom word lists
โ โโโ progress/ # Student progress data
โโโ assets/ # Game assets
โ โโโ audio/ # Sound effects and music
โโโ templates/ # CSV templates for word import
โโโ requirements.txt # Python dependencies
โโโ pytest.ini # Test configuration
โโโ .env.example # Environment variable template
This project uses a story-based development workflow. See .agent/DEV_AGENT_INSTRUCTIONS.md for guidelines on:
- Story status lifecycle
- Branch naming conventions
- Code review process
- Sprint planning
.agent/DEV_AGENT_INSTRUCTIONS.md- Agent guidelinesdocs/sprint-status.yaml- Current sprint planningdocs/stories/- Detailed story implementation guides
- Check
docs/sprint-status.yamlforready-for-devstories - Read the detailed story file in
docs/stories/<STORY-ID>.md - Create a feature branch:
{EPIC-ID}-{STORY-ID}(e.g.,EPIC-1-STORY-3) - Implement following the story file acceptance criteria
- Write tests and ensure they pass
- Update story status and create a Pull Request
- Common Core L.3.2f: Spell grade-appropriate words correctly
- Develops phonics and word recognition skills
- Builds vocabulary through repeated word exposure
- Reinforces letter sequencing and recognition
See docs/04-design-tech-appendix.md section 10 for expansion ideas including:
- Multiplayer cooperative modes
- Additional word categories (science, math, vocabulary)
- Voice recognition for pronunciation practice
- Mobile/tablet versions
- Teacher classroom dashboard
[Add your license information here]
Built with โค๏ธ for young learners everywhere.
Questions or feedback? Contact the development team or open an issue on GitHub.