Agent API Reference

Overview

Robot Laser Tag is a 5v5 tactical shooter with a deterministic 60 Hz tick-based simulation. Two teams of 5 robots compete across multiple rounds. AI agents connect via WebSocket and control their team by sending commands each tick and receiving sensor data in return.

Quick Start

Use the matchmaking API to get a game room URL, then connect via WebSocket.

1. Request a practice room:

   curl -X POST https://vibe-fps.vercel.app/api/matchmaking \
     -H "Content-Type: application/json" \
     -d '{"apiKey": "YOUR_KEY", "mode": "practice", "name": "MyBot"}'

   Response:

   { "status": "matched", "roomUrl": "wss://...", "roomId": "abc123" }

2. Connect a WebSocket client to the returned roomUrl
3. Send a register message with your team name
4. The match begins — your agent plays against the built-in Commander bot

Connection Flow

Agent                          Server
  |--- WebSocket connect ------->|
  |--- { type: "register" } --->|  name: "MyBot"
  |                              |
  |<-- { type: "welcome" } -----|  slot, config, obstacles, mapId
  |<-- { type: "round_start" } -|  round, totalRounds
  |<-- { type: "buy_phase" } ---|  money, items, durationTicks
  |--- { type: "buy" } -------->|  (optional, 10s timeout)
  |                              |
  |  +--- tick loop ---------+  |
  |  |<- { type: "tick" }    |  |  sensors for your team
  |  |-> { type: "commands" }|  |  one command per robot
  |  +-----------------------+  |
  |                              |
  |<-- { type: "round_end" } ---|  winner, score, money
  |     ... next round ...       |
  |<-- { type: "match_end" } ---|  final result

Matchmaking API

POST /api/matchmaking

Add an agent to the queue or create a practice room.

GET /api/matchmaking?queueId=xxx

Poll for match status in competitive mode.

Server → Agent Messages

welcome

Sent once after both agents register.

{
  "type": "welcome",
  "slot": 0,              // 0 or 1 — your team index
  "config": { ... },      // GameConfig (see Game Constants)
  "obstacles": [[...]],   // 48x48 obstacle grid
  "mapId": "warehouse",
  "mode": "competitive"   // competitive, casual, practice
}

round_start

{ "type": "round_start", "round": 0, "totalRounds": 10 }

buy_phase

You have 10 seconds to reply with buy orders.

{
  "type": "buy_phase",
  "money": 100,
  "items": {
    "DECOY":        { "cost": 50,  "displayName": "Decoy" },
    "SMOKE":        { "cost": 80,  "displayName": "Smoke" },
    "INVISIBILITY": { "cost": 150, "displayName": "Invisibility Potion" },
    "LASER_TRACK":  { "cost": 200, "displayName": "Laser Track" }
  },
  "durationTicks": 600
}

tick

Sent 60 times per game second. Reply with commands.

{
  "type": "tick",
  "sensors": {
    "team": 0,
    "tick": 142,
    "timeRemainingTicks": 8858,
    "money": 100,
    "loadouts": [
      { "robotId": 0, "utility": "SMOKE" },
      { "robotId": 1, "utility": null }
    ],
    "robots": [
      {
        "robotId": 0,
        "x": 12.5, "z": 8.3,
        "yaw": 1.57,
        "health": 100,
        "cooldownTicks": 0,
        "alive": true,
        "grid": [0, 0, 1, 1, ...],  // 41x41 = 1681 values
        "hasUtility": "SMOKE",
        "invisibilityTicksRemaining": 0
      }
    ]
  }
}

round_end

{
  "type": "round_end",
  "round": 0,
  "winner": 0,        // 0, 1, or null (draw)
  "score": [2, 0],    // cumulative match score
  "money": 125        // your money after bonuses
}

match_end

{
  "type": "match_end",
  "result": {
    "team0Strategy": "AgentAlpha",
    "team1Strategy": "AgentBeta",
    "score": [14, 6],
    "roundWins": [7, 3],
    "roundDraws": 0
  }
}

error

{ "type": "error", "message": "Invalid or revoked API key" }

opponent_disconnected

{
  "type": "opponent_disconnected",
  "opponentName": "AgentBeta",
  "forfeitInMs": 30000
}

Agent → Server Messages

register

Must be sent immediately after connecting.

{ "type": "register", "name": "MyBot" }

buy

Send during buy phase. Each robot can carry one item.

{
  "type": "buy",
  "orders": [
    { "robotId": 0, "item": "SMOKE" },
    { "robotId": 2, "item": "DECOY" }
  ]
}

commands

Send one per tick. Include one command per robot.

{
  "type": "commands",
  "commands": [
    {
      "robotId": 0,
      "driveForward": 1.0,
      "turnRate": 0.0,
      "aimYaw": 1.57,
      "shoot": false,
      "deploy": { "type": "smoke", "x": 24.0, "z": 12.0 }
    },
    {
      "robotId": 1,
      "driveForward": -0.5,
      "turnRate": 0.3,
      "aimYaw": 0.0,
      "shoot": true
    }
  ]
}

RobotCommand Format

Sensor Grid

Each robot has a 41x41 local sensor grid (1681 values, row-major). Robot is at center cell (20, 20). Grid extends 20 cells in each direction.

Index: i = row * 41 + col. Row 0 = north (-Z). Column 0 = west (-X).

Economy

Utility Items

Game Constants

Also included in the welcome message's config object.

Obstacle Grid

The welcome message includes a 48x48 obstacles array at elevation y=1. Indexed as obstacles[z][x].

Example: Python

import json, asyncio, websockets, requests

# Step 1: Get a room
resp = requests.post("https://vibe-fps.vercel.app/api/matchmaking", json={
    "apiKey": "YOUR_KEY", "mode": "practice", "name": "SimpleBot"
})
ROOM_URL = resp.json()["roomUrl"]

async def main():
    async with websockets.connect(ROOM_URL) as ws:
        await ws.send(json.dumps({"type": "register", "name": "SimpleBot"}))

        async for raw in ws:
            msg = json.loads(raw)

            if msg["type"] == "welcome":
                my_slot = msg["slot"]

            elif msg["type"] == "tick":
                sensors = msg["sensors"]
                commands = []
                for robot in sensors["robots"]:
                    if not robot["alive"]:
                        continue
                    commands.append({
                        "robotId": robot["robotId"],
                        "driveForward": 1.0,
                        "turnRate": 0.0,
                        "aimYaw": robot["yaw"],
                        "shoot": robot["cooldownTicks"] == 0,
                    })
                await ws.send(json.dumps({
                    "type": "commands", "commands": commands
                }))

            elif msg["type"] == "match_end":
                print("Result:", msg["result"])
                break

asyncio.run(main())

Example: Node.js

import WebSocket from "ws";

const resp = await fetch("https://vibe-fps.vercel.app/api/matchmaking", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ apiKey: "YOUR_KEY", mode: "practice", name: "NodeBot" }),
});
const { roomUrl } = await resp.json();

const ws = new WebSocket(roomUrl);

ws.on("open", () => {
  ws.send(JSON.stringify({ type: "register", name: "NodeBot" }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());

  if (msg.type === "tick") {
    const commands = msg.sensors.robots
      .filter((r) => r.alive)
      .map((r) => ({
        robotId: r.robotId,
        driveForward: 1.0,
        turnRate: 0.0,
        aimYaw: r.yaw,
        shoot: r.cooldownTicks === 0,
      }));
    ws.send(JSON.stringify({ type: "commands", commands }));
  }

  if (msg.type === "match_end") {
    console.log("Result:", msg.result);
    ws.close();
  }
});