Math Dragons
Dragon-powered math games that are actually fun! A collection of four math mini-games wrapped in a whimsical dragon fantasy world, built with Flutter.
Current Status
Step 10 complete — Firebase integration with anonymous auth, optional Google Sign-In, offline-first Firestore cloud sync, conflict resolution, and backup prompt system.
MathDragonsGame, event types, reward config)PlayerProfile data model with Hive persistence (scales, evolution, game stats)EventBus for decoupled game-to-service communicationRewardService with full scale earning logicFactTracker tracking per-fact accuracy and masterySessionManager tracking app and game session stateHapticsService with named haptic patternsLocalStorage (Hive) with profile, fact history, and meta boxesSchema migration system (forward-only, versioned)Enhanced GameRegistry with sorted queries and storage dependencyProvider wiring — all services accessible from any widgetHub screen — data-driven from PlayerProfile, scrollable layoutDragon companion — animated pulsing egg/dragon on hub screenGame cards — show real level, star count, world progress, tap animationProfile bar — dragon name, evolution stage name, formatted scales counterDaily challenge card — static placeholder with example tasksSettings screen — dragon name text field, sound/music/haptics toggles, about sectionGame shell — shared HUD (scales, level), pause overlay (Resume/Settings/Quit), SessionManager integrationResult screen — animated stars, scales counter tick-up, stats grid, Play Again/Back to HubCustom navigation transitions — fade+scale for games, slide for settingsDragon Eggs (Step 4) — Bubble Pop port with falling eggs, equation builder, 6 difficulty tiers, combo system, auto-leveling, Flame engineFire Trail (Step 5) — Math Snake port with grid movement, D-pad + swipe controls, flame intensity mechanic, 5 worlds (40 levels), answer gems, sparkle effects, countdownDragon Runes (Step 6) — Number Links port with circular node layout, drag-to-connect chain mechanics, equation validation, level generation, hint system, spell-casting particle effects, 5 worlds (50 levels)Dragon's Feast (Step 7) — Merged Muncher port with 5x5 grid navigation, 26+ math categories (even/odd, multiples, primes, composites, perfect squares, factors, ranges), enemy AI (chasers + wanderers), power-ups (freeze/wings/shield), 5 worlds (40 levels)Adaptive Difficulty (Step 8) — DifficultyEngine with per-operation accuracy tracking, adaptive level selection, performance windows, EventBus integrationProblem Generation Design — documented curriculum/scheduler/adapter methodology with solvability and spacing invariantsProgressionManager (Step 8) — Dragon evolution stages (Egg→Elder Dragon), XP system, evolution thresholds, cross-game progress trackingAchievement System (Step 9) — 52 achievements across 3 categories (per-game, cross-game, milestones), reactive EventBus-based unlocking, achievement popup overlay, tabbed browser screenDaily Challenges (Step 9) — 2-3 deterministic tasks per day, 5 challenge types, streak tracking with bonus scales, hub card with live progressCosmetics Store (Step 9) — 8 dragon colors + 6 accessories purchasable with Dragon Scales, store screen with purchase/equip flowAnimated Scales Counter (Step 9) — Tick-up animation with gold particle effects for scale rewardsAchievement Popup (Step 9) — Slide-down banner notification with sequential queue, haptic feedbackFirebase Auth (Step 10) — Anonymous auth on first launch (invisible), optional Google Sign-In upgrade for cross-device backupCloud Sync (Step 10) — Offline-first Firestore sync (profile, facts, achievements, daily challenges), debounced writes, background sync on connectivity changeConflict Resolution (Step 10) — Per-field max for scalars, union for additive data, merge for game stats and level starsBackup Prompt (Step 10) — Non-blocking bottom sheet at evolution stage 2+, 7-day cooldown, Google Sign-In flowSync Indicator (Step 10) — Cloud status icon in profile bar (synced/syncing/offline)Connectivity Monitor (Step 10) — Auto-retry Firebase init and sync on network reconnectionFirestore Security Rules (Step 10) — User-scoped access with data validationParent-gated links — Settings > For Parents opens playmathdragons.com privacy, feedback and support pages, each behind a parental gate (two-digit multiplication, App Store 1.3 Kids Category rule); url_launcher opens the system browserFounding-tester flag — beta installs are marked locally (lib/core/founding_tester.dart, app_meta box) so beta families can get the paid unlock free at full release; nothing leaves the deviceNo network permission — release Android manifest declares no INTERNET permission (the app makes no network calls)613 tests — all passingflutter analyze passes cleanflutter test passes — all greenflutter build apk --debug succeeds
Games
Game Theme Math Skills Status Dragon Runes Ancient rune puzzles Equation building, all 4 operations Playable Fire Trail Dragon flight Mental math under time pressure Playable Dragon Eggs Egg hatching Equation assembly from falling eggs Playable Dragon's Feast Treasure feast Number properties, categorization Playable
Prerequisites
Flutter SDK 3.41+ (Dart 3.11+)Android SDK with platform toolsAn Android emulator or physical device (for running the app)
Installing Flutter (Windows, via Scoop)
scoop bucket add extras
scoop install extras/flutter
Verify installation:
flutter --version
flutter doctor
Building & Running Locally
1. Get dependencies
cd math_dragons
flutter pub get
2. Generate Hive adapters and localization files
dart run build_runner build --delete-conflicting-outputs
flutter gen-l10n
3. Run static analysis
flutter analyze
This should report no issues .
4. Run tests
flutter test
All 535 tests should pass.
5. Build a debug APK
flutter build apk --debug
The APK will be at build/app/outputs/flutter-apk/app-debug.apk.
6. Run on a connected device or emulator
# List available devices
flutter devices
# Run on the default device
flutter run
# Run on a specific device
flutter run -d <device-id>
Project Structure
math_dragons/
├── lib/
│ ├── main.dart # App entry point (initializes Hive, runs app)
│ ├── app.dart # StatefulWidget with MultiProvider + lifecycle
│ ├── core/
│ │ ├── game_interface.dart # MathDragonsGame contract
│ │ ├── game_events.dart # Sealed GameEvent types
│ │ ├── game_registry.dart # Game discovery + sorted queries
│ │ ├── event_bus.dart # Stream-based typed pub/sub
│ │ ├── player_profile.dart # PlayerProfile, GameStats, PlayerSettings (Hive)
│ │ ├── reward_service.dart # Scales earning logic + EventBus listener
│ │ ├── fact_tracker.dart # FactRecord model + tracking service
│ │ ├── session_manager.dart # App/game session tracking
│ │ ├── haptics.dart # Named haptic patterns
│ │ ├── difficulty_engine.dart# Adaptive difficulty engine
│ │ ├── progression_manager.dart # Dragon evolution + XP system
│ │ ├── achievement.dart # Achievement data model + 52 definitions
│ │ ├── achievement_tracker.dart # EventBus listener + unlock logic
│ │ ├── daily_challenge.dart # Daily challenge data model
│ │ └── daily_challenge_manager.dart # Challenge generation + tracking
│ ├── storage/
│ │ ├── local_storage.dart # Hive wrapper (profiles, facts, meta)
│ │ ├── migration.dart # Schema migration runner (v2)
│ │ ├── cloud_sync.dart # Offline-first Firestore sync manager
│ │ ├── sync_resolver.dart # Conflict resolution (max/union/merge)
│ │ └── connectivity_monitor.dart # Network state monitoring + auto-retry
│ ├── auth/
│ │ ├── auth_service.dart # Firebase Auth wrapper (anonymous + Google)
│ │ ├── anonymous_auth.dart # UID ↔ PlayerProfile linkage manager
│ │ └── account_upgrade.dart # Google Sign-In upgrade flow
│ ├── hub/ # Hub screen, game cards, profile bar, settings
│ ├── dev/ # Debug-only internal tooling (accessory calibration)
│ ├── navigation/ # Custom page route transitions
│ ├── games/
│ │ ├── shared/ # Game shell, result screen, shared components
│ │ │ └── problem_generation.dart # Curriculum components, mastery estimates, scheduler, validators
│ │ ├── dragon_runes/ # Number Links port (Flame game)
│ │ │ ├── components/ # Rune nodes, connection line, particles, hints
│ │ │ ├── models/ # RuneNodeData, EquationTarget, config, equations
│ │ │ ├── systems/ # Chain manager, equation validator, level generator, scoring, hints
│ │ │ └── widgets/ # Target panel, chain display, hint button, score display
│ │ ├── fire_trail/ # Math Snake port (Flame game)
│ │ │ ├── components/ # Dragon head, trail segments, gems, grid, sparkles
│ │ │ ├── models/ # GridPosition, Direction, FlameIntensity, config
│ │ │ ├── systems/ # Movement, problem generation, trail management
│ │ │ └── widgets/ # D-pad, flame meter, problem display, countdown
│ │ ├── dragon_eggs/ # Bubble Pop port (Flame game)
│ │ │ ├── components/ # Eggs, danger line, equation, toast, sparkle
│ │ │ └── models/ # Egg data, difficulty, math problems, scoring
│ │ └── dragons_feast/ # Merged Muncher port (Flame game)
│ │ ├── components/ # Grid, tiles, dragon, enemies, power-ups, effects
│ │ ├── models/ # GridCell, MathCategory, EnemyType, FeastConfig
│ │ ├── systems/ # Category system, board generator, enemy AI, power-ups, collision
│ │ └── widgets/ # Category display, lives, score, D-pad, transitions
│ ├── monetization/
│ │ └── store_screen.dart # Cosmetics store (scales purchasing)
│ ├── widgets/
│ │ ├── achievement_popup.dart # Slide-down achievement notification
│ │ ├── animated_scales_counter.dart # Animated counter with particles
│ │ └── cosmetic_preview.dart # Dragon cosmetic display widget
│ ├── rewards/ # Palace builder (v2 stub)
│ ├── l10n/ # Localization (ARB + generated)
│ └── theme/ # Colors, typography, spacing
├── assets/
│ ├── fonts/ # Cinzel, Nunito, JetBrains Mono
│ ├── images/ # Dragons, hub, games, UI (placeholders)
│ ├── animations/ # Rive/Lottie files (placeholder)
│ └── sounds/ # Music + SFX (placeholder)
├── test/
│ ├── core/ # Unit tests for models and services
│ ├── storage/ # Storage/migration tests
│ ├── hub/ # Hub widget unit tests (profile bar, etc.)
│ ├── navigation/ # Route mapping tests
│ ├── games/shared/ # Game shell and result screen tests
│ ├── games/dragon_eggs/ # Dragon Eggs game tests (75 tests)
│ ├── games/fire_trail/ # Fire Trail game tests (69 tests)
│ ├── games/dragon_runes/ # Dragon Runes game tests (61 tests)
│ ├── games/dragons_feast/ # Dragon's Feast game tests (90 tests)
│ ├── monetization/ # Store screen tests
│ └── integration/ # Integration tests (placeholder)
├── docs/ # Planning documents, including MATH_PROBLEM_GENERATION_DESIGN.md
└── pubspec.yaml
Hive Type ID Registry
typeId Class File 0 PlayerProfilecore/player_profile.dart1 GameStatscore/player_profile.dart2 PlayerSettingscore/player_profile.dart3 FactRecordcore/fact_tracker.dart4 FactStatus (enum)core/fact_tracker.dart5 UnlockedAchievementcore/achievement.dart6 DailyChallengeStatecore/daily_challenge.dart
Design Documents
Tech Stack
Framework: Flutter 3.41 / Dart 3.11Game Engine: Flame (included, used in later steps)State Management: ProviderLocal Storage: Hive (with code-generated adapters)Cloud Backend: Firebase (Auth + Firestore, offline-first sync)Auth: Firebase Anonymous Auth + optional Google Sign-In upgradeFonts: Cinzel (headings), Nunito (body), JetBrains Mono (counters)
Firebase (removed)
The app no longer contains any Firebase code or packages (verified 2026-10-19). It is fully offline, has no accounts, and collects no data. Leftover Firebase project files (firebase.json, firestore.rules) and the unused firebaseUid/linkedProvider profile fields remain only for history and existing installs; they are not used.
Notes
Windows Developer Mode is recommended for plugin builds. Enable via start ms-settings:developers.The app is dark-themed by default (dragon's lair aesthetic).
All user-facing strings go through Flutter's localization system -- no hardcoded strings.
After modifying Hive-annotated classes, run dart run build_runner build --delete-conflicting-outputs to regenerate adapters.
After modifying ARB files, run flutter gen-l10n to regenerate localization classes.
