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.
- 🤖 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
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
- Python 3.11+
- Node.js 18+
- CUDA-compatible GPU (12GB+ VRAM recommended)
- Gemini API Key (Get one here)
- Hugging Face Token (Get one here)
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.pyBackend runs on http://localhost:3001
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 devFrontend runs on http://localhost:3000
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:3001NEXT_PUBLIC_API_URL=http://localhost:3001/api
NEXT_PUBLIC_WS_URL=http://localhost:3001-
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
-
Start a Session
- Create a session from your generated game
- Share the session code with students
-
Monitor Progress
- View real-time leaderboard
- Track student scores
- Enter session code on home page
- Enter your name
- Play the game
- Scores automatically submit to leaderboard
User Prompt
↓
[Falcon-7B] → Game Concept & Mechanics
↓
[BLIP-2] → Analyze Available Assets
↓
[Gemini-1.5] → Generate Complete Game Code
↓
HTML5 Game
- Flask - Web framework
- Flask-SocketIO - WebSocket support
- PyTorch - Deep learning
- Transformers - Hugging Face models
- Gemini API - Code generation
- Next.js 14 - React framework
- TailwindCSS - Styling
- Socket.io-client - Real-time updates
- React Query - Data fetching
- Phaser 3 - Game engine
- Howler.js - Audio
- Matter.js - Physics
cd backend
python server.pyModels auto-load on first request (takes ~2-3 minutes).
cd frontend
npm run devHot reload enabled by default.
MIT License - See LICENSE file for details
Contributions welcome! Please open an issue or PR.
- Close other GPU applications
- Reduce
max_new_tokensingame_generator_multi.py - Use smaller models
- Ensure backend is running on port 3001
- Check CORS_ORIGINS in backend config
- Verify HF_TOKEN is valid
- Check internet connection
- Ensure sufficient disk space (~20GB for models)
For issues or questions, please open a GitHub issue.
Built with ❤️ for educators