99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
Markdown
# 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
|
||
```
|