113 lines
3.3 KiB
Markdown
113 lines
3.3 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 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
|
||
```
|