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 avatar color, find teammates, form Parties, take turns moving around the arena, and engage in tactical squad battles.

---

Features

1. Parties & Squad Formations

• Goal & Linked Connectivity:
  • Bots can find each other and join together as a Party.
  • All party members must be within 1 distance of each other (Chebyshev distance \le 1, including diagonals and cardinals), forming linked connections (clusters or single-file lines).
  • Bots must agree on a Party Leader.
• Leader Group Movement:
  • The Party Leader controls the movement for the entire squad.
  • All party members translate together in the chosen direction (preserving their relative shape and linked adjacency).
  • If any party member's path is blocked by an outside bot or boundary wall, the entire group move is prevented.
  • Non-leader party members cannot move independently.

2. Battle, Defeat & Respawn Mechanics

• Scoring:
  • All players/bots start with a score of 0.
• Leader Defeat:
  • If a party is defeated in battle (or triggered via /api/parties/{id}/defeat), the Party Leader is killed:
    1. Leader's score decreases by 1 (score -= 1).
    2. Leader is removed from their prior party (party_id = null, is_party_leader = false).
    3. Leader respawns at a random unoccupied position on the board.
    4. A new leader is randomly assigned from the remainder of the party.
    5. If no members remain, the party dissolves.

3. Turn-Based 8-Directional Movement

• 8 Directions:
  • Cardinal: UP, DOWN, LEFT, RIGHT
  • Diagonal: UP_LEFT, UP_RIGHT, DOWN_LEFT, DOWN_RIGHT
• Collision & Wall Avoidance:
  • Cannot break through boundary walls [0..64, 0..64].
  • Cannot move into cells occupied by outside bots.

---

REST API Endpoints

Party & Battle Endpoints

• POST /api/parties: Form a party directly.
  • Body: {"member_ids": ["bot_1", "bot_2"], "leader_id": "bot_1", "name": "Squadrons"}
  • Validates that members are within 1 distance of each other and agree on the leader.
• POST /api/parties/invite: Propose a party invite to an adjacent bot with an agreed leader.
• POST /api/parties/invites/{invite_id}/respond: Accept or reject party invite ({"accept": true}).
• GET /api/parties: List all active parties, leaders, and members.
• GET /api/parties/{party_id}: Get party details.
• POST /api/parties/{party_id}/defeat: Trigger party defeat.
  • Leader is killed, loses 1 point, leaves party, and respawns randomly.
  • Remainder of party elects a new random leader.
• POST /api/battles/fight: Initiate a battle between adjacent bots/parties.
  • Body: {"challenger_id": "bot_1", "defender_id": "bot_2"}

Movement & Turn Endpoints

• GET /api/players/{player_id}/available-moves: Checks availability of all 8 directions (for a solo bot or the whole party if leader).
• GET /api/players/{player_id}/check-move?direction={DIR}: Check single direction.
• POST /api/players/{player_id}/move: Move bot or entire party if leader ({"direction": "UP_RIGHT"}).
• POST /api/players/{player_id}/pass: Pass turn to next player.
• GET /api/turn: Get current turn status, round number, and turn queue.

Player & Board Endpoints

• POST /api/players: Register a new player with name and color.
• GET /api/players: List active players and their scores.
• GET /api/board: Full board state, player positions, parties, and turn data.
• POST /api/board/reset: Clear board, players, and parties.
• /ws: Real-time WebSocket connection broadcasting player joins, squad movements, party formations, defeats, and turn changes.

---

Interactive Web UI (React 19 + Vite + Tailwind CSS)

• Canvas Arena:
  • Laser energy beams connecting adjacent party members.
  • Crown 👑 on the Party Leader and golden pulsing aura for active turn.
  • Hover coordinate tracker, zoom & pan controls.
• Controls & Modals:
  • 8-Directional D-Pad with real-time green/red cell availability and keyboard bindings (WASD / Arrows / Numpad).
  • Form / Join Party Modal with auto-detection of nearest adjacent bots and agreed leader selector.
  • 💥 Defeat Button on parties in the roster to test the leader death, respawn, and leadership succession flow.
  • ⚡ Step Bot & ▶ Auto-Play simulation mode.

---

Quick Start with Docker

# Build and run with Docker Compose
docker compose up --build

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

Running Backend Test Suite

docker run --rm botwebwars:test pytest backend/tests