96 lines
5.1 KiB
Markdown
96 lines
5.1 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, 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
|
||
```
|