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 register with their name and custom avatar color and are randomly placed onto the grid.

---

## Features

- **FastAPI Backend**:
  - `POST /api/players` (or `/api/register`): Register a player with `name` and `color`. The game places them at a random unoccupied `(x, y)` coordinate between `(0, 0)` and `(64, 64)`.
  - `GET /api/board`: Returns grid dimensions, player count, and player list.
  - `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 pushing live player spawns, departures, and board resets to all connected clients.
  - Interactive OpenAPI/Swagger documentation at `/docs`.

- **React + Vite + Tailwind CSS Frontend**:
  - High-performance HTML5 Canvas rendering for the 64×64 arena with pan (click & drag), zoom (mouse wheel or zoom buttons), and grid coordinate rulers.
  - Hover cursor coordinate tracker showing exact `(x, y)` coordinates.
  - Glowing bot avatars rendered in the player's chosen color with nameplates and pulsing selection rings.
  - Live registration modal with interactive color picker, cyberpunk color presets, and real-time avatar preview.
  - Sidebar showing all active bots and coordinates; click any bot to focus the camera on them.
  - 1-click **Quick Spawn Bot** button for rapid testing.
  - Real-time synchronization via WebSockets with auto-reconnection.

- **Dockerized Single-Container Deployment**:
  - Multi-stage `Dockerfile` compiles the frontend with Node 22 and packages it into a lightweight Python 3.12 image.
  - FastAPI serves both the API/WebSocket endpoints and the compiled SPA frontend.

---

## 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 Usage Examples

### Register a Player
```bash
curl -X POST http://localhost:8000/api/players \
  -H "Content-Type: application/json" \
  -d '{"name": "CyberViper", "color": "#38BDF8"}'
```
Response:
```json
{
  "id": "bot_a1b2c3d4",
  "name": "CyberViper",
  "color": "#38BDF8",
  "x": 42,
  "y": 18,
  "created_at": "2026-09-05T21:00:00.000000Z"
}
```

### Inspect Board State
```bash
curl http://localhost:8000/api/board
```

### Clear / Reset Board
```bash
curl -X POST http://localhost:8000/api/board/reset
```

---

## Local Development (Without Docker)

### Backend
```bash
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

### Frontend
```bash
cd frontend
npm install
npm run dev
```
The Vite development server runs at [http://localhost:5173](http://localhost:5173) and proxies `/api` and `/ws` to FastAPI on port 8000.

### Running Backend Tests
```bash
pytest backend/tests
```