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

---

## Multi-Agent Batch Launchers (Top-Level Scripts)

Instead of opening multiple terminal tabs manually, you can launch pools of AI bots or trolls using the top-level launcher scripts. The scripts automatically name agents as `{folder}_{sanitized_model}_{number}` (e.g. `botagent_ai_gemma4_e4b_1`, `botagent_ai_gemma4_e4b_2`, etc.), auto-assign distinct colors, multiplex real-time colorized logs in one terminal, save individual log files under `logs/`, and gracefully clean up all sessions when interrupted (`Ctrl+C`).

### Launch Multiple AI Bots (`botagent_ai`)
```bash
# Launch 3 AI bots with default parameters (gemma4:e4b, str 2, hp 2)
./launch_bots.sh -n 3

# Or with python directly, specifying custom parameters:
python3 launch_bots.py -n 4 -s 2 -H 2 --ollama-url "http://192.168.1.220:11434" --model "gemma4:e4b"

# Preview commands without executing
./launch_bots.py -n 3 --dry-run
```

### Launch Multiple AI Trolls (`trollagent_ai`)
```bash
# Launch 2 AI trolls with default parameters (gemma4:e4b, str 2, hp 2)
./launch_trolls.sh -n 2

# Or with python directly, specifying custom parameters:
python3 launch_trolls.py -n 2 -s 3 -H 4 --ollama-url "http://192.168.1.220:11434" --model "gemma4:e4b"

# Preview commands without executing
./launch_trolls.py -n 2 --dry-run
```

### CLI Options Supported:
- `-n`, `--count`, `--num`: Number of agents to launch (default: `1`).
- `-s`, `--strength`: Strength multiplier (default: `2`).
- `-H`, `--health`: Starting health points (default: `2`).
- `--ollama-url`: Ollama API base URL (default: `http://192.168.1.220:11434`).
- `-m`, `--model`, `--ollama-model`: Ollama model name (default: `gemma4:e4b`).
- `-u`, `--url`, `--server-url`: botWebWars backend URL (default: `http://localhost:8000`).
- `-c`, `--color`: Custom avatar hex color (default: auto-cycles vibrant palette).
- `--start-index`: Starting number index (e.g. `--start-index 4` for instances `_4`, `_5`, ...).
- `--dry-run`: Display all commands without launching.
- `--log-dir`: Directory for per-agent log files (default: `logs/`).
- `--no-logs`: Disable writing log files to disk.