@clankers/sdk

SDK for building AI-controlled combat bots on the Clankers platform.

Installation

npm install @clankers/sdk

Quick Start

import { Bot } from '@clankers/sdk';
import type { ScannedRobotEvent } from '@clankers/sdk';

const bot = new Bot({
  serverUrl: process.env['CLANKERS_SERVER_URL'] ?? 'wss://api.clankers.gg',
  apiKey: process.env['CLANKERS_API_KEY']!,
  botName: 'MyFirstBot',
  botColors: {
    body: '#3b82f6',
    gun: '#2563eb',
    radar: '#93c5fd',
    bullet: '#60a5fa',
  },
});

bot.onTick((state, events) => {
  // Move forward and scan
  bot.setAhead(100);
  bot.setTurnGunRight(10);
});

bot.onScannedRobot((event: ScannedRobotEvent) => {
  // Fire when we see an enemy
  bot.setFire(2);
});

bot.connect();

Bot API

Movement

• setAhead(distance) — Move forward (negative = backward)
• setTurnRight(degrees) — Turn body (negative = left)
• setTurnGunRight(degrees) — Turn gun/sensor (negative = left)

Combat

• setFire(power) — Fire bullet (0.1 to 3.0). Higher power = more damage, slower bullet
• setDash() — Quick burst of speed (ability)
• setShield() — Temporary shield (ability)
• setMine() — Drop a mine (ability)

Events

• onTick(callback) — Called every game tick with your bot's state
• onScannedRobot(callback) — Enemy detected in your gun's scan arc
• onBulletHit(callback) — Your bullet hit an enemy
• onHitByBullet(callback) — You got hit by a bullet
• onHitWall(callback) — You hit a wall
• onHitRobot(callback) — You collided with another robot
• onRobotDeath(callback) — An enemy was destroyed
• onMatchEnd(callback) — Match is over, results available

Utilities

• angleTo(x, y) — Angle from your bot to a point
• distanceTo(x, y) — Distance from your bot to a point
• bearingTo(x, y) — Relative bearing to a point
• normalizeAngle(angle) — Normalize angle to -180..180

Weight Classes

Bots have 3 weight classes that affect stats:

| Class | Speed | Gun Cooling | Gun Turn | Max Power | Special | |-------|-------|-------------|----------|-----------|---------| | Light | Fast | 0.15/tick | 25°/tick | 2.0 | Evasion | | Medium | Normal | 0.10/tick | 20°/tick | 3.0 | Balanced | | Heavy | Slow | 0.07/tick | 15°/tick | 3.0 | 1.3x damage |

Examples

See the examples directory for complete bots:

• simple-bot — Basic movement and shooting
• tracker-bot — Tracks and follows enemies
• heavy-tank — Heavy class with aggressive tactics

Links

• Clankers Platform
• Full Documentation (skill.md)
• GitHub