CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7This is a competitive AI bot development project for the Game of Amazons, designed to run on the Botzone platform. The project focuses on creating high-performance bots using Monte Carlo Tree Search (MCTS) with various optimization techniques.
8 
9**Key Technologies**: Python 3.6+, C++11, NumPy
10**Platform**: Botzone (Ubuntu 16.04 x86-64)
11**Game**: Amazons (8×8 board, 4 amazons per player, queen movement + arrow shooting)
12 
13## Development Commands
14 
15### Bot Compilation
16C++ bots are compiled manually with:
17```bash
18g++ -O3 -std=c++11 -o bots/botXXX bots/botXXX.cpp
19```
20 
21The tournament system provides a helper function:
22```bash
23python -c "from scripts.tournament.utils import compile_bot; compile_bot('bot003')"
24```
25 
26### Testing Commands
27**Quick functionality test** (first move as BLACK):
28```bash
29echo "1
30-1 -1 -1 -1 -1 -1" | python bots/bot001.py
31# or for C++ bots:
32echo "1
33-1 -1 -1 -1 -1 -1" | ./bots/bot001_cpp
34```
35 
36**Run simple bot tests**:
37```bash
38python scripts/test_bot_simple.py
39```
40 
41**Run Botzone protocol simulation**:
42```bash
43python scripts/botzone_simulator.py
44```
45 
46### Tournament System
47The tournament framework (`scripts/tournament/`) provides comprehensive testing:
48 
49**Single match**:
50```bash
51python -c "from scripts.tournament.cli import run_match; run_match('bot001', 'bot003')"
52```
53 
54**Competition automation** (10-game series):
55```bash
56python scripts/run_competitions.py
57```
58 
59**Check legal moves** (debugging tool):
60```bash
61python scripts/check_legal_moves.py
62```
63 
64**Debug board visualization**:
65```bash
66python scripts/debug_board.py
67```
68 
69## Architecture Overview
70 
71### Directory Structure
72- `core/` - Shared game logic (board representation, move generation)
73- `bots/` - Bot implementations (Python and C++ versions)
74- `scripts/` - Testing and utility scripts
75- `docs/` - Comprehensive documentation
76- `memorybank/` - Project context and technical decisions (Cline system)
77- `results/` - Tournament results (JSON format)
78- `logs/` - Match logs and output
79 
80### Bot Architecture
81The primary algorithm is **Multi-Component MCTS** with these key features:
82 
831. **Multi-Component Evaluation**: Five strategic factors combined:
84   - Queen Territory (BFS-based territory control)
85   - King Territory (weighted close-range control)
86   - Queen Position (exponential decay scoring)
87   - King Position (distance-weighted positioning)
88   - Mobility (available moves count)
89 
902. **Phase-Aware Weighting**: Different strategies for early/mid/late game phases
91 
923. **Dynamic UCB Constant**: Exploration decreases as game progresses
93 
944. **Long-Running Mode**: Maintains MCTS tree state between turns for efficiency
95 
96### Bot Implementations
97- `bot001.py` / `bot001.cpp` - Primary MCTS implementation (Python and C++ versions)
98- `bot002.cpp` - Optimized version with bitboard representation (has TLE issues)
99- `bot003.cpp` - Baseline MCTS bot for comparison
100- `bot004-bot008.cpp` - Optimization bots with different techniques
101- `opponent.cpp` - Latest implementation with AVX2 SIMD optimizations
102 
103## Platform Constraints (Botzone)
104 
105### Time Limits
106- **Python long-running bots**: 12s (first turn), 4s (subsequent turns)
107- **C++ long-running bots**: 2s (first turn), 1s (subsequent turns)
108 
109### Resource Limits
110- Memory: 256 MB default
111- CPU: Single core (no multi-threading benefit)
112 
113### I/O Protocol
114- Simplified interaction: Line-based stdin/stdout
115- Long-running mode: Must flush stdout after each turn
116- Move format: 6 integers `x0 y0 x1 y1 x2 y2`
117 
118## Development Workflow
119 
120### Cline Memory Bank System
121The project uses a Cline memory bank (`memorybank/`) for context:
122- `projectbrief.md` - Project overview and objectives
123- `systemPatterns.md` - Architecture and design decisions
124- `techContext.md` - Technologies and constraints
125- `activeContext.md` - Current state and next steps
126- `progress.md` - Development progress and milestones
127 
128### Development Rules (`.clinerules/`)
129- `development_workflow.md` - Development processes
130- `task_completion.md` - Mandatory sequential workflow for task completion
131- `memory_bank_update.md` - How to update memory bank files
132- `readme_update.md` - README update procedures
133 
134### Key Development Patterns
1351. **Always test sequentially** - Run tests in order: simple test → protocol simulation → tournament
1362. **Update memory bank first** - Review and update memory bank files before making changes
1373. **Check Botzone compatibility** - Ensure bots work within platform constraints
1384. **Use tournament framework** - For comprehensive testing and performance comparison
139 
140## Common Tasks
141 
142### Creating a New Bot
1431. Copy an existing bot (e.g., `bot003.cpp`) as a starting point
1442. Implement optimization technique
1453. Compile: `g++ -O3 -std=c++11 -o bots/botXXX bots/botXXX.cpp`
1464. Test with simple test script
1475. Run competition against baseline (`bot003`)
1486. Analyze results in `results/competitions/`
149 
150### Debugging TLE (Time Limit Exceeded) Issues
1511. Check time limits in bot code (conservative buffers required)
1522. Use tournament system to measure actual execution times
1533. Profile with `scripts/check_legal_moves.py` for move generation issues
1544. Review Botzone logs for specific timing patterns
155 
156### Testing Botzone Compatibility
1571. Use `botzone_simulator.py` to simulate platform I/O
1582. Verify long-running mode works correctly
1593. Check memory usage stays under 256 MB
1604. Ensure move format matches Botzone expectations
161 
162## Important Notes
163 
164- **No automated build system** - Bots are compiled manually
165- **NumPy dependency** - Required for Python bots, not for C++ bots
166- **Tree reuse** - MCTS trees are preserved between turns in long-running mode
167- **Bitboard representation** - Used in optimized bots for faster operations
168- **AVX2 optimizations** - Latest addition in `opponent.cpp` for SIMD parallelism
169 
170## Getting Started
1711. Read `README.md` for comprehensive project overview
1722. Check `memorybank/` for current project context
1733. Use tournament framework for testing: `scripts/tournament/`
1744. Follow Cline workflows in `.clinerules/` for development tasks