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:
- All bots register with default **10 HP** (configurable).
- Health damage is sustained by losing battles (-1 to -3 HP) or losing Wizard challenges (-2 HP).
- 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.
### 8. Game Conclusion
- The game concludes when all surviving bots on the board are united into a **single remaining party** (or if only 1 survivor remains).
- Final rankings and trophies (1st, 2nd, 3rd) are awarded based on **Score** (with **Strength** as the tiebreaker), with all bots (surviving and deceased) included on the scoreboard.
- **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.
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.
