🎮 Astraea - AI Game Generator

Astraea is an AI-powered educational game generator that creates interactive HTML5 games from natural language prompts. Perfect for teachers who want to create custom learning games without coding.

✨ Features

• 🤖 Multi-Model AI Pipeline - Uses Falcon-7B for concept generation, BLIP-2 for image analysis, and Gemini-1.5 for code generation
• 🎨 Asset Integration - Automatically incorporates available game assets (sprites, tiles, backgrounds)
• 🎯 Real-time Leaderboards - Live scoring and competition via WebSockets
• 👨‍🏫 Teacher Dashboard - Manage game sessions and track student progress
• 🎮 Instant Preview - Test games before sharing with students

🏗️ Project Structure

Astraea/
├── backend/          # Python Flask API with AI models
│   ├── assets/       # Game assets (sprites, tiles, backgrounds)
│   ├── prompts/      # System prompts for AI models
│   └── scripts/      # Game libraries (Phaser, Howler, etc.)
├── frontend/         # Next.js web application
│   ├── components/   # React components
│   ├── pages/        # Next.js pages
│   └── services/     # API and WebSocket clients
└── README.md         # This file

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• CUDA-compatible GPU (12GB+ VRAM recommended)
• Gemini API Key (Get one here)
• Hugging Face Token (Get one here)

1. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your API keys

# Start backend
python server.py

Backend runs on http://localhost:3001

2. Frontend Setup

cd frontend

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local if needed (defaults work for local development)

# Start frontend
npm run dev

Frontend runs on http://localhost:3000

📝 Environment Variables

Backend (.env)

GEMINI_API_KEY=your_gemini_api_key_here
HF_TOKEN=your_huggingface_token_here
PORT=3001
HOST=0.0.0.0
CORS_ORIGINS=http://localhost:3000,http://localhost:3001

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:3001/api
NEXT_PUBLIC_WS_URL=http://localhost:3001

🎯 Usage

For Teachers

1. Create a Game

   • Navigate to "Game Creator"
   • Enter a prompt like "Create a math game where students catch falling numbers that add up to 10"
   • Wait for generation (~30-60 seconds)
   • Preview and test the game

2. Start a Session

   • Create a session from your generated game
   • Share the session code with students

3. Monitor Progress

   • View real-time leaderboard
   • Track student scores

For Students

1. Enter session code on home page
2. Enter your name
3. Play the game
4. Scores automatically submit to leaderboard

🤖 AI Pipeline

User Prompt
    ↓
[Falcon-7B] → Game Concept & Mechanics
    ↓
[BLIP-2] → Analyze Available Assets
    ↓
[Gemini-1.5] → Generate Complete Game Code
    ↓
HTML5 Game

📦 Technology Stack

Backend

• Flask - Web framework
• Flask-SocketIO - WebSocket support
• PyTorch - Deep learning
• Transformers - Hugging Face models
• Gemini API - Code generation

Frontend

• Next.js 14 - React framework
• TailwindCSS - Styling
• Socket.io-client - Real-time updates
• React Query - Data fetching

Game Libraries (Auto-injected)

• Phaser 3 - Game engine
• Howler.js - Audio
• Matter.js - Physics

🔧 Development

Backend Development

cd backend
python server.py

Models auto-load on first request (takes ~2-3 minutes).

Frontend Development

cd frontend
npm run dev

Hot reload enabled by default.

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions welcome! Please open an issue or PR.

🐛 Troubleshooting

"CUDA out of memory"

• Close other GPU applications
• Reduce max_new_tokens in game_generator_multi.py
• Use smaller models

"Connection refused" on frontend

• Ensure backend is running on port 3001
• Check CORS_ORIGINS in backend config

Models fail to load

• Verify HF_TOKEN is valid
• Check internet connection
• Ensure sufficient disk space (~20GB for models)

📧 Support

For issues or questions, please open a GitHub issue.

---

Built with ❤️ for educators