137 lines
4.8 KiB
Markdown
137 lines
4.8 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/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
|
||
```
|