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

```bash
# 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**:
   ```bash
   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):
   ```bash
   python run_server.py
   ```

2. **Start pygame clients** (in separate terminals):
   ```bash
   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

```bash
# 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

```bash
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:

```bash
# 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

```bash
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

```bash
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