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, using asyncio for networking, pygame for graphics, and UDP multicast for automatic server discovery.

**Project Structure:**
- `src/shared/` - Shared code (models, protocol, constants, discovery utilities)
- `src/server/` - Game server with authoritative game state and multicast beacon
- `src/client/` - Game client with pygame rendering, discovery, and server selection UI
- `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
# Start the server (with discovery beacon enabled by default)
python run_server.py --name "My Game" --port 8888

# Start clients with auto-discovery (no host needed)
python run_client.py --name Alice
# If multiple servers found, a selection UI appears

# Manual connection (skip discovery)
python run_client.py 192.168.1.100 --port 8888 --name Bob

# Server options:
# --host HOST         Bind address (default: localhost)
# --port PORT         Port number (default: 8888)
# --name NAME         Server name for discovery
# --no-discovery      Disable multicast beacon

# Client options:
# [host]              Server host (omit for auto-discovery)
# --port PORT         Server port
# --name NAME         Player name
# --discover          Force discovery mode

# 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

**Client-Server Model:**
- Server (`src/server/game_server.py`) runs the authoritative game loop using asyncio
- Clients connect via TCP and send input commands (MOVE, START_GAME, etc.)
- Server broadcasts game state updates to all connected clients at 10 FPS
- Clients render the game state locally at 60 FPS using pygame

**Key Components:**
- `src/shared/protocol.py` - JSON-based message protocol (MessageType enum, Message class)
- `src/shared/models.py` - Data models (Snake, Position, Food, GameState) with serialization
- `src/shared/constants.py` - Game configuration (grid size, colors, tick rate, multicast settings)
- `src/shared/discovery.py` - Multicast discovery utilities (ServerInfo, DiscoveryMessage)
- `src/server/game_logic.py` - Game rules (movement, collision detection, food spawning)
- `src/server/server_beacon.py` - UDP multicast beacon for server discovery
- `src/client/renderer.py` - Pygame rendering of game state
- `src/client/server_discovery.py` - Client-side server discovery
- `src/client/server_selector.py` - Pygame UI for selecting from multiple servers

**Game Flow:**
1. Server starts on port 8888 and broadcasts presence on multicast group 239.255.0.1:9999
2. Clients send DISCOVER message to multicast group and collect SERVER_ANNOUNCE responses
3. If multiple servers found, client shows selection UI; if one found, auto-connects
4. Clients connect via TCP and receive WELCOME message with player_id
5. Any player can press SPACE to send START_GAME message
6. Server creates snakes for all connected players and spawns food
7. Server runs game loop: update positions → check collisions → broadcast state
8. Game ends when only 0-1 snakes remain alive

**Discovery Protocol:**
- Multicast group: 239.255.0.1:9999 (local network)
- Client → Multicast: DISCOVER (broadcast request)
- Server → Client: SERVER_ANNOUNCE (direct response with host, port, name, player count)
- Server also periodically broadcasts presence every 2 seconds