An interactive geography learning game using spaced repetition to master world map locations
Installation • Usage • Features • Contributing • Roadmap
Map Mayhem is a mobile-first geography learning application that transforms the traditional flashcard experience into an engaging, interactive map-based game. Using proven spaced repetition techniques, Map Mayhem helps users efficiently learn and remember country locations worldwide through dynamic interactions with an interactive world map.
- Interactive World Map - Tap, zoom, and explore a fully interactive vector map
- Spaced Repetition Learning - Modified FSRS algorithm optimizes your learning efficiency
- Cross-Platform - Seamless experience on both Android and iOS devices
- Offline Capability - Learn anywhere, even without an internet connection
- Progress Tracking - Monitor your improvement with detailed statistics
- Customizable Learning - Focus on specific regions or create custom country playlists
- Dynamic Difficulty - Adaptive challenges based on your performance
- Geography enthusiasts, students, and educators
- Travelers wanting to improve their global geography knowledge
- Casual gamers looking for educational entertainment
- Anyone preparing for geography-related exams or competitions
- Users seeking a mobile, on-the-go learning tool using spaced repetition techniques
For detailed analysis of our target audience and their expectations, see TARGET_AUDIENCE.md.
- Download Map Mayhem from the Google Play Store (Coming Soon)
- Install the application following on-screen instructions
- Launch the app and start learning!
- Download Map Mayhem from the Apple App Store (Coming Soon)
- Install the application following on-screen instructions
- Launch the app and start learning!
Try Map Mayhem directly in your browser:
- Visit our web application (Coming Soon)
- No installation required - works on desktop and mobile browsers
- Start learning geography instantly!
- Flutter SDK (3.5.3 or higher)
- Dart (3.0.0 or higher)
- Git
- Android Studio or VS Code with Flutter extensions
# Clone the repository
git clone https://github.com/yourusername/map-mayhem.git
# Navigate to project directory
cd map-mayhem
# Install dependencies
flutter pub get
# Run the app in development mode
flutter runTo run the web version locally:
# Get dependencies
flutter pub get
# Run in web development mode
flutter run -d chrome
# Build for production
flutter build web --release --web-renderer canvaskitMap Mayhem can be deployed to Cloudflare Pages using multiple methods:
-
Direct Upload (Recommended): Build locally and deploy with one command
./direct_upload_to_cloudflare.sh
-
GitHub Actions: Automatic deployment on code push
- Set up once and deployments happen automatically
-
Manual Upload: Build locally and upload through the Cloudflare dashboard
For detailed deployment instructions, see CLOUDFLARE_DEPLOYMENT.md.
- If you encounter package resolution issues, try
flutter cleanfollowed byflutter pub get - For platform-specific build errors, ensure you have the latest Flutter SDK with
flutter upgrade - Check the Flutter documentation for platform-specific setup requirements
- Launch the app - Open Map Mayhem on your mobile device
- Select a learning mode - Choose between Practice, Challenge, or Custom modes
- Interact with the map - Use intuitive touch gestures to navigate and select countries
- Track your progress - Review your learning statistics and improvement over time
- The app presents you with a country name to locate
- The world map appears, allowing you to navigate and find the requested country
- Tap on the country you believe matches the prompt
- Receive immediate feedback on your selection
- The app uses spaced repetition to schedule future appearances of each country based on your performance
- Tap - Select a country
- Pinch - Zoom in/out of the map
- Drag - Pan across the map
- Double-tap - Quick zoom to a specific area
Map Mayhem presents an interactive world map and challenges you to locate specific countries. The game dynamically adjusts to your performance:
- A country name appears as your target
- The map initially displays a zoomed-out view
- As you narrow down your search, the map repositions and zooms in on the target region
- Correct answers provide visual feedback with country highlighting and labeling
- Incorrect guesses show the correct location to reinforce learning
- The spaced repetition algorithm schedules countries to reappear based on your performance:
- Countries you struggle with appear more frequently
- Well-known countries appear less often to optimize learning time
- Map Rotations - Optional 90° rotations or upside-down views to enhance spatial awareness
- Incremental Difficulty - Dynamic zoom levels and panning adjust as you improve
- Custom Region Focus - Create playlists to focus on specific geographic areas
- Challenge Modes - Time-based challenges and competitive options for advanced users
Map Mayhem is built with Flutter using the Dart programming language, providing:
- Cross-platform compatibility for Android and iOS
- High-performance animations for smooth map transitions
- Responsive widget system for intuitive mobile interfaces
- Vector-based map rendering using Flutter packages (flutter_svg, google_maps_flutter)
- High-resolution map assets optimized for various mobile screen sizes
- Touch-optimized interactive map with zoom, pan, and rotation gestures
The core learning algorithm uses a modified FSRS (Free Spaced Repetition Scheduler) implementation:
- Dynamically adjusts review intervals based on performance
- Prioritizes difficult countries while spacing out well-known ones
- Configurable parameters for personalized learning pace
- Local storage using Flutter plugins (shared_preferences, SQLite)
- Optional cloud synchronization for cross-device progress (Firebase)
- Efficient caching of map assets for offline usage
We welcome contributions to Map Mayhem! Whether you're fixing bugs, improving documentation, or proposing new features, your help makes this project better for everyone.
Follow the developer installation instructions to set up your local environment.
- Fork the repository and create your branch from
main - Make your changes following our coding standards
- Add tests for any new functionality
- Ensure all tests pass with
flutter test - Update documentation as needed
- Submit a pull request with a clear description of your changes
- Follow the Dart style guide
- Write meaningful commit messages
- Include comments for complex logic
- Maintain test coverage for new features
- Use the GitHub issue tracker to report bugs
- Include detailed steps to reproduce the issue
- Specify your device model and OS version
- Attach screenshots if applicable
- Skip Button - Quickly bypass countries once mastered
- Enhanced Context - Show neighboring countries and facts after correct guesses
- Custom Playlists - Create and share country collections
- Cloud Sync - Cross-device progress synchronization
- Multiplayer Mode - Compete with friends in real-time geography challenges
- Achievements System - Unlock rewards for learning milestones
- Touch precision on very small countries or islands
- Occasional rendering delays on older devices
- Handling of disputed territories and changing borders
This project is licensed under the MIT License - see the LICENSE file for details.
- Map data contributors and geographic information sources
- Flutter and Dart development communities
- Early testers and feedback providers
- Educational research on spaced repetition learning techniques
Map Mayhem is committed to providing an engaging, educational experience that makes learning world geography fun and effective. We continuously improve based on user feedback and educational best practices.