claudePySnake/README.md

Multiplayer Snake Game

A network multiplayer Snake game built with Python, asyncio, and pygame.

Features

• Real-time multiplayer gameplay with client-server architecture
• Web client - Play in your browser without installing anything!
• Desktop client - Native pygame client for local play
• Automatic server discovery using multicast (zero-configuration LAN play)
• Dual-protocol support - TCP for desktop, WebSocket for web
• Support for multiple players simultaneously
• Classic Snake gameplay with collision detection
• Color-coded snakes for each player
• Score tracking and win conditions

Setup

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

# Install dependencies
pip install -r requirements.txt

# For development
pip install -r requirements-dev.txt

Running the Game

Web Client (Easiest!)

1. Start the server:

   python run_server.py --name "My Game"
   

2. Open your browser and navigate to:

   http://localhost:8000
   

3. Enter your name and click Connect. The WebSocket URL is auto-detected!

4. Play! Multiple players can join from different browsers/devices.

Desktop Client (Pygame)

1. Start the server (if not already running):

   python run_server.py
   

2. Start pygame clients (in separate terminals):

   python run_client.py --name Alice
   # Auto-discovers the server on your network
   

Mixed Play

Web and desktop clients can play together! The server supports both protocols simultaneously:

• Desktop clients connect via TCP (port 8888)
• Web clients connect via WebSocket (port 8889)

Manual Connection

# Server with all options
python run_server.py --host 0.0.0.0 --port 8888 --ws-port 8889 --name "Game Room"

# Desktop client (direct connection)
python run_client.py 192.168.1.100 --port 8888 --name Bob

# Web client: enter ws://192.168.1.100:8889 in the browser

Server Options

python run_server.py --help

# Network
# --host HOST         Host address to bind to (default: localhost)
# --port PORT         TCP port for desktop clients (default: 8888)
# --ws-port PORT      WebSocket port for web clients (default: 8889, 0 to disable)
# --http-port PORT    HTTP server port (default: 8000, 0 to disable)
# --name NAME         Server name for discovery (default: Snake Server)

# Features
# --no-discovery      Disable multicast discovery beacon
# --no-websocket      Disable WebSocket server (desktop only)
# --no-http           Disable HTTP server (use external web server like nginx)
# --web-dir PATH      Path to web files (default: web)

Production Deployment

For production with nginx or Apache:

# Run server without built-in HTTP server
python run_server.py --no-http --host 0.0.0.0

# nginx serves static files from web/ directory
# and proxies WebSocket connections to port 8889

See web/README.md for detailed nginx/Apache configuration.

Client Options

python run_client.py --help
# [host]              Server host (omit to use auto-discovery)
# --port PORT         Server port (default: 8888)
# --name NAME         Your player name (default: Player)
# --discover          Force discovery mode

Playing the Game

• Press SPACE to start the game (any player can start)
• Use arrow keys or WASD to control your snake
• Eat food to grow and score points
• Avoid walls and other snakes

Testing

pytest
pytest --cov=src --cov-report=html  # With coverage

Project Structure

• src/server/ - Game server with authoritative game state
• src/client/ - Game client with pygame rendering
• src/shared/ - Shared code (models, protocol, constants)
• tests/ - Unit tests