BalloonMath

A lightweight mental-math balloon game for kids. Timed rounds, rising balloons, telephone-style dialpad input, per-kid accounts with persistent stats. Runs as a PWA so kids can "Add to Home Screen" on Android and launch fullscreen.

Stack

• React + Vite + TypeScript
• vite-plugin-pwa for the manifest + service worker
• Supabase for auth and the stats table

Setup

1. Install deps:

   npm install

2. Create a Supabase project at https://supabase.com and grab the project URL + anon key.
3. Copy the env template and fill it in:

   cp .env.template .env
   # edit .env and set VITE_SUPABASE_URL + VITE_SUPABASE_ANON_KEY

4. Apply the database schema. In the Supabase dashboard → SQL Editor, paste and run the contents of supabase/migrations/0001_init.sql. This creates the stats table, row-level security policy, and the auth-user trigger that auto-creates a stats row for each new sign-up.
5. (Optional) Turn off "Confirm email" in Supabase → Authentication → Providers → Email → "Confirm email" if you want kids to sign up and play without clicking a confirmation link. Alternatively, keep it on and have them click the link on their first sign-up.

Develop

npm run dev

Open http://localhost:5173 in Chrome and use device emulation (DevTools → Toggle Device Toolbar → iPhone 12 Pro or similar) for a phone-shaped preview.

Build

npm run build
npm run preview   # serves the production build locally

Deploy

Any static host works. For Netlify or Vercel:

• Connect this repo.
• Build command: npm run build
• Publish dir: dist
• Env vars: VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY

After deploy, on an Android phone:

1. Open the URL in Chrome.
2. Chrome menu → Add to Home Screen.
3. Launch from the home screen — it opens full-screen in portrait.

Game rules

• 60-second rounds. Balloons spawn at the bottom and rise toward spikes.
• Each balloon carries a math question. Answer via the dialpad at the bottom — auto-matches any visible balloon, no Enter key.
• Saved balloon → XP and streak + 1. Balloon hits the spikes → streak resets to 0.
• XP per balloon = 10 × difficultyMult × speedMult
  • difficulty: easy 1.0 / medium 1.5 / hard 2.0
  • speed: chill 1.0 / normal 1.5 / fast 2.0
• Difficulty controls number ranges and concurrent balloons (3 / 4 / 5).
• Speed controls rise duration (15s / 10s / 6s) and the XP multiplier.

Stats tracked (per kid)

• Best round — highest XP scored in a single round.
• Total XP — cumulative across all rounds.
• Correct streak — lifetime streak that only resets when a balloon pops.

Scripts

• npm run dev — dev server
• npm run build — type-check + Vite production build
• npm run preview — serve dist/
• npm run typecheck — TypeScript check only
• npm run check:questions — sanity-check the question generator ranges
• node scripts/make-icons.mjs — regenerate placeholder PWA icons

Customizing

• Ranges: src/game/questions.ts (CFG object)
• Pacing / XP: src/game/config.ts
• Styling: src/styles/index.css
• Icons: replace public/icons/icon-192.png + icon-512.png with real artwork