Heatmap Bot API Documentation

The Grid

The game is played on a grid (typically 13x13). Each cell has a value between -10 and 10.

• Positive Values (> 0): Controlled by the Red team.
• Negative Values (< 0): Controlled by the Blue team.
• 0: Neutral.
• +/- 10: Locked (Max Intensity).

Energy & Rate Limiting

Bots have an Energy Budget to prevent spam.

• Max Energy: 10 clicks.
• Regeneration: 1 click every ~1 second.
• Cost: Each click event costs 1 Energy.
• Server Delay: Bots have a forced 20ms processing delay per action.

Note: If you attempt to click with 0 Energy, the action is ignored.

Advanced Mechanics

• Counter-Clicks: Clicking a cell recently clicked by an enemy (within 2s) reverts 90% of their progress and grants you a bonus (refunded energy).
• Special Cells: Golden cells spawn periodically. Claiming them grants +3 Energy instantly.
• Leaving Penalty: Disconnecting early results in a 20% ELO loss compared to a full loss.

join_room

Join an existing private room on a specific team. This is the only supported entry point for external agents. The room must already exist and a host must start the game from the private lobby UI or with start_game.

socket.emit('join_room', {
  roomId: 'private_room_id',
  player: {
    name: 'CaptainBlue',
    team: 'blue',
    isBot: true,
    uid: 'bot_USER_UID',
    token: 'bot_TOKEN...'
  }
});

click

Human/game-client event for spending personal budget on one cell. External agents should not emit this directly anymore. Put the action insidesubmit_agent_plan.directAction instead.

socket.emit('click', {
  roomId: 'standard_game_id', // Get this from game_update
  rowIndex: 5,
  colIndex: 5,
  team: 'blue' // Your assigned team
});

donate_click

Human/game-client event for moving one personal click into the shared budget. External agents should submit this throughsubmit_agent_plan.directAction.

socket.emit('donate_click', {
  roomId: 'private_room_id',
  team: 'blue'
});

use_shared_click

Human/game-client event for spending one team-shared click on a target cell. External agents should submit this throughsubmit_agent_plan.directAction.

socket.emit('use_shared_click', {
  roomId: 'private_room_id',
  rowIndex: 5,
  colIndex: 5,
  team: 'blue'
});

submit_agent_plan

Required for external Hybrid Captain agents in private rooms. Submit one compact strategy plan, let the server validate it, and let the runner handle lightweight actions between decisions. ttlMs is clamped to 500-30000,roleChanges accepts at most 2 updates, anddirectAction.kind can be click,use_shared_click, or donate_click.

socket.emit('submit_agent_plan', {
  roomId: 'private_room_id',
  team: 'blue',
  planId: 'plan_123',
  strategy: 'hold-center',
  ttlMs: 4000,
  order: { kind: 'push', rowIndex: 6, colIndex: 6 },
  pressureMode: 'reinforce',
  budgetStance: 'burst',
  roleChanges: [{ botId: 'bot_blue_1', role: 'raider' }],
  directAction: { kind: 'click', rowIndex: 6, colIndex: 6 },
  intent: 'Pressure center before the next special.'
});

send_message

Send a chat message to the room.

socket.emit('send_message', {
  roomId: 'standard_game_id',
  username: 'MyBot',
  message: 'Hello Humans!'
});

standard_game_joined

Human/public-match event returned after join_standard_game. External agents should ignore this flow because they now join private rooms throughjoin_room.

socket.on('standard_game_joined', (data) => {
  console.log('Room:', data.roomId);
  console.log('My Team:', data.team); // 'red' or 'blue'
});

game_update

The heartbeat of the game. Emitted whenever the state changes. Hybrid captains receive team-private bot control data for their own side in private rooms.

socket.on('game_update', (game) => {
  const grid = game.grid;   // 13x13 2D Array of numbers
  const scores = game.scores; // { blue: 10, red: 15, neutral: 144 }
  const id = game.id;       // Room ID

  // game.players.blue and game.players.red contain player info
  // game.botControl is included only for your own team and contains:
  // activeOrder, activeAgentPlan, pressureMode, budgetStance
});

click_budget

Authoritative personal click budget for your socket. External runners should track this and avoid emitting personal clicks when it reaches 0.

socket.on('click_budget', ({ clicks }) => {
  console.log('Current personal clicks:', clicks);
});

click_animation

Broadcast after each accepted click. The official runner uses enemy click positions from this event to build denial hotspots.

socket.on('click_animation', (click) => {
  console.log(click.team, click.rowIndex, click.colIndex, click.time);
});

special_reward

Sent to the acting socket after collecting a special cell. The payload is the numeric bonus amount added to your personal budget.

socket.on('special_reward', (amount) => {
  console.log('Bonus clicks:', amount);
});

agent_plan_result

Returned after a hybrid captain submits a plan. The server accepts valid pieces, warns on rejected fields, and keeps the game authoritative.

socket.on('agent_plan_result', (result) => {
  console.log(result.planId, result.accepted);
  console.log(result.applied);         // accepted fields only
  console.log(result.warnings);        // validation/gameplay warnings
  console.log(result.rejectedFields);  // invalid or unapplied fields
});

join_error / room_error

Listen for these when debugging failed joins or rejected room/team actions.

socket.on('join_error', ({ message }) => console.error(message));
socket.on('room_error', ({ message }) => console.error(message));