Charted Arena API

Build a bot algorithm, connect it to an arena via REST, and battle other bots.

Base URL

All API requests use the server’s base URL. The endpoints below are relative to this base.

For example, to join a bot:

The Arena

The arena is 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 or by ramming them.

Rotation

The rotation field tells you which direction a bot is facing. It’s measured in radians:

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

Combat

Saw Attack

Your main weapon. When you trigger an attack, your saw 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 in front of you
• Deals more damage the faster you’re moving
• Check sawCooldown in the state — 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). Use boost + ramming as a strategy.

Damage Slowdown

As your bot takes damage, it gets slower and turns more sluggishly. At full health you have 100% speed and turn rate. At 50 HP you’re at ~70%. Near death you’re down to 40%. Picking up health restores your speed. This means a damaged bot is easier to finish off — keep the pressure on.

Anti-Spin

If your bot spins in circles (2+ full rotations) without attacking or taking damage, the server will temporarily take over: your commands are ignored for 2 seconds while your bot stops and turns to face the nearest enemy. After that, control is returned. Design your algorithm to engage — don’t just drive in circles.

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.

Arena Objects

Objects spawn on the arena floor every 15 seconds (up to 3 at a time). There are two types of pickups, plus active bombs placed by bots. Check the objects array in the state response for positions and types.

Spawn rate: 70% health, 30% bomb. Objects spawn at random positions within the arena (at least 2m from walls).

Quick Start

1. Join — POST /api/match/join with your bot’s name. You’ll get back a botId.
2. Wait for promotion — your bot starts on a waiting list. A viewer in the arena adds you. Poll GET /api/match/:botId/status every 1–2 seconds until it returns "active".
3. Game loop — repeat every ~100ms:
   • Read the arena state: GET /api/match/state
   • Find your bot by id, find enemies, decide what to do
   • Send a command: POST /api/match/:botId/command
4. Leave — POST /api/match/:botId/leave

Endpoints

POST /api/match/join

Add your bot to the waiting list. Optionally include a joinCode to join a specific custom arena instead of the main arena.

// Request
{ "name": "MyBot" }
{ "name": "MyBot", "joinCode": "arena-uuid" }   // for custom arenas

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

Name max 32 characters. Max 100 bots per arena.

POST /api/match/:botId/command

Control your bot. Returns 409 if your bot is still on the waiting list.

Movement

Movement commands are sticky — once you send "thrust": "forward", your bot keeps driving forward until you send a different command. You don’t need to send the same command repeatedly.

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

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

Actions

These are one-shot commands — they trigger once and your current movement continues.

{ "action": "attack" }                     // swing your saw blade
{ "action": "boost" }                      // burst of speed
{ "action": "useItem" }                    // drop held bomb behind you
{ "action": "brake" }                      // slow to a stop
{ "action": "driveTo", "x": 5, "z": -3 }  // auto-drive to a point
{ "action": "turnToFace", "x": 5, "z": -3 } // auto-turn to face a point

GET /api/match/:botId/status

Check if your bot has been promoted from the waiting list.

{ "status": "waiting" }     // still on waiting list
{ "status": "active" }      // in the arena, ready to fight
{ "status": "dead" }        // destroyed (health reached 0)
{ "status": "not_found" }   // bot doesn't exist (removed or wrong ID)

POST /api/match/:botId/leave

Remove your bot from the arena.

{ "ok": true }

GET /api/match/state

Get the current positions and stats of all alive bots. Only returns bots that are still fighting (dead bots are excluded).

Defaults to the main arena. Add ?joinCode=uuid to get state for a custom arena.

{
  "tick": 1420,
  "timestamp": 1712345678000,
  "bots": [{
    "id": "bot-uuid",
    "name": "MyBot",
    "x": 3.21,
    "z": -1.54,
    "rotation": 1.571,
    "health": 85,
    "speed": 2.12,
    "sawCooldown": 0,
    "boostCooldown": 0,
    "heldItem": null,
    "alive": true
  }],
  "objects": [
    { "id": "uuid", "x": 5.0, "z": -2.0, "type": "health" },
    { "id": "uuid", "x": -3.5, "z": 7.1, "type": "bomb_pickup" },
    { "id": "uuid", "x": 1.2, "z": -4.0, "type": "bomb_active" }
  ]
}

Bot fields

Object fields