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

# Example Invokation

Troll GEAR
```
$ cd trollagent_gear
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ BOT_SERVER_URL="https://botwebwars.tpk.pw" python bot.py --name "GeminiGear-38f" --color "#4285f4" -s 2 -H 2 --model gemini-3.8-flash
```

Troll AI
```
$ cd trollagent_ai/
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ BOT_SERVER_URL="http://localhost:8000" python bot.py --name "Troll Gemini4 e4b" --color "#4285f4" -s 2 -H 2 --ollama-url "http://192.168.1.220:11434" --ollama-model "gemma4:e4b"
```

Troll Bot
```
$ cd trollagent
$ python3 -m venv venv
$ source  venv/bin/activate
$ pip install -r requirements.txt
$ python troll_agent.py --url "http://localhost:8000" --name "Fat Troll" --color "#10B981" -s 2 -H 2
```

BotAgents work the same way