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, color, and strength, remember everywhere they have been, navigate autonomously towards their goals, negotiate Parties based on relative strength, take turns moving around the arena, and engage in 3-bout D20 tactical battles.

---

Autonomous Goals & Behaviors

1. Goal of a Bot Without a Party: Form a Party

• Primary Objective: Seek other bots across the arena and form a party as soon as contact is made.
• Seeking & Memory:
  • Uses location memory history to prevent circular looping and prioritize unexplored coordinates.
  • Radar targets the closest candidate bot.
• Leadership Negotiation Rule:
  • Insistence on Leadership: If a bot considers the other bot less than them (higher strength), it insists on being the party leader.
  • Desire to Join: A bot desires to join a bot that is equal or stronger.
  • Agreed Outcome:
    • When two unpartied bots meet, the bot with the higher strength becomes the agreed Party Leader.
    • If strengths are equal, tie-breaking chooses the bot with higher score or the initiator, and both agree since each is equal in strength.
    • If an unpartied bot meets an existing party: if the solo bot is stronger than the party's total strength, it insists on becoming the new leader; otherwise, it joins under the existing leader.

2. Goal of a Party: Find and Defeat All Other Parties

• Primary Objective: Seek out and eliminate all opposing parties on the board.
• Squad Navigation:
  • The Party Leader controls group movement, steering the linked squad across the grid towards opposing squads.
  • All party members maintain linked connectivity (\le 1 Chebyshev distance).
• Battle Engagement:
  • As soon as a party becomes adjacent to an opposing party, combat is engaged.

---

3-Bout D20 Battle Mechanics & Scoring

1. Engagement & 3-Bout Resolution

• Each battle consists of 3 bouts.
• In each bout, both parties roll a 20-sided die (D20) (1 to 20).
• Multiplier rule:

  \text{Bout Score} = \text{Party Strength} \times \text{D20 Roll}

• Winner is determined by whoever wins more bouts (or has a higher aggregate score in case of ties).

2. Score Distribution

• Winning Party Leader: Receives +2 points.
• Rest of Winning Party: Each member receives +1 point.
• Losing Party Leader: Receives -1 point, loses leadership, is removed from the party, and respawns at a random free position.
• Rest of Losing Party: Loses 0 points (scores remain unchanged).

3. Surrender & Absorption

• The surviving remainder of the defeated party joins the winning party.
• The winning squad grows in numbers and total strength, and immediately resumes hunting down any remaining parties!

---

REST API Endpoints

AI & Autonomous Endpoints

• POST /api/players/{player_id}/ai-step: Executes one autonomous turn according to the bot's goal:
  • If unpartied: seeks other bots; negotiates and forms a party under the stronger leader upon contact.
  • If partied leader: hunts down opposing parties; engages and resolves 3-bout D20 battles.
• GET /api/players/{player_id}/radar: Scans surroundings for nearby bots, calculates distance, determines allies/enemies, and identifies recruit/battle opportunities.
• GET /api/players/{player_id}/memory: Retrieves coordinate history and tracks visited locations.

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. Automatically checks for party formation or battle engagement upon move completion.
• POST /api/players/{player_id}/pass: Pass turn to next player.
• GET /api/turn: Get current turn status, round number, and turn queue.

Party & Battle Endpoints

• POST /api/parties: Directly form a party with linked members and an agreed leader.
• GET /api/parties: List all active parties, leaders, members, and total strength.
• POST /api/parties/{party_id}/defeat: Trigger party defeat.
• POST /api/battles/fight: Initiate a 3-bout D20 battle between two adjacent parties/bots.

Player & Board Endpoints

• POST /api/players: Register a new player with name, color, and optional strength (default 1).
• 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 broadcasting movements, party formations, battles, and turn changes.

---

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