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

# 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

# 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

# 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