botWebWars/README.md

# botWebWars

A FastAPI and React-based web arena featuring a real-time **64 × 64 grid** with coordinates ranging from `(0, 0)` to `(64, 64)`. Players/bots register with their name, color, and strength, remember everywhere they have been, navigate autonomously towards their goals, negotiate **Parties** based on relative strength, take turns moving around the arena, and engage in **3-bout D20 tactical battles**.

---

## Autonomous Goals & Behaviors

### 1. Goal of a Bot Without a Party: Form a Party
- **Primary Objective**: Seek other bots across the arena and form a party as soon as contact is made.
- **Seeking & Memory**:
  - Uses location memory history to prevent circular looping and prioritize unexplored coordinates.
  - Radar targets the closest candidate bot.
- **Leadership Negotiation Rule**:
  - **Insistence on Leadership**: If a bot considers the other bot less than them (**higher strength**), it **insists on being the party leader**.
  - **Desire to Join**: A bot desires to join a bot that is **equal or stronger**.
  - **Agreed Outcome**:
    - When two unpartied bots meet, the bot with the **higher strength** becomes the agreed **Party Leader**.
    - If strengths are equal, tie-breaking chooses the bot with higher score or the initiator, and both agree since each is equal in strength.
    - If an unpartied bot meets an existing party: if the solo bot is stronger than the party's total strength, it insists on becoming the new leader; otherwise, it joins under the existing leader.

### 2. Goal of a Party: Find and Defeat All Other Parties
- **Primary Objective**: Seek out and eliminate all opposing parties on the board.
- **Squad Navigation**:
  - The Party Leader controls group movement, steering the linked squad across the grid towards opposing squads.
  - All party members maintain linked connectivity ($\le 1$ Chebyshev distance).
- **Battle Engagement**:
  - As soon as a party becomes adjacent to an opposing party, combat is engaged.

---

## 3-Bout D20 Battle Mechanics & Scoring

### 1. Engagement & 3-Bout Resolution
- Each battle consists of **3 bouts**.
- In each bout, both parties roll a **20-sided die (D20)** (1 to 20).
- Multiplier rule:
  $$\text{Bout Score} = \text{Party Strength} \times \text{D20 Roll}$$
- Winner is determined by whoever wins more bouts (or has a higher aggregate score in case of ties).

### 2. Score Distribution
- **Winning Party Leader**: Receives **+2 points**.
- **Rest of Winning Party**: Each member receives **+1 point**.
- **Losing Party Leader**: Receives **-1 point**, loses leadership, is removed from the party, and respawns at a random free position.
- **Rest of Losing Party**: Loses **0 points** (scores remain unchanged).

### 3. Surrender & Absorption
- The **surviving remainder of the defeated party joins the winning party**.
- The winning squad grows in numbers and total strength, and immediately resumes hunting down any remaining parties!

---

## REST API Endpoints

### AI & Autonomous Endpoints
- `POST /api/players/{player_id}/ai-step`: Executes one autonomous turn according to the bot's goal:
  - If unpartied: seeks other bots; negotiates and forms a party under the stronger leader upon contact.
  - If partied leader: hunts down opposing parties; engages and resolves 3-bout D20 battles.
- `GET /api/players/{player_id}/radar`: Scans surroundings for nearby bots, calculates distance, determines allies/enemies, and identifies recruit/battle opportunities.
- `GET /api/players/{player_id}/memory`: Retrieves coordinate history and tracks visited locations.

### Movement & Turn Endpoints
- `GET /api/players/{player_id}/available-moves`: Checks availability of all 8 directions (for a solo bot or the whole party if leader).
- `GET /api/players/{player_id}/check-move?direction={DIR}`: Check single direction.
- `POST /api/players/{player_id}/move`: Move bot or entire party if leader. Automatically checks for party formation or battle engagement upon move completion.
- `POST /api/players/{player_id}/pass`: Pass turn to next player.
- `GET /api/turn`: Get current turn status, round number, and turn queue.

### Party & Battle Endpoints
- `POST /api/parties`: Directly form a party with linked members and an agreed leader.
- `GET /api/parties`: List all active parties, leaders, members, and total strength.
- `POST /api/parties/{party_id}/defeat`: Trigger party defeat.
- `POST /api/battles/fight`: Initiate a 3-bout D20 battle between two adjacent parties/bots.

### Player & Board Endpoints
- `POST /api/players`: Register a new player with `name`, `color`, and optional `strength` (default 1).
- `GET /api/players`: List active players and their scores.
- `GET /api/board`: Full board state, player positions, parties, and turn data.
- `POST /api/board/reset`: Clear board, players, and parties.
- `/ws`: Real-time WebSocket broadcasting movements, party formations, battles, and turn changes.

---

## Quick Start with Docker

```bash
# Build and run with Docker Compose
docker compose up --build
```
Open [http://localhost:8000](http://localhost:8000) in your browser.

### Running Backend Test Suite
```bash
docker run --rm botwebwars:test pytest backend/tests
```