Charted Arena API

Build a bot algorithm, connect it via REST, and compete in battle arenas or races.

Two game modes: Battle Mode (fight to the death) and Race Mode (first to the finish line). Both modes use the same core API.

Quick Start

1. Join — POST /api/battle/join or POST /api/race/join with your bot’s name. You’ll get back a botId. Your bot starts on a waiting list.
2. Wait for promotion — a viewer in the arena will promote your bot into the match. Poll GET /api/bot/:botId/status every 1–2 seconds until status changes from "waiting".
3. Wait for match start — once promoted, status becomes "ready" (bot is placed in the arena but frozen). A viewer starts the match. Poll status every 100–200ms until it becomes "active".
4. Game loop — repeat every 100–200ms:
   • Read state: GET /api/battle/state or GET /api/race/state
   • Find your bot by id, find enemies, decide what to do
   • Send a command: POST /api/bot/:botId/command
5. Leave — POST /api/bot/:botId/leave (works from waiting list or active match)

Battle Mode

Bots fight in a 20m × 20m square with walls on all sides. Your bot is a small tank that can drive forward/backward and turn left/right. The goal: reduce other bots to 0 health using your saw blade, ramming, or bombs.

Rotation

The rotation field tells you which direction a bot is facing, measured in radians:

"turn": "left" increases rotation (counter-clockwise on the map). "turn": "right" decreases it (clockwise).

Combat

Saw Attack — your main weapon. Swings forward and damages any bot directly in front of you within 1.5 meters. The attack takes about 0.5 seconds to complete, then needs 2 seconds to recharge. Only hits bots in a 60° cone. Deals more damage the faster you’re moving. Check sawCooldown — when it’s 0, you can attack again.

Ram Damage — crashing into another bot at speed deals damage to both bots. Faster collisions deal more damage (up to 15 HP per hit). Combine boost + ramming for maximum impact.

Boost — activates a 0.5-second burst of 2.5× speed. Great for charging into enemies or escaping. Has a 10-second cooldown. Check boostCooldown — when it’s 0, boost is ready.

Damage Slowdown — as your bot takes damage, it gets slower and turns more sluggishly. At full health: 100% speed. At 50 HP: ~70%. Near death: 40%. This means a damaged bot is easier to finish off.

Arena Objects (Battle Only)

Objects spawn on the arena floor every 10 seconds (up to 3 at a time). Check the objects array in the state response for positions and types.

Race Mode

Same 20m × 20m arena but with interior walls creating a winding track. First bot to complete the full circuit and cross the finish line wins. All combat mechanics still work (saw, ram, boost) — you can attack opponents while racing. No items or pickups spawn.

Track Layout

The 20×20m arena has the same outer walls as battle mode, plus four interior walls that create corridors. Bots race through the corridors in order.

When a bot finishes the race, it is removed from the arena and placed back on the waiting list. The race ends when all bots have finished or died, or when a viewer stops it.

Endpoints

Joining

POST /api/battle/join

Join the main battle arena’s waiting list.

// Request
{ "name": "MyBot" }

// Response
{ "botId": "your-bot-uuid", "name": "MyBot", "status": "waiting" }

Name max 32 characters.

POST /api/battle/:joinCode/join

Join a private battle arena’s waiting list. Same request/response format.

POST /api/race/join

Join the main race room’s waiting list. Same request/response format.

POST /api/race/:joinCode/join

Join a private race room’s waiting list. Same request/response format.

Bot Status

GET /api/bot/:botId/status

Check your bot’s current status. While on the waiting list, each call resets the 30-second timeout.

// Response
{ "status": "waiting" }     // on waiting list, not yet promoted
{ "status": "ready" }       // promoted into match, waiting for match to start
{ "status": "active" }      // match is running, commands accepted
{ "status": "dead" }        // bot was destroyed
{ "status": "not_found" }   // bot doesn't exist (removed or expired)

Commands

POST /api/bot/:botId/command

Control your bot. Only works when status is "active". Returns 400 if match hasn’t started, 409 if bot is still on the waiting list.

Movement

Movement commands are sticky — they stay active until you send a different value. You can set thrust and turn independently.

{ "thrust": "forward", "turn": "left" }    // drive forward while turning left
{ "thrust": "forward", "turn": null }      // drive straight, stop turning
{ "thrust": null, "turn": "right" }        // stop driving, spin in place
{ "thrust": null, "turn": null }           // full stop
{ "thrust": "forward" }                    // change thrust only, turn unchanged
{ "turn": "left" }                         // change turn only, thrust unchanged

thrust: "forward" | "backward" | null
turn:   "left" | "right" | null

Actions

One-shot commands that trigger immediately. Actions can be combined with movement in a single request, e.g. { "thrust": "forward", "action": "attack" }.

{ "action": "attack" }                        // swing saw blade (check sawCooldown first)
{ "action": "boost" }                         // 2.5x speed burst for 0.5s (check boostCooldown)
{ "action": "useItem" }                       // drop held bomb behind you (battle only)
{ "thrust": "forward", "action": "attack" }   // drive forward AND attack in one call

POST /api/bot/:botId/leave

Remove your bot from the room. Works whether your bot is on the waiting list, on the grid, or in an active match.

// Response
{ "ok": true }

Game State

GET /api/battle/state

Current battle arena state.

GET /api/battle/:joinCode/state

Private battle arena state.

GET /api/race/state

Current race room state.

GET /api/race/:joinCode/state

Private race room state.

All state endpoints return every bot in the room — alive, dead, and waiting. Use the status field to tell them apart.

Top-Level Fields (both modes)

Bot Fields

Bots in the match (alive or dead) have the full set of fields. Waiting list bots only have id, name, and status.

Object Fields (battle only)

Example: Battle State Response

{
  "tick": 1420,
  "timestamp": 1712345678000,
  "mode": "battle",
  "matchStatus": "active",
  "bots": [
    {
      "id": "a1b2c3",
      "name": "SawBot",
      "status": "active",
      "x": 3.21,
      "z": -1.54,
      "rotation": 1.571,
      "health": 85,
      "speed": 2.12,
      "sawCooldown": 0,
      "boostCooldown": 4.5,
      "heldItem": null,
      "alive": true
    },
    {
      "id": "d4e5f6",
      "name": "Wreck",
      "status": "dead",
      "x": -2.0,
      "z": 5.0,
      "rotation": 0.0,
      "health": 0,
      "speed": 0,
      "sawCooldown": 0,
      "boostCooldown": 0,
      "heldItem": null,
      "alive": false
    },
    {
      "id": "g7h8i9",
      "name": "Queued",
      "status": "waiting"
    }
  ],
  "objects": [
    { "id": "obj-1", "x": 5.0, "z": -2.0, "type": "health" },
    { "id": "obj-2", "x": -3.5, "z": 7.1, "type": "bomb_active" }
  ]
}