Initial commit: Multiplayer Snake game with server discovery
Implemented a complete network multiplayer Snake game with the following features: Core Game: - Client-server architecture using asyncio for networking - Pygame-based rendering at 60 FPS - Server-authoritative game state with 10 TPS - Collision detection (walls, self, other players) - Food spawning and score tracking - Support for multiple players with color-coded snakes Server Discovery: - UDP multicast-based automatic server discovery (239.255.0.1:9999) - Server beacon broadcasts presence every 2 seconds - Client discovery with 3-second timeout - Server selection UI for multiple servers - Auto-connect for single server - Graceful fallback to manual connection Project Structure: - src/shared/ - Protocol, models, constants, discovery utilities - src/server/ - Game server, game logic, server beacon - src/client/ - Game client, renderer, discovery, server selector - tests/ - Unit tests for game logic, models, and discovery Command-line interface with argparse for both server and client. Comprehensive documentation in README.md and CLAUDE.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Vladyslav Doloman
110
CLAUDE.md
Normal file
110
CLAUDE.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user