claudePySnake/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **network multiplayer Snake game** built with Python 3.11, featuring both web and desktop clients with dual-protocol support (TCP + WebSocket).

**Project Structure:**
- `src/shared/` - Shared code (models, protocol, constants, discovery utilities)
- `src/server/` - Dual-protocol game server (TCP + WebSocket), HTTP server, multicast beacon
- `src/client/` - Pygame desktop client with discovery and server selection UI
- `web/` - Browser-based web client (HTML/CSS/JavaScript)
- `tests/` - Test files using pytest

## Setup Commands

```bash
# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt
```

## Running the Game

```bash
# Web Client (easiest - no installation needed)
python run_server.py --name "My Game"
# Open browser to http://localhost:8000

# Desktop Client (pygame)
python run_client.py --name Alice
# Auto-discovers server on local network

# Server Options:
# --host HOST          Bind address (default: localhost)
# --port PORT          TCP port for desktop clients (default: 8888)
# --ws-port PORT       WebSocket port for web clients (default: 8889, 0=disable)
# --http-port PORT     HTTP server port (default: 8000, 0=disable)
# --name NAME          Server name for discovery
# --no-discovery       Disable multicast beacon
# --no-websocket       Disable WebSocket server (desktop clients only)
# --no-http            Disable HTTP server (use nginx/Apache in production)
# --web-dir PATH       Web files directory (default: web)

# Production Deployment:
python run_server.py --no-http --host 0.0.0.0
# Use nginx to serve web/ directory and proxy WebSocket to port 8889
# See web/README.md for nginx configuration examples

# Press SPACE to start the game, arrow keys/WASD to move
```

## Development Commands

```bash
# Run all tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=html

# Format code with black
black src/ tests/

# Lint code
flake8 src/ tests/

# Type check
mypy src/
```

## Architecture

**Dual-Protocol Client-Server Model:**
- Server runs authoritative game loop using asyncio
- **Desktop clients** connect via TCP (port 8888) with newline-delimited JSON
- **Web clients** connect via WebSocket (port 8889) with JSON frames
- Server broadcasts game state updates to all clients at 10 FPS
- Desktop clients render at 60 FPS with pygame
- Web clients render at 60 FPS with HTML5 Canvas

**Key Backend Components:**
- `src/shared/protocol.py` - JSON-based message protocol (same for TCP and WebSocket)
- `src/shared/models.py` - Data models with serialization (Snake, Position, Food, GameState)
- `src/shared/constants.py` - Configuration (grid, colors, tick rate, ports)
- `src/shared/discovery.py` - Multicast discovery utilities
- `src/server/game_server.py` - Dual-protocol game server (TCP + WebSocket)
- `src/server/game_logic.py` - Game rules (movement, collision, food)
- `src/server/websocket_handler.py` - WebSocket connection handler
- `src/server/http_server.py` - Static file server for web client (aiohttp)
- `src/server/server_beacon.py` - UDP multicast beacon

**Desktop Client Components:**
- `src/client/game_client.py` - pygame client with TCP connection
- `src/client/renderer.py` - Pygame rendering
- `src/client/server_discovery.py` - Multicast discovery
- `src/client/server_selector.py` - Server selection UI

**Web Client Components:**
- `web/index.html` - Main HTML interface
- `web/style.css` - Responsive styling (dark theme)
- `web/protocol.js` - Protocol implementation (JavaScript)
- `web/game.js` - Game client with Canvas rendering and WebSocket connection

**Game Flow:**
1. Server starts TCP (8888), WebSocket (8889), HTTP (8000), and broadcasts on multicast (9999)
2. Desktop clients discover via multicast; web clients use auto-detected WebSocket URL
3. Clients connect and receive WELCOME with player_id
4. Any player presses SPACE to send START_GAME
5. Server creates snakes and spawns food
6. Server loop: update → check collisions → broadcast state (protocol-agnostic)
7. Game ends when ≤1 snake alive

**Protocol Handling:**
- Server stores clients as `(connection, ClientType.TCP|WEBSOCKET)`
- `send_to_client()` detects type and sends via appropriate method
- TCP: newline-delimited JSON (`message\n`)
- WebSocket: JSON frames (native WebSocket message)

**Production Deployment:**
- Run server with `--no-http` flag
- Use nginx/Apache to serve `web/` directory
- Proxy WebSocket connections to port 8889
- See `web/README.md` for configuration examples