DrawnBetween

AI-Powered Multiplayer Guessing Game

DrawnBetween is a web-based multiplayer game that combines AI image generation with word association gameplay. Players take turns creating images from three words using Stable Diffusion AI, while others try to guess the original words that generated the image.

How It Works

1. Create: One player enters three words (e.g., "cat", "space", "pizza")
2. Generate: AI creates an image based on those words using Stable Diffusion
3. Guess: Other players try to guess the original three words
4. Score: Points awarded for correct guesses, with bonuses for being first
5. Repeat: Players take turns being the prompter

Game Modes

• Solo Play: Practice mode for single players
• Two Player: Classic head-to-head gameplay
• Group Play: Multiplayer mode supporting up to 8 players with leaderboards

Architecture

Frontend (Flask Application)

• Main App: Flask web server with user authentication
• Templates: Responsive web interface using Bulma CSS
• Real-time Updates: JavaScript-based auto-refresh for live gameplay
• Payment Integration: PayPal checkout for premium features

Backend (FastAPI + AI)

• API Server: FastAPI with WebSocket support
• AI Engine: Stable Diffusion v1.4 for image generation
• Task Queue: Redis + Celery for handling generation requests
• Database: SQLite with SQLAlchemy ORM

Infrastructure

• AWS EC2: Auto-scaling server instances
• Server Management: Automatic start/stop based on demand
• Premium Servers: Dedicated instances for paid users

Requirements

System Requirements

• OS: Linux (Ubuntu recommended)
• Python: 3.8+
• Memory: 8GB+ RAM (16GB+ recommended for AI model)
• Storage: 10GB+ free space
• GPU: CUDA-compatible GPU recommended for faster generation

Dependencies

See requirements.txt and environment.yaml for complete dependency lists.

Installation

1. Clone Repository

git clone <repository-url>
cd drawnbetween

2. Environment Setup

# Create conda environment
conda env create -f environment.yaml
conda activate drawnbetween

# Or use pip
pip install -r requirements.txt

3. Download AI Model

# Download Stable Diffusion model (4GB+)
pip install gdown
gdown https://drive.google.com/uc?id=139AzBFyGcY0nzZRlSPmkjKKzvvqSs8XK models/sd-v1-4.ckpt

4. Database Setup

# Initialize database
python -c "from app.factory import create_app, db; app = create_app(); app.app_context().push(); db.create_all()"

# Optional: Load test data
sqlite3 app/db.sqlite < db/scripts/create_tables.sql
sqlite3 app/db.sqlite < db/scripts/test_data.sql

5. Configuration

# Copy environment template
cp .env.example .env

# Edit configuration with your specific values
nano .env

Required Environment Variables:

• SECRET_KEY: Flask secret key for session management
• PAYPAL_CLIENT_ID: Your PayPal application client ID
• PAYPAL_SECRET: Your PayPal application secret key
• BACKEND_URL: URL of your AI backend server
• FRONTEND_URL: IP address of your frontend server
• FREE_SERVER_AWS_ID: AWS EC2 instance ID for free server
• PAID_SERVER_1_AWS_ID: AWS EC2 instance ID for first paid server

Optional Environment Variables:

• PAYPAL_MODE: Set to 'live' for production, 'sandbox' for testing (default: sandbox)
• NUM_PAID_SERVERS: Number of paid servers available (default: 4)
• PAID_SERVER_CAPACITY: Maximum games per paid server (default: 20)

Running the Application

Single Server Setup (Development)

# Terminal 1: Start Redis
redis-server --port 6381

# Terminal 2: Start Celery worker
celery -A celery_worker.celery worker --loglevel=info --pool=solo

# Terminal 3: Start main application
python3 run.py

# Terminal 4: Start server manager
python3 manage_peripherals.py

Production Setup (AWS EC2)

Frontend Server

# Start main application
python3 run.py

# Start peripheral manager
python3 manage_peripherals.py

Backend Server

# Set Python path
export PYTHONPATH="${PYTHONPATH}:/path/to/drawnbetween-backend/app/stable-diffusion:/path/to/drawnbetween-backend/src/taming-transformers:/path/to/drawnbetween-backend/src/clip"

# Start services
redis-server --port 6381
celery -A celery_worker.celery worker --loglevel=info --pool=solo
python3 run.py

Docker Setup

# Build and run with Docker Compose
docker-compose up -d

Usage

1. Access the Game: Navigate to http://localhost:5000
2. Create Account: Sign up with a username and password
3. Start Game: Choose game mode and invite friends with game token
4. Play: Take turns creating prompts and guessing words

Game Flow

1. Landing Page: Choose to start new game or join existing
2. Player Setup: Enter name and create/join game room
3. Gameplay Loop:
   • Prompter enters three words
   • AI generates image (15-60 seconds)
   • Other players guess the words
   • Points awarded based on accuracy
   • Next player's turn

Premium Features

Upgrade System

• Cost: $1 USD per game session
• Duration: 2 hours of premium access
• Benefits:
  • Skip waiting queues
  • Dedicated server access
  • Faster image generation
• Payment: PayPal integration

Server Tiers

• Free Tier: Shared server, potential wait times
• Premium Tier: Dedicated servers (4 available, 20 games each)

Configuration

Key Settings (app/main.py)

backend_url = 'http://172.31.47.30:5005/generate'  # AI backend
frontend_url = '172.31.15.10'                      # Frontend server
num_paid_servers = 4                               # Premium servers
paid_server_capacity = 20                          # Games per server

Server Management (manage_peripherals.py)

idle_time_limit = 3600      # Auto-stop after 1 hour idle
paid_server_time = 7200     # Premium access duration (2 hours)
game_idle_time = 86400 * 4  # Delete games after 4 days

Database Schema

Core Tables

• Server: AWS instance management and status
• Game: Game sessions, scores, and state
• Player: User accounts and game participation
• Session: Login tracking and device info

Key Relationships

• Games belong to servers
• Players participate in games
• Servers auto-scale based on demand

Security Features

• NSFW Filtering: Content moderation using forbidden word lists
• Input Validation: Sanitization of user prompts
• Session Management: Secure user authentication
• Payment Security: PayPal integration for transactions

Troubleshooting

Common Issues

Server Won't Start

# Check if ports are available
netstat -tulpn | grep :5000
netstat -tulpn | grep :6381

AI Model Issues

# Verify model download
ls -la models/sd-v1-4.ckpt
# Should be ~4GB file

Database Errors

# Reset database
rm app/db.sqlite
python -c "from app.factory import create_app, db; app = create_app(); app.app_context().push(); db.create_all()"

AWS Connection Issues

• Verify AWS credentials are configured
• Check security groups allow required ports
• Ensure EC2 instances have proper IAM roles

Project Structure

drawnbetween/
├── app/                    # Main Flask application
│   ├── templates/          # HTML templates
│   ├── static/            # CSS, JS, images
│   ├── models.py          # Database models
│   ├── main.py            # Core game logic
│   └── auth.py            # Authentication
├── backend/               # FastAPI backend
│   ├── backend/           # API routes and services
│   ├── models/            # Data models
│   └── socket_routes/     # WebSocket handlers
├── db/                    # Database scripts
├── aws/                   # AWS deployment files
├── requirements.txt       # Python dependencies
├── environment.yaml       # Conda environment
├── docker-compose.yml     # Docker configuration
└── manage_peripherals.py  # Server management

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Stable Diffusion: AI image generation model

---

Note: This is a resource-intensive application requiring significant computational power for AI image generation. Consider cloud deployment for production use.