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

# 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

# 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

# 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