REAL WORLD × AI × GAMING 🎮

"Turn the Real World into a Game."
An interactive web game designed to drastically reduce children's screen time by incentivizing real-world offline activities through AI vision verification and adventure game progression.

---

🌟 Core Idea & Philosophy

Traditional digital games trap children in front of glowing screens for hours. REAL WORLD × AI × GAMING flips the paradigm: the screen becomes a game master, while the real world becomes the playing field.

Instead of tapping virtual buttons, children receive age-appropriate real-world quests such as:

• 🌿 Nature: Water a plant, find 3 green leaves, sprout a seed, observe birds.
• 🧹 Home & Organizing: Clean study desk, arrange 5 books neatly, fold clothes.
• 🎨 Creativity & Craft: Draw an animal from life, build something from recyclables.
• 🤝 Helping & Kindness: Help set the dinner table, write a thank-you letter.
• 🏃 Fitness: 15 star jumps, outdoor walk, stretching.
• 🛠️ Building: Build a paper bridge, craft a phone stand.

The player performs the mission in the physical world, snaps a photo proof using their camera or phone, and submits it. A multimodal AI Vision Model (Google Gemini) inspects the photo to confirm that the task was genuinely completed. If verified, the player earns XP, Gold Coins, advances through 10 Levels, builds Daily Streaks, and unlocks Explorer Badges!

🛡️ Child Safety & Privacy by Design

• Face is NEVER required: The AI strictly inspects the object, organized items, artwork, or craft, rather than the child's identity.
• Strict Safety Prompts: The AI task generator strictly bans tasks involving fire, electricity, sharp objects, heights, roads, or hazardous chemicals.
• Age-Appropriate Segmentation: Automatically assigns tasks suited to 5–8 ("Junior Explorer"), 9–12 ("Adventure Explorer"), or 13–16 ("Master Explorer").

---

🏗️ Tech Stack

Frontend

• Framework: React 18 with TypeScript
• Bundler: Vite 6
• Styling: Tailwind CSS with custom adventure game palette, 3D buttons, and radar animations
• Icons: Lucide React
• Celebrations: Canvas Confetti
• Audio & SFX: Browser-native Web Audio API synthesizer (click chimes, victory fanfare, fail buzzers, and optional ambient chord loops with zero external audio download dependencies)

Backend

• Runtime: Node.js (v18+) with Express.js and TypeScript (tsx)
• Database & ORM: PostgreSQL with Prisma ORM (includes seamless local JSON store fallback for zero-friction hackathon evaluation)
• File Uploads: Multer with strict MIME validation (JPEG, PNG, WebP) and 10MB limit
• AI Multimodal Model: Google Gemini API (gemini-2.5-flash / gemini-1.5-flash) for live image verification and quest generation

---

📁 Project Structure

antigravity/
├── backend/
│   ├── data/                 # Local persistence cache & storage
│   ├── prisma/
│   │   └── schema.prisma     # Prisma schema (User, Level, Task, MissionCompletion, Streak, Badge, UserBadge)
│   ├── src/
│   │   ├── ai/
│   │   │   ├── imageVerifier.ts # Multimodal Gemini AI vision verification
│   │   │   └── taskGenerator.ts # Gemini AI age-appropriate task generator
│   │   ├── controllers/
│   │   │   ├── taskController.ts # Task generation, listing, verification, completion
│   │   │   └── userController.ts # Player signup, profile, streaks, badges, progress
│   │   ├── middleware/
│   │   │   └── upload.ts     # Multer multipart/form-data validation
│   │   ├── routes/
│   │   │   ├── taskRoutes.ts # /api/tasks routes
│   │   │   └── userRoutes.ts # /api/users routes
│   │   ├── services/
│   │   │   └── db.ts         # Dual-capable database layer (Prisma PostgreSQL + fallback)
│   │   ├── types/
│   │   │   └── index.ts      # TypeScript interfaces
│   │   ├── utils/
│   │   │   ├── seed.ts       # Database seeder script
│   │   │   └── seedData.ts   # 300 curated offline quests & badges
│   │   └── server.ts         # Express server entrypoint
│   ├── uploads/              # Stored proof photographs (.gitkeep)
│   ├── .env.example          # Sample environment configuration
│   ├── package.json
│   └── tsconfig.json
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── BadgeCard.tsx          # Achievement badge card with lock/unlock states
│   │   │   ├── Navbar.tsx             # Player stats, level, XP, coins, audio toggles
│   │   │   ├── PlayMissionModal.tsx   # "Your Next Mission" AI quest popup
│   │   │   └── VerificationModal.tsx  # Animated radar scan, AI score gauge, rewards
│   │   ├── pages/
│   │   │   ├── CompletedMissions.tsx  # Trophy gallery with category filters & photo previews
│   │   │   ├── Home.tsx               # Main game dashboard & hero PLAY trigger
│   │   │   ├── Levels.tsx             # Levels 1 to 10 with 10 missions per level
│   │   │   ├── Onboarding.tsx         # Player name, age classification, avatar picker
│   │   │   ├── Profile.tsx            # Explorer profile, level progress & badges showcase
│   │   │   ├── Settings.tsx           # Audio FX & music toggles, logout modal
│   │   │   ├── Streaks.tsx            # Daily flame counter, 7-day rewards & calendar
│   │   │   └── TaskDetail.tsx         # Camera capture input, photo preview, verify trigger
│   │   ├── services/
│   │   │   ├── api.ts                 # REST API client
│   │   │   └── soundEffects.ts        # Web Audio API game synthesizer
│   │   ├── styles/
│   │   │   └── index.css              # Custom game styling and keyframe animations
│   │   ├── types/
│   │   │   └── index.ts               # Frontend TypeScript types
│   │   ├── App.tsx                    # Master game view coordinator
│   │   └── main.tsx                   # Vite React root
│   ├── index.html
│   ├── package.json
│   ├── tailwind.config.js
│   ├── tsconfig.json
│   └── vite.config.ts
│
├── package.json                       # Root script orchestrator
└── README.md                          # Full documentation

---

🚀 Quick Start Guide

Prerequisites

• Node.js: v18.0.0 or higher
• npm: v9.0.0 or higher
• (Optional) PostgreSQL: v14+ (if using live PostgreSQL; otherwise the built-in local store works immediately out of the box).
• (Optional) Google Gemini API Key: from Google AI Studio for live AI vision verification.

---

1. Installation

You can install all dependencies for both backend and frontend from the root:

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

Or from the workspace root:

npm run install:all

---

2. Backend Setup & Environment Variables

Navigate to backend/:

cd backend

Create your .env file by copying the example:

cp .env.example .env

Configure backend/.env:

# Server Port
PORT=5000
NODE_ENV=development

# Database Connection (PostgreSQL)
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/real_world_game?schema=public"

# AI Configuration (Google Gemini API Key)
# Obtain your free API key at: https://aistudio.google.com/
AI_API_KEY="your_gemini_api_key_here"

# Verification Score Threshold (Pass if score >= 70)
VERIFICATION_PASS_THRESHOLD=70

Developer Note on Missing API Key:
In accordance with the hackathon rules, if AI_API_KEY is not provided during development, the backend will return a clear, informative message explaining that the key is required rather than silently faking verification.

---

3. Database Setup & Prisma Migration

Generate the Prisma Client:

cd backend
npm run prisma:generate

If you have a PostgreSQL database running locally or in Docker:

# Push schema to PostgreSQL database
npm run prisma:push

# Or run standard migration
npm run prisma:migrate

# Seed all 300 missions (10 levels × 10 tasks × 3 age groups) and badges
npm run seed

Zero-Friction Fallback:
If PostgreSQL is not started on your machine yet, the backend automatically detects this and uses the built-in JSON persistence store in backend/data/storage.json, fully seeded with all 300 offline missions, 10 levels, streaks, and badges.

---

4. Running the Application

Option A: Running with Two Terminals (Recommended)

Terminal 1 — Backend:

cd backend
npm run dev

Backend runs on http://localhost:5000

Terminal 2 — Frontend:

cd frontend
npm run dev

Frontend runs on http://localhost:5173

Open http://localhost:5173 in your web browser.

---

📡 API Documentation

Method	Endpoint	Description	Request Body / Params
GET	/api/health	Health & info check	None
POST	/api/users	Register / login explorer	{ name: string, age: number, avatar?: string }
GET	/api/users/:id	Get explorer profile	None
PATCH	/api/users/:id	Update profile info	{ name?: string, avatar?: string }
GET	/api/users/:id/progress	Get XP, coins, level, progress %	None
GET	/api/users/:id/streak	Get streak count, 7-day rewards, history	None
GET	/api/users/:id/badges	Get badges with earned status	None
GET	/api/users/:id/missions	Get verified completed missions	None
GET	/api/tasks	Get level quests	?ageGroup=9-12&level=1
GET	/api/tasks/:id	Get single task details	None
POST	/api/tasks/generate	AI-generated dynamic quest	{ age: 10, ageGroup: "9-12", level: 1, previousTasks: [] }
POST	/api/tasks/:id/verify	Upload photo & verify with AI Vision	multipart/form-data: image, taskId, userId
POST	/api/missions/:id/complete	Complete verified mission	{ userId, proofImageUrl, verificationScore }

---

🔍 How AI Image Verification Works

1. Photo Upload: The child captures or selects a photo of the completed offline mission via <input type="file" accept="image/*" capture="environment">.
2. Pre-flight Validation: The Express backend Multer middleware verifies file type (image/jpeg, image/png, image/webp) and enforces a 10MB size limit.
3. Task Grounding: The backend retrieves the specific quest details (e.g. title: "Water a Plant", description: "Find a houseplant or garden plant and gently water it").
4. Multimodal Vision Analysis: The backend converts the image buffer into base64 and invokes Google Gemini's multimodal vision API (gemini-2.5-flash).
5. Privacy-Focused Prompting:
   • The model is instructed: "Focus only on visible evidence relevant to the task (e.g. watered soil, organized books, finished drawing). Do not identify the child. Do not require the child's face. Do not reject valid evidence simply because the child is not visible."
6. Structured Evaluation: The model returns:

   {
     "passed": true,
     "score": 92,
     "reason": "The photo clearly shows a houseplant in fresh, damp soil with a watering can nearby."
   }

7. Threshold Decision:
   • score >= 70: Approved. XP and Coins are credited, level progress updates, daily streak registers, badges evaluate, and the next mission unlocks!
   • score < 70: Not Verified. Constructive feedback is shown, and the child can immediately re-upload another photo without losing progress.

---

🎮 Game Mechanics & Progression

• Age Groups:
  • Group 1 (5–8 yrs): "Junior Explorer" — Sensory discovery, gentle organization, drawing, toy pairing.
  • Group 2 (9–12 yrs): "Adventure Explorer" — Recycled crafts, book sorting, simple food prep, leaf rubbing.
  • Group 3 (13–16 yrs): "Master Explorer" — Mini herb gardens, DIY organizers, workouts, desk cable management.
• 10 Levels & 100 Missions per Age Group:
  • Level 1: Very Easy (+50 XP, +10 Coins)
  • Level 2–3: Easy / Easy+ (+60 XP, +15 Coins)
  • Level 4–6: Medium (+75 XP, +20 Coins)
  • Level 7–8: Challenging (+100 XP, +25 Coins)
  • Level 9–10: Hard / Champion (+150 XP, +35 Coins)
• 7-Day Streak Rewards:
  • Day 1: +10 coins
  • Day 2: +15 coins
  • Day 3: +20 coins
  • Day 4: +25 coins
  • Day 5: +30 coins
  • Day 6: +40 coins
  • Day 7: +100 coins + 7-Day Streak Master Badge
• Badges:
  • 🌟 First Mission: Complete first real-world quest.
  • 🎯 5 Missions: Complete 5 quests.
  • 🏆 10 Missions: Complete 10 quests.
  • 🔥 7 Day Streak: Maintain a full 7-day streak.
  • 🌿 Nature Explorer: Complete 3 nature quests.
  • 🤝 Kind Helper: Complete 3 helping quests.
  • 🎨 Creative Mind: Complete 3 creativity/building quests.
  • 👑 Champion: Complete Level 10.

---

🔒 Security & Child Privacy Standards

• Zero Face Recognition: AI prompt instructions explicitly instruct the vision model to ignore faces and focus on physical task outcomes.
• Backend Key Isolation: API keys (AI_API_KEY, DATABASE_URL) are strictly kept on the Express backend; no sensitive keys are ever packaged into frontend bundles.
• CORS & Rate Limiting Ready: Express includes CORS origin protection, JSON body limits, and Multer file validation.
• Sanitized Uploads: Image files are renamed with cryptographically random timestamps before storage.

---

🏆 Hackathon Submission Checklist

• Full-stack architecture (React + TypeScript + Vite frontend & Express + TypeScript backend).
• PostgreSQL database schema with Prisma ORM.
• Zero-friction local database fallback for instant reviewer evaluation.
• Real Google Gemini Vision verification engine for photo evidence.
• Strict child privacy protections (no face requirement).
• 3 Age Groups with 10 Levels and 10 Missions each (300 total slots).
• Daily streak tracker with 7-day reward calendar.
• Completed Missions gallery with category filtering.
• Sound effects and gentle ambient music via Web Audio API.
• Clean, responsive, modern adventure game UI.

Ollama image verification

This project now uses local Ollama + Qwen2.5-VL for mission photo verification.

1. Install Ollama.
2. Download the vision model: ollama pull qwen2.5vl:3b
3. Make sure Ollama is running.
4. In backend, install dependencies with npm install.
5. Start the backend with npm run dev.
6. Start the frontend with npm run dev.

The verification endpoint sends only the current uploaded mission image plus the current task title/description to Ollama. It does not send previous uploaded images.

Default Ollama configuration:

• OLLAMA_URL=http://localhost:11434
• OLLAMA_MODEL=qwen2.5vl:3b
• VERIFICATION_PASS_THRESHOLD=70