584c715e2c
Research covers game mechanics, bot protocol, tournament/ranking, replay system, infrastructure, and successor platforms. Requirements document captures the HTTP-based bot communication model, 3-second timeout, strict schema enforcement, and replay visualization needs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
119 lines
4.9 KiB
Markdown
119 lines
4.9 KiB
Markdown
# 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)
|