A high-performance, competitive Snake AI bot designed for CopperHead Bot Hack Tournaments.
- Multi-Layer Strategy Engine: Safety-first survival, A* pathfinding, area control, and adaptive aggression
- Tournament-Ready: Handles multiple consecutive games with clean state resets
- Protocol Compliant: Full WebSocket protocol compliance with proper message handling
- Dynamic Awareness: Reads grid dimensions from server, tracks all game objects
- Persistent Learning: Adapts weights across matches via per-opponent and cohort profiles
- Auto-Redeploy: Re-enters the tournament automatically after round losses
- Python 3.10+
- A running CopperHead server
# Clone this repository
git clone https://github.com/YOUR_USERNAME/copperhead-bot.git
cd copperhead-bot
# Install dependencies
pip install -r requirements.txtCopy the environment template and configure:
cp .env.example .envEdit .env with your server URL:
COPPERHEAD_SERVER_URL=ws://localhost:8765/ws/
BOT_NAME=CopperheadChampion
# Using environment variables (recommended)
python bot.py
# Or with command-line arguments
python bot.py --server ws://localhost:8765/ws/ --name "MyBot"
# Against a specific difficulty opponent
python bot.py --server ws://localhost:8765/ws/ --difficulty 5copperhead-bot/
├── bot.py # Main entry point, WebSocket connection, game loop
├── strategy.py # Multi-layer decision engine
├── pathfinding.py # A*, BFS, flood-fill algorithms
├── utils.py # Grid helpers, coordinate utilities
├── requirements.txt
├── .env.example
└── README.md
- Never collide with walls, self, or opponent (unless intentional)
- Maintain fallback safe moves at all times
- Validate all moves before execution
- A* pathfinding to food with safety constraints
- BFS for distance calculations
- Penalty for paths that reduce future mobility
- Flood-fill to count accessible cells
- Prefer moves that maximize reachable space
- Avoid corridors and dead-ends
- When Ahead: Play defensively, deny space to opponent
- When Behind: Apply pressure, cut off escape routes, force risky opponent moves
- Clean state reset between games
- No persistent assumptions across rounds
- Robust reconnection handling
| Variable | Description | Default |
|---|---|---|
COPPERHEAD_SERVER_URL |
WebSocket URL of the CopperHead server | ws://localhost:8765/ws/ |
BOT_NAME |
Display name for the bot | CopperheadChampion |
BOT_DIFFICULTY |
Internal difficulty setting (1-10) | 10 |
BOT_QUIET |
Suppress console output | false |
BOT_REDEPLOY_AFTER_ROUND_LOSS |
Auto-redeploy after losing a round | true |
BOT_REDEPLOY_LADDER_ONLY |
Only redeploy against ladder (CopperBot) opponents | true |
| Argument | Short | Description |
|---|---|---|
--server |
-s |
Server WebSocket URL |
--name |
-n |
Bot display name |
--difficulty |
-d |
Difficulty level (1-10) |
--quiet |
-q |
Suppress console output |
| Type | Description |
|---|---|
joined |
Player assigned to arena with player_id and room_id |
waiting |
Waiting for opponent to join |
start |
Game beginning with mode and room_id |
state |
Game tick with full game state object |
gameover |
Round ended with winner, wins, points_to_win |
match_complete |
Match finished with winner and final_score |
match_assigned |
New tournament round with room_id, player_id, opponent |
competition_complete |
Tournament ended with champion |
error |
Server error with message description |
{"action": "ready", "mode": "two_player", "name": "BotName"}
{"action": "move", "direction": "up|down|left|right"}The strategy engine uses weighted scoring for move selection:
- Safety: Immediate collision avoidance (critical)
- Food Distance: Weighted by snake length comparison
- Reachable Space: Flood-fill cell count
- Opponent Pressure: Distance to opponent head
- Corridor Avoidance: Penalize moves with few neighbors
See CONTRIBUTING.md for guidelines on how to contribute.
Key areas for enhancement:
- Enhanced opponent prediction algorithms
- Multi-food path planning
- Buff-aware strategies
- Machine learning integration
See SECURITY.md for security policy and vulnerability reporting.
This project is licensed under the MIT License - see LICENSE for details.
- CopperHead Server - The game server
- Building Your Own Bot - Official bot guide
- Game Rules - Complete game rules
- Tournament Guide - Tournament hosting
Built for the CopperHead Bot Hack Tournament