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 custom avatar color, are placed randomly onto the board, and take turns moving around the arena.

---

## Features

### Turn-Based Movement & Rules
- **Turn Order**: Strict round-robin turn order based on registration sequence.
- **8 Movement Directions**:
  - **Cardinal**: `UP`, `DOWN`, `LEFT`, `RIGHT` (or `N`, `S`, `W`, `E`)
  - **Diagonal**: `UP_LEFT`, `UP_RIGHT`, `DOWN_LEFT`, `DOWN_RIGHT` (or `NW`, `NE`, `SW`, `SE`)
- **Obstacle & Boundary Enforcement**:
  - **Boundary Walls**: Cannot break past coordinate boundaries `[0..64, 0..64]`.
  - **Collision Prevention**: Cannot move into any square occupied by another player/bot.
  - **Turn Enforcement**: A bot can only move when it is their turn (`403 Forbidden` if attempted out of turn).
- **Pass Turn**: Players can skip/pass their turn if stuck or desired.

### REST Endpoints

#### Movement & Inspection Endpoints
- `GET /api/players/{player_id}/available-moves`
  - Checks all 8 movement directions for availability, target coordinates, and rejection reasons (wall collision or occupied by another bot). Also indicates if it is currently that bot's turn.
- `GET /api/players/{player_id}/check-move?direction={DIR}`
  - Fast check for a single direction (e.g. `UP`, `DOWN`, `NW`, etc.). Returns `available: true/false`, target coordinates, and reason if blocked.
- `POST /api/players/{player_id}/move`
  - Execute a movement. Accepts `{"direction": "UP_RIGHT"}` or `{"dx": 1, "dy": -1}`.
  - Validates boundaries, occupant collisions, and turn order.
  - Advances position and rotates turn to next player.
- `POST /api/players/{player_id}/pass`
  - Passes the turn to the next player.
- `GET /api/turn`
  - Returns current turn state (active player ID & name, round number, turn number, and player order).

#### Management Endpoints
- `POST /api/players` (or `/api/register`): Register a player with `name` and `color`.
- `GET /api/board`: Returns grid dimensions, player count, all player coordinates, and turn information.
- `GET /api/players`: Lists active players.
- `DELETE /api/players/{player_id}`: Remove a player from the arena.
- `POST /api/board/reset`: Reset the board and clear all players.
- `/ws`: Real-time WebSocket feed broadcasting movements, spawns, departures, and turn rotations.
- Interactive OpenAPI / Swagger documentation at `/docs`.

---

### Interactive Web UI (React + Vite + Tailwind CSS)
- **HTML5 Canvas 64×64 Grid**:
  - Click-and-drag pan, mouse-wheel zoom, coordinate axis rulers (0 to 64), and hover coordinate tracker.
  - Golden pulsing halo and crown `👑` highlighting the active turn player.
  - Visual movement overlays showing free cells (green) vs blocked cells (red) around the active bot.
- **8-Directional On-Screen D-Pad**:
  - Compass layout (NW, N, NE, W, PASS, E, SW, S, SE) with real-time green/red availability styling and tooltips.
  - Full keyboard control: **WASD**, **Arrow keys**, or **Numpad (1-9)**, plus **Spacebar** to pass.
- **Simulation & Testing Tools**:
  - **⚡ Step Bot**: Executes 1 valid random move for the active bot.
  - **▶ Auto-Play**: Automatically runs bot turns in real time so you can watch them navigate the arena.
  - **🎲 Quick Spawn Bot**: 1-click bot generator with fun cyber names and neon colors.

---

## Quick Start with Docker

### Option 1: Docker Compose (Recommended)

```bash
docker compose up --build
```

Open [http://localhost:8000](http://localhost:8000) in your browser.

### Option 2: Docker CLI

```bash
# Build the Docker image
docker build -t botwebwars .

# Run the container
docker run -d -p 8000:8000 --name botwebwars botwebwars
```

- Webapp & Arena: [http://localhost:8000](http://localhost:8000)
- Swagger API Docs: [http://localhost:8000/docs](http://localhost:8000/docs)

---

## API Examples

### 1. Register a Bot
```bash
curl -X POST http://localhost:8000/api/players \
  -H "Content-Type: application/json" \
  -d '{"name": "CyberViper", "color": "#38BDF8"}'
```

### 2. Check If a Direction is Available
```bash
curl "http://localhost:8000/api/players/{player_id}/check-move?direction=UP_RIGHT"
```
Response:
```json
{
  "direction": "UP_RIGHT",
  "dx": 1,
  "dy": -1,
  "target_x": 36,
  "target_y": 11,
  "available": true,
  "reason": null
}
```

### 3. Query All 8 Available Directions
```bash
curl "http://localhost:8000/api/players/{player_id}/available-moves"
```

### 4. Move Bot (During Their Turn)
```bash
curl -X POST "http://localhost:8000/api/players/{player_id}/move" \
  -H "Content-Type: application/json" \
  -d '{"direction": "UP_RIGHT"}'
```

### 5. Pass Turn
```bash
curl -X POST "http://localhost:8000/api/players/{player_id}/pass"
```

---

## Running Backend Tests

```bash
docker run --rm botwebwars pytest backend/tests
```