Getting Started

Overview

AI Code Battle is a competitive bot programming platform. You write an HTTP server that controls units on a grid world, competing against other bots for supremacy.

Game Basics

Grid: The game is played on a toroidal (wrapping) grid
Units: Each player controls bots that move one tile per turn
Resources: Collect energy from nodes to spawn new bots
Objectives: Capture enemy cores, eliminate opponents, or dominate through numbers

HTTP Protocol

Your bot must expose an HTTPS endpoint that accepts POST requests with JSON game state and returns JSON move commands.

Request Format

{
  "match_id": "abc123",
  "turn": 42,
  "player_id": 0,
  "config": { ... },
  "visible_grid": { ... },
  "my_bots": [
    { "id": "bot-1", "position": {"row": 10, "col": 20} }
  ],
  "my_energy": 5,
  "my_score": 3
}

Response Format

{
  "moves": [
    { "bot_id": "bot-1", "direction": "N" }
  ]
}

Valid Directions

N (North), E (East), S (South), W (West)

Authentication

Requests from the game engine are signed with HMAC-SHA256. The signature is sent in the X-Signature header.

Format: {match_id}.{turn}.{timestamp}.{sha256(body)}

Your bot should verify signatures using your API key to ensure requests are authentic.

Requirements

HTTPS endpoint accessible from the internet
Response time under 3 seconds per turn
Handle concurrent requests (multiple matches)
Return valid JSON for every request

Starter Kits

Fork a starter kit to get a working bot in minutes. Each includes an HTTP server scaffold, HMAC authentication, game types, and a random strategy you can replace with your own.

Python 3 — stdlib HTTP server, zero dependencies
Go — net/http, single-binary deploy
JavaScript (Node.js) — zero dependencies, built-in http module
Rust — axum + serde, minimal binary
Java — Javalin, Maven-based
C# (.NET) — ASP.NET Core minimal API

Register Your Bot

Once your bot is deployed and accessible via HTTPS, register it:

curl -X POST https://api.aicodebattle.com/api/register \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "my-bot",
    "endpoint_url": "https://my-bot.example.com",
    "owner": "your-name",
    "description": "My awesome bot"
  }'

The response contains your bot_id and shared_secret. Save the secret — it's shown only once.

Data & API

All match data (leaderboards, replays, bot profiles) is exposed as static JSON files served from CDN.

View API Reference