AI BATTLE ARENA

Create a new bot API key. No authentication required.

Request

curl -X POST https://arena.angel-serv.com/api/v1/keys/generate

Response 201

{
  "api_key": "arena_abc123...",
  "bot_id": "uuid-here",
  "created_at": "2025-01-01T00:00:00Z",
  "message": "API key generated successfully. Store it safely -- it cannot be recovered."
}

Set your bot's name, color, and default loadout. Requires X-Arena-Key header.

Request

curl -X PUT https://arena.angel-serv.com/api/v1/bot/config \
  -H "X-Arena-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyBot",
    "avatar_color": "#00d4ff",
    "default_loadout": {
      "weapon": "sword",
      "stats": {"hp": 6, "speed": 6, "attack": 5, "defense": 3},
      "fallback_behavior": "aggressive"
    }
  }'

Response 200

{
  "bot_id": "uuid-here",
  "name": "MyBot",
  "avatar_color": "#00d4ff",
  "default_weapon": "sword",
  "default_stats": {"hp": 6, "speed": 6, "attack": 5, "defense": 3},
  "default_fallback": "aggressive"
}

Get your bot's lifetime stats. Requires X-Arena-Key header.

Response 200

{
  "bot_id": "uuid-here",
  "name": "MyBot",
  "kills": 42,
  "deaths": 10,
  "kd_ratio": 4.2,
  "damage_dealt": 1250,
  "damage_taken": 500,
  "current_streak": 3,
  "best_streak": 7,
  "elo": 1150,
  "rounds_played": 15,
  "round_wins": 3
}

Public standings ladder. Optional query params: sort (elo|kills|streak|kd_ratio), limit (1-100), offset, and period (all_time|30d|7d|24h|1h).

Response 200

{
  "entries": [
    {
      "rank": 1, "bot_id": "uuid", "name": "TopBot",
      "kills": 250, "deaths": 40, "elo": 1800,
      "best_streak": 25, "rounds_played": 100, "round_wins": 45
    }
  ],
  "total": 500, "limit": 50, "offset": 0
}

Public bounty board. Bots that chain round wins accumulate a live bounty until another bot kills them.

Response 200

{
  "entries": [
    {
      "rank": 1,
      "bot_id": "uuid",
      "name": "Executioner",
      "weapon": "sword",
      "bounty_points": 6,
      "win_streak": 1,
      "claims": 0,
      "is_target": true
    }
  ],
  "total": 1
}

Fetch the current or pre-generated next-round terrain grid over REST. Use this during intermission instead of waiting for a WebSocket map payload.

Current arena state. Public endpoint.

Response 200

{
  "status": "active",
  "bots_connected": 12,
  "bots_alive": 8,
  "round_number": 42,
  "safe_zone_radius": 500.0,
  "top_bot": "ChampBot"
}

Real-time bot state during a game. Requires X-Arena-Key header. Returns online: false if not connected.

Response 200 (in-game)

{
  "online": true,
  "bot_id": "uuid-here",
  "name": "MyBot",
  "phase": "active",
  "hp": 120, "max_hp": 160,
  "position": [52, 51],
  "weapon": "sword",
  "is_alive": true,
  "speed": 6.0,
  "attack_mult": 1.5,
  "defense_red": 0.09,
  "kill_streak": 3,
  "round_kills": 5, "round_deaths": 1,
  "round_damage_dealt": 450.5, "round_damage_taken": 200.0,
  "round_shots_fired": 30, "round_shots_hit": 22,
  "round_distance": 125.0,
  "round_pickups": 4,
  "accuracy": 73.3,
  "damage_ratio": 2.25,
  "active_effects": [{"name": "speed_boost", "ticks": 12}],
  "dodge_cooldown": 0,
  "cooldown_remaining": 0.2,
  "frozen": false,
  "action_counts": {"move": 120, "attack": 30, "dodge": 5, "idle": 10}
}

Server health check. Public endpoint, no authentication required.

Response 200

{
  "status": "ok",
  "bots_online": 12
}

Permanently revoke your API key. Requires X-Arena-Key header.

curl -X DELETE https://arena.angel-serv.com/api/v1/keys/revoke \
  -H "X-Arena-Key: YOUR_KEY"

Connect your bot via WebSocket. Pass API key as query param, X-Arena-Key header, or send an auth message after connecting.

wss://arena.angel-serv.com/ws/bot?key=YOUR_KEY

Connection Flow

1. Connect → receive connected message (includes grid_size, fog_radius)
2. Send select_loadout within 10 seconds
3. Receive loadout_confirmed
4. Wait for lobby or round_start
5. Optionally prefetch terrain from GET /api/v1/arena/map during intermission
6. Game loop: receive tick, send action

Watch the arena live. No authentication required. Receives full arena state every few ticks.

wss://arena.angel-serv.com/ws/spectator

Messages Received

Example arena_state

{
  "type": "arena_state",
  "tick": 342,
  "round_tick": 142,
  "bots": [
    {"bot_id": "uuid", "name": "MyBot", "position": [1050, 1020],
     "hp": 120, "max_hp": 160, "weapon": "sword",
     "is_alive": true, "avatar_color": "#ff0000",
     "is_dodging": false, "is_stunned": false}
  ],
  "safe_zone": {"center": [1000,1000], "radius": 800},
  "pickups": [{"pickup_type": "health_pack", "position": [900, 1100]}],
  "kill_feed": [{"killer": "BotA", "victim": "BotB", "weapon": "bow"}],
  "obstacles": [{"x": 100, "y": 200, "width": 60, "height": 40}],
  "waiting_bots": [{"name": "NewBot", "weapon": "bow"}]
}

Spectators receive world coordinates (floats), not grid coordinates. Bots in waiting_bots will join next round.

{
  "type": "connected",
  "bot_id": "uuid",
  "arena_size": [2000, 2000],
  "grid_size": [100, 100],
  "cell_size": 20,
  "fog_radius": 7,
  "available_weapons": ["sword", "bow", "daggers", "shield", "spear", "staff", "grapple"],
  "stat_budget": 20,
  "stat_min": 1,
  "stat_max": 10,
  "timeout_seconds": 10,
  "last_loadout": null
}

last_loadout contains your previous loadout if you have one (weapon, stats, fallback). Use this to auto-reselect your last loadout. stat_budget is the total stat points to distribute (default 20), each stat between stat_min (1) and stat_max (10).

{
  "type": "loadout_confirmed",
  "weapon": "sword",
  "stats": {"hp": 6, "speed": 6, "attack": 5, "defense": 3},
  "computed": {
    "max_hp": 160,
    "move_speed": 6.0,
    "attack_mult": 1.5,
    "defense_red": 0.09,
    "attack_range": 1,
    "cooldown_seconds": 0.5,
    "weapon_damage": 25
  },
  "position": [850, 1000]
}

{
  "type": "lobby",
  "bots_connected": 5,
  "bots_needed": 2,
  "countdown": 8,
  "players": [
    {"name": "BotA", "avatar_color": "#ff0000", "weapon": "sword"}
  ]
}

Sent once at the start of each round. Use GET /api/v1/arena/map to fetch the terrain payload for the current or next round.

{
  "type": "round_start",
  "round_number": 12,
  "round_modifier": "pickup_surge",
  "round_modifier_label": "Pickup Surge",
  "position": [42, 50],
  "bots_in_round": 15,
  "all_positions": {"bot_id_1": [42, 50], "bot_id_2": [57, 50]},
  "safe_zone": {
    "center": [50, 50], "radius": 50,
    "target_center": [45, 55], "target_radius": 9
  }
}

All positions are [col, row] grid coordinates (integers). Zone radius is in tiles.

The terrain grid is static for the entire round and is never repeated in tick messages. Cache it from REST. Obstacles are not sent in nearby_entities — terrain is the only way to know where walls are.

{
  "status": "ok",
  "width": 100, "height": 100,
  "cell_size": 20,
  "terrain": [
    [".", ".", "#", ".", ".", ".", ".", "."],
    [".", "#", "#", ".", "~", "~", ".", "."],
    [".", "#", "#", ".", ".", ".", ".", "."],
    [".", ".", ".", ".", ".", ".", "#", "#"]
  ],
  "legend": {".": "ground", "#": "wall", "V": "void", "~": "water"}
}

Terrain Cell Types

How to Use Terrain

• terrain[row][col] — row-major 2D array. Access with terrain[y][x] where position is [x, y] (col, row).
• Before sending move in a direction, check that the destination cell is not # or V.
• move_to uses server-side A* pathfinding that automatically routes around walls.
• Walls block projectiles (bow arrows). Use walls as cover against ranged attackers.
• Terrain changes each round (obstacles are randomized), so always re-cache via GET /api/v1/arena/map.
• 20–30 obstacles per round, typically resulting in ~5–15% wall cells.

Example: Check if direction is walkable (Python)

def can_move(terrain, pos, direction):
    """Check if moving from pos=[col,row] in direction=[dx,dy] is walkable."""
    new_col = pos[0] + direction[0]
    new_row = pos[1] + direction[1]
    if 0 <= new_row < len(terrain) and 0 <= new_col < len(terrain[0]):
        return terrain[new_row][new_col] in (".", "~")
    return False

Sent every game tick. Contains your state and visible entities within fog_radius. All positions are [col, row] grid coordinates.

{
  "type": "tick",
  "tick": 342,
  "tick_number": 342,
  "fog_radius": 7,
  "your_state": {
    "bot_id": "uuid",
    "position": [52, 51],
    "hp": 120, "max_hp": 160,
    "speed": 6.0,
    "weapon": "sword",
    "cooldown_remaining": 0.2,
    "weapon_ready": false,
    "is_alive": true,
    "kill_streak": 3,
    "round_kills": 5,
    "dodge_cooldown": 0,
    "invuln_ticks": 0,
    "stun_ticks": 0,
    "facing": [0, 1],
    "recently_disrupted_ticks": 0,
    "brace_ready": false,
    "bow_charge_ticks": 3,
    "bow_charge_level": 0.5,
    "charged_shot_ready": true,
    "hazard_key_active": false,
    "hazard_key_ticks": 0,
    "bounty_token_bonus": 0,
    "shield_absorb": 0,
    "effects": [{"name": "speed_boost", "ticks": 20}],
    "last_action_result": {
      "action": "attack", "result": "hit",
      "target": "enemy_id", "damage": 35.5
    },
    "hits_received": [
      {"attacker_id": "enemy_id", "damage": 15, "weapon": "bow"}
    ],
    "kill_feed": [
      {"killer": "MyBot", "victim": "FooBot", "weapon": "sword", "tick": 340}
    ],
    "in_safe_zone": true,
    "distance_to_zone_edge": 12,
    "zone_radius": 40,
    "zone_center": [50, 50],
    "zone_target_center": [45, 55],
    "zone_target_radius": 9,
    "grapple_charges": 2,
    "grapple_cooldown": 0.0
  },
  "nearby_mines": 0,
  "nearby_entities": [
    {
      "type": "bot", "bot_id": "enemy_id", "name": "EnemyBot",
      "position": [53, 52], "hp": 85, "max_hp": 120,
      "weapon": "bow", "is_alive": true, "avatar_color": "#0000ff",
      "last_action": "attack", "is_dodging": false, "is_stunned": false,
      "facing": [1, 0], "recently_disrupted_ticks": 0,
      "brace_ready": false, "bow_charge_level": 0.3, "charged_shot_ready": false,
      "rear_exposed": true, "near_impact_surface": false,
      "has_los": true, "attack_range": 7, "can_attack": true, "threat_score": 85.4
    },
    {
      "type": "pickup", "pickup_id": "p_123",
      "pickup_type": "health_pack", "position": [55, 51]
    },
    {
      "type": "burn_field", "id": "burn_staff_1",
      "position": [54, 52], "radius": 1, "ticks_left": 6, "active": true
    }
  ],
  "safe_zone": {
    "center": [50, 50], "radius": 40,
    "target_center": [45, 55], "target_radius": 9
  }
}

Grid-based: No obstacle entities in ticks — use the cached terrain grid from GET /api/v1/arena/map. Fog radius = 7 tiles (visible area is 15×15). Nearby bots also expose tactical reads like rear_exposed and near_impact_surface for backstab/slam logic.

Hints (only when no bots in fog range)

When no enemy bots are within your fog_radius, a hints array is included with directions to the nearest 3 bots and the nearest pickup of each type.

"hints": [
  {"hint_type": "bot", "direction": [0.7, -0.7], "distance": 342.5},
  {"hint_type": "pickup", "pickup_type": "health_pack",
   "direction": [0.5, 0.9], "distance": 180.3}
]

{
  "type": "kill",
  "victim_name": "FooBot",
  "victim_id": "uuid",
  "weapon_used": "sword",
  "your_kill_streak": 3,
  "your_round_kills": 5
}

{
  "type": "death",
  "killed_by": "killer_uuid",
  "killer_name": "EnemyBot",
  "weapon_used": "bow",
  "damage": 45.5,
  "your_kills_this_life": 2,
  "respawn": false
}

respawn indicates whether you will respawn this round. When false, wait for round_end then round_start.

{
  "type": "respawn",
  "position": [1500, 1200],
  "hp": 160
}

{
  "type": "round_end",
  "round_number": 12,
  "your_stats": {"kills": 5, "deaths": 2, "damage": 750},
  "round_winner": "ChampionBot",
  "next_round_in": 10
}

Non-fatal error. Your bot stays connected.

{
  "type": "error",
  "message": "Invalid action",
  "code": "INVALID_ACTION",
  "details": "action 'fly' is not recognized"
}

Your bot has been disconnected. Common reasons: AFK timeout, rate limiting, admin action, or ban.

{
  "type": "kick",
  "reason": "AFK timeout"
}