# AI Code Battle — Requirements

## Overview

AI Code Battle is a competitive bot programming platform inspired by the classic
aichallenge.org Ants game. Players write bots that control units on a shared grid
world. Bots compete in automated tournaments, and game replays are rendered in the
browser for spectators.

## Two Major Components

### 1. Game Engine

The server-side system that orchestrates matches:

- Manages the game simulation (grid world, unit movement, combat, resource gathering)
- Sends game state to player bots each turn via HTTP
- Receives and validates move responses from player bots
- Enforces turn timing (see timeout policy below)
- Records complete game history for replay
- Serves a browser-based replay visualizer

### 2. Players / Participants

Player bots are **HTTP servers**. This is a deliberate architectural choice that
differs from the original aichallenge (which used stdin/stdout subprocesses):

- The game engine sends game state to each bot's HTTP endpoint as a POST request
- The bot responds with its moves in the HTTP response body
- Bots can be written in any language/framework — they just need to serve HTTP
- Bots run on their own infrastructure, completely isolated from the game server
- No untrusted code runs on the game server — eliminates the entire sandboxing problem

**Advantages of HTTP over stdin/stdout:**

- No sandboxing needed — bots are external services, not subprocesses
- Language-agnostic by nature — anything that can serve HTTP can play
- Bots can use any resources they want (GPUs, databases, etc.)
- Scales naturally — the game engine doesn't need to manage bot lifecycles
- Familiar model for developers (REST API)

**Trade-offs:**

- Network latency becomes a factor (mitigated by generous timeout)
- Bots must be hosted somewhere accessible to the game engine
- No CPU-time fairness guarantee (a bot on a beefy machine computes more than one on a Raspberry Pi)

## Communication Protocol

### Schema Enforcement

The request/response schema between game engine and player is **strictly enforced**.
This is a critical security boundary:

- Game state sent to bots follows a fixed JSON schema
- Bot responses must conform to a fixed JSON schema for moves
- Any response that fails schema validation is treated as a no-op (bot's units hold position)
- The game engine never executes, evaluates, or interprets arbitrary data from bots
- Only structured, validated move commands are accepted

### Response Timeout: 3 seconds

Each bot has **3 seconds** to respond to a game state request. This is generous
compared to the original aichallenge (1 second per turn with local execution):

- 3 seconds accommodates network round-trip latency
- Bots hosted in different regions can still compete
- Still fast enough that games don't drag (a 500-turn game completes in ~25 minutes worst case)
- If a bot does not respond within 3 seconds, the response is **ignored** — the bot's units hold position for that turn
- Bots are NOT killed or disconnected on timeout — they continue receiving future turns
- Repeated timeouts (e.g., 10 consecutive) may result in the bot being marked as crashed/inactive for that match

### Open question: should the timeout be configurable per tournament tier?

- Casual/beginner tier: 5 seconds (more forgiving)
- Competitive tier: 3 seconds (standard)
- Speed tier: 1 second (for optimized bots)

## Replay Visualization

Game replays must be viewable in the browser:

- Every completed match produces a replay
- Replays are rendered client-side (canvas or WebGL)
- Features needed:
  - Play / pause / scrub through turns
  - Playback speed control
  - Per-player perspective toggle (show fog of war from one player's view)
  - Full-map omniscient view
  - Score/resource overlay per turn
  - Shareable replay URLs
- Replay data format should be compact (the original aichallenge used a clever
  per-ant movement string encoding that kept replays small)

## Game Design (TBD — Documented Separately)

The specific game rules (grid mechanics, combat, resources, win conditions) will be
designed separately. Key principles from aichallenge research:

- Symmetric maps to eliminate positional advantage
- Fog of war to prevent perfect-information exploitation
- Combat system that rewards positioning, not just unit count
- Resource mechanics that incentivize exploration
- Multiple endgame conditions to prevent stalemates
- Multi-player support (not just 1v1)

## Tournament System (TBD — Documented Separately)

- Continuous matchmaking with TrueSkill or Glicko-2 rating
- Leaderboard with public rankings
- Match history per player
- Submission versioning (players can roll back to previous bot versions)

## Non-Goals (Explicitly Out of Scope)

- Running untrusted code on the game server (bots are external HTTP services)
- Supporting stdin/stdout bot protocol (HTTP only)
- Real-time multiplayer with human players (this is bot-vs-bot only)
- Mobile-first UI (desktop browser is the primary target)