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 and avatar color, find teammates, form **Parties**, take turns moving around the arena, and engage in tactical squad battles.

---

## Features

### 1. Parties & Squad Formations
- **Goal & Linked Connectivity**:
  - Bots can find each other and join together as a **Party**.
  - All party members must be within **1 distance** of each other (Chebyshev distance $\le 1$, including diagonals and cardinals), forming linked connections (clusters or single-file lines).
  - Bots must agree on a **Party Leader**.
- **Leader Group Movement**:
  - The Party Leader controls the movement for the entire squad.
  - All party members translate together in the chosen direction (preserving their relative shape and linked adjacency).
  - If any party member's path is blocked by an outside bot or boundary wall, the entire group move is prevented.
  - Non-leader party members cannot move independently.

### 2. Battle, Defeat & Respawn Mechanics
- **Scoring**:
  - All players/bots start with a score of **0**.
- **Leader Defeat**:
  - If a party is defeated in battle (or triggered via `/api/parties/{id}/defeat`), the **Party Leader is killed**:
    1. Leader's score decreases by 1 (`score -= 1`).
    2. Leader is removed from their prior party (`party_id = null`, `is_party_leader = false`).
    3. Leader respawns at a random unoccupied position on the board.
    4. A **new leader is randomly assigned** from the remainder of the party.
    5. If no members remain, the party dissolves.

### 3. Turn-Based 8-Directional Movement
- **8 Directions**:
  - Cardinal: `UP`, `DOWN`, `LEFT`, `RIGHT`
  - Diagonal: `UP_LEFT`, `UP_RIGHT`, `DOWN_LEFT`, `DOWN_RIGHT`
- **Collision & Wall Avoidance**:
  - Cannot break through boundary walls `[0..64, 0..64]`.
  - Cannot move into cells occupied by outside bots.

---

## REST API Endpoints

### Party & Battle Endpoints
- `POST /api/parties`: Form a party directly.
  - Body: `{"member_ids": ["bot_1", "bot_2"], "leader_id": "bot_1", "name": "Squadrons"}`
  - Validates that members are within 1 distance of each other and agree on the leader.
- `POST /api/parties/invite`: Propose a party invite to an adjacent bot with an agreed leader.
- `POST /api/parties/invites/{invite_id}/respond`: Accept or reject party invite (`{"accept": true}`).
- `GET /api/parties`: List all active parties, leaders, and members.
- `GET /api/parties/{party_id}`: Get party details.
- `POST /api/parties/{party_id}/defeat`: Trigger party defeat.
  - Leader is killed, loses 1 point, leaves party, and respawns randomly.
  - Remainder of party elects a new random leader.
- `POST /api/battles/fight`: Initiate a battle between adjacent bots/parties.
  - Body: `{"challenger_id": "bot_1", "defender_id": "bot_2"}`

### 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 (`{"direction": "UP_RIGHT"}`).
- `POST /api/players/{player_id}/pass`: Pass turn to next player.
- `GET /api/turn`: Get current turn status, round number, and turn queue.

### Player & Board Endpoints
- `POST /api/players`: Register a new player with `name` and `color`.
- `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 connection broadcasting player joins, squad movements, party formations, defeats, and turn changes.

---

## Interactive Web UI (React 19 + Vite + Tailwind CSS)

- **Canvas Arena**:
  - Laser energy beams connecting adjacent party members.
  - Crown `👑` on the Party Leader and golden pulsing aura for active turn.
  - Hover coordinate tracker, zoom & pan controls.
- **Controls & Modals**:
  - **8-Directional D-Pad** with real-time green/red cell availability and keyboard bindings (WASD / Arrows / Numpad).
  - **Form / Join Party Modal** with auto-detection of nearest adjacent bots and agreed leader selector.
  - **💥 Defeat Button** on parties in the roster to test the leader death, respawn, and leadership succession flow.
  - **⚡ Step Bot** & **▶ Auto-Play** simulation mode.

---

## 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
```