Skip to content
xjjohnsonPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

Math Game

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.

Status

  • 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.

Running it

npm install
npm run web        # open in a browser on this computer
npm test           # unit tests
npm run typecheck

On 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.

Building the Android app (APK)

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 preview

When 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 USB

The android/ folder is generated by npx expo prebuild and isn't committed.

Testing Nearby on two phones

  1. Install the APK on both Android phones. Turn on Bluetooth and Wi-Fi on both.
  2. On each phone: Settings → 📡 Play nearby (test) → Allow.
  3. Tap Try the Nearby test. On phone A tap Host. On phone B tap Find, then tap phone A's name.
  4. 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.

Layout

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

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages