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)

docker compose up --build

Open http://localhost:8000 in your browser.

Option 2: Docker CLI

# 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
• Swagger API Docs: http://localhost:8000/docs

---

API Examples

1. Register a Bot

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

curl "http://localhost:8000/api/players/{player_id}/check-move?direction=UP_RIGHT"

Response:

{
  "direction": "UP_RIGHT",
  "dx": 1,
  "dy": -1,
  "target_x": 36,
  "target_y": 11,
  "available": true,
  "reason": null
}

3. Query All 8 Available Directions

curl "http://localhost:8000/api/players/{player_id}/available-moves"

4. Move Bot (During Their Turn)

curl -X POST "http://localhost:8000/api/players/{player_id}/move" \
  -H "Content-Type: application/json" \
  -d '{"direction": "UP_RIGHT"}'

5. Pass Turn

curl -X POST "http://localhost:8000/api/players/{player_id}/pass"

---

Running Backend Tests

docker run --rm botwebwars pytest backend/tests