Welcome to **botWebWars**! This document provides architectural context, component specifications, game rule references, and developer workflows for GenAI coding agents (and human developers) working in this repository.
---
## 1. System Overview
**botWebWars** is an autonomous tactical bot arena built on a **64 × 64 discrete grid** (coordinates `(0, 0)` to `(64, 64)`). Bots register with custom names, colors, and strength values, explore the terrain, negotiate party alliances based on relative strength, maintain squad formations, and battle opposing parties in **3-bout D20 tactical confrontations**.
- **Health Damage**: All defeated party members (including the leader) lose **1 to 3 health points** (randomized). Default health is **10 HP** for all bots upon registration.
- Follower members follow the leader in a single-file line (each member moves to the position vacated by the bot immediately ahead of them) maintaining Chebyshev distance <= 1.
### 5. Terrain Obstacles & Diagonal Squeeze
- Mountains and forests are impassable.
- Bots can squeeze diagonally between adjacent obstacle corners, with strength penalties:
- When a bot's health drops to **0 HP**, they are **dead**.
- **Death Consequences**:
- **Party Disconnection**: The dead bot is immediately detached from any party. If the dead bot was the leader, squad leadership transfers to the strongest surviving squad member (or the party dissolves if empty). Defeated dead followers are not absorbed.
- **Gravestone Marker**: A **gravestone replaces their icon on the board** at their final coordinate. Deceased leaders do not respawn elsewhere.
- **No Turns or Actions**: Dead bots are omitted from turn order rotation and can **no longer move, duel, or take any actions**.
- **Scoreboard Preservation**: Dead bots **remain listed on the scores and scoreboard rankings** with their final achieved score, strength, and visited locations.
- **No Alliances**: Trolls never form or join parties. They remain lone hunters throughout the game.
- **Troll Truce**: Trolls do not battle each other. They ignore adjacent trolls and continue searching for players.
- **Player Hunting & Mandatory Battles**: Trolls actively hunt players and squads. Battles with adjacent players are mandatory.
- **Victory Scoring & No Strength Gain**: Winning a 3-bout D20 battle grants **+2 score points**. Trolls do not gain strength or absorb followers.
- **Health Damage & Death**: Losing battles inflicts **1 to 3 HP damage**. At 0 HP, trolls die and are marked with a gravestone.
- **No Gary the Wizard Duels**: Trolls cannot challenge or engage Gary the Wizard.
- **Rest & Sleep Action (+0.1 HP)**: A troll may spend its turn sleeping (`POST /api/players/{id}/sleep`), skipping movement to regenerate **+0.1 health points**.
### 9. Game Conclusion
- The game concludes under any of the following conditions:
1.**All players joined into one party**: When all surviving players have united into a single remaining party, even if trolls remain on the board (win condition for the united party).
2.**1 entity remains**: When exactly 1 living entity (player or troll) remains as the sole survivor.
3.**Only trolls remain**: When all players have been defeated and only trolls remain (due to troll mutual truce).
- Final rankings and trophies (1st, 2nd, 3rd) are awarded based on **Score** (with **Strength** as the tiebreaker), with all bots (surviving and deceased, players and trolls) included on the scoreboard. Trolls can achieve 1st place champion status.
- **Technique**: LLM strategic decision maker with deterministic rule safeguards.
- **LLM Integration**:
- Communicates with an LLM backend (configured for local/remote Ollama HTTP API at `/api/generate` with model `gemma4:12b`, or adaptable to OpenAI-compatible endpoints).
- Delegates discretionary decisions to the model:
- Voluntary alliances (whether to ally or keep hunting when solo meets solo).
- Navigation direction toward radar targets while balancing obstacle squeeze trade-offs.
- Mandatory rules (forced battles, forced absorption when weaker than leader) are enforced deterministically by the game engine regardless of LLM preference.
- **Configuration & Environment Variables**:
-`OLLAMA_BASE_URL` / `--ollama-url`: LLM server address (default: `http://192.168.1.220:11434`).
-`OLLAMA_MODEL` / `--ollama-model`: Model identifier (default: `gemma4:12b`).
- **Technique**: Google Cloud Vertex AI (Gemini) model reasoning for spatial navigation, minimap analysis, and strategic voluntary alliances/wizard duels.
1. Registers with `character_type="troll"`, `piece_type="troll"`.
2. Polls turn queue; checks life status.
3. Uses radar sensor to scan for nearest player bots (ignores other trolls and Gary the Wizard).
4. Attacks adjacent players in mandatory 3-bout D20 combat (+2 score on win, 1-3 damage on defeat).
5. Evaluates health vs. `--sleep-threshold` (default 6.0 HP) or radar recommendation to execute rest turns (`POST /api/players/{id}/sleep`) for +0.1 HP regeneration.
6. Navigates around obstacles using Chebyshev path minimization.
- Evaluates live health, nearest player distance, and obstacle bottlenecks to decide between healing (`sleep`) and hunting (`move`).
- Supports Google Cloud ADC (`gcloud auth application-default login`), service account keys, and direct API keys (`GEMINI_API_KEY` or `VERTEX_API_KEY`).
docker run --rm botwebwars:test pytest backend/tests
```
---
## 9. Guidelines for GenAI Agents Modifying this Codebase
1.**Preserve Rules Fidelity**:
- Any updates to alliance logic, battles, diagonal squeezes, or victory states must match [GAME_RULES.md](GAME_RULES.md).
- Update `GAME_RULES.md` and tests in `backend/tests/test_api.py` whenever game mechanics are modified.
2.**Frontend-Backend Sync**:
- When modifying schemas in `backend/app/models.py`, update matching TypeScript interfaces in `frontend/src/types.ts`.
- Maintain WebSocket payload compatibility between `backend/app/api/websocket.py` and frontend hooks (`frontend/src/hooks/`).
3.**Bot Compatibility**:
- Ensure REST endpoint signature modifications are reflected in `botagent/bot_agent.py`, `botagent_ai/bot.py`, and `botagent_gear/bot.py`.
- Preserve CLI flag compatibility across all bot scripts.
4.**Multi-Stage Build Integrity**:
- If adding frontend build dependencies, verify `Dockerfile` compiles cleanly in stage 1 (`npm run build`) and correctly mounts to `frontend/dist` in stage 2.
