A math learning game for kids ages 5-15: flashcards, speed drills, rewards and two-device multiplayer. Built with Expo, React Native and TypeScript for Android, with a web build for PC.
The full plan lives in docs/build-plan.md.
- Phase 1: scaffold (Expo Router navigation, theme, multi-profile store, settings store)
- Phase 2: math engine and unit tests
- Phase 3: single-player core (10-question rounds, scoring, per-question timers, number pad, streaks, times tables, adaptive difficulty, results and high scores)
- Phase 4: rewards (coins, stars, streak bonuses, daily challenge, day streak calendar, progress screen, sound effect hooks)
- Phase 5: shop and avatar (avatars, backgrounds, card styles, buddies), badges, weekly goals
- Phase 6: polish (bigger problems stacked in columns, animations, read aloud, vibration, dyslexia font, colorblind colors, reduce motion, word problems, tricky-facts review, PIN-protected parent report)
- Phase 7: Nearby permission screen and two-phone prototype (confirmed on two Android phones)
- Phase 8: play with friends: Race and Co-op Defense on up to 8 phones over Nearby (one host, the rest join), and take-turns for 2-6 players on one phone
- Phases 9-10: see the build plan
Sounds are placeholder tones on web and silent on Android until real sound files are added.
npm install
npm run web # open in a browser on this computer
npm test # unit tests
npm run typecheckOn Android, everything except playing nearby runs in Expo Go (npm start, then scan the QR code).
Playing nearby uses our own native module (modules/math-nearby), so it needs a real app build.
Easiest: let GitHub build it. Every merge to main runs the "Android APK" workflow, which posts
the app on the Latest Android app release. On each phone, open that page
(signed in to GitHub, since the repo is private), tap math-game.apk, and allow installing from the
browser when asked. To build without merging, open the Actions tab → Android APK → Run workflow.
Updating. Each build is stamped with its workflow run number, and the release also carries a
version.json with that number. On launch the app reads it, and when a newer build is out, Home shows
an "Update now" button that downloads the APK and opens Android's installer (Settings → Check for
updates does the same). This needs the release to be downloadable without signing in, so the repo has
to be public.
The other two ways also give an .apk to install on each phone.
In the cloud with EAS (no Android Studio needed):
npx eas-cli@latest login # free Expo account
npx eas-cli@latest build -p android --profile previewWhen it finishes, open the link it prints on each phone, or scan the QR code, to download the APK.
On your own computer with Android Studio:
npx expo run:android --variant release # with a phone plugged in over USBThe android/ folder is generated by npx expo prebuild and isn't committed.
- Install the APK on both Android phones. Turn on Bluetooth and Wi-Fi on both.
- On each phone: Settings → 📡 Play nearby (test) → Allow.
- Tap Try the Nearby test. On phone A tap Host. On phone B tap Find, then tap phone A's name.
- Both phones show "Connected" and the same 4-digit code. Tap Send hello on either phone and the message shows up on the other one.
Emulators can't do this; it needs two real phones.
src/app routes (Expo Router); each file just renders a screen
src/screens Home, Profiles, ModePicker, Play (round + results), Progress, Shop, Settings,
Parent, Permissions, NearbyTest
src/components BigButton, OptionGroup, ChoiceButtons, NumberPad, FlashCard, TimerBar,
StreakCalendar, CompanionBubble, Screen
src/constants theme, difficulty configs, shop catalog, badges
src/store Zustand stores persisted to AsyncStorage
src/utils mathEngine, gameSession, scoring, adaptive, rewards, progress, dates,
shop, badges, weekly, soundEffects, seededRandom (+ tests in __tests__)
src/test shared test fixtures
src/types shared types
src/hooks useTimer, useGameSession
src/services multiplayer transports (Phases 8-9)
modules/math-nearby native Android module wrapping Google Nearby Connections, and its
config plugin that adds the Bluetooth / Wi-Fi permissions