BlockWarriors/ docs
DashboardHome

Bot API Reference

Complete reference for writing bot strategies. Your bot receives a BotAPI object with methods to control movement, combat, and read game state.

Strategy Interface

Your bot is defined as a Strategy object with lifecycle callbacks. Only onSpawn and onTick are required.

Strategy
interface Strategy {
  // Called once when your bot spawns in the world
  onSpawn(bot: BotAPI): void;

  // Called every 500ms while the match is active
  onTick(bot: BotAPI, state: GameState): void;

  // Called when your bot dies (optional)
  onDeath?(bot: BotAPI): void;

  // Called when your bot takes damage (optional)
  onDamage?(bot: BotAPI, attacker?: EntityInfo): void;

  // Called when a chat message is received (optional)
  onChat?(bot: BotAPI, sender: string, message: string): void;
}

BotAPI Methods

State Properties

These read-only properties are available on the BotAPI object:

.position
Vec3

Bot's current position { x, y, z }

.health
number

Current health (0-20, where 20 = 10 hearts)

.food
number

Current food level (0-20)

.inventory
Item[]

Array of items in the bot's inventory

.nearbyEntities
EntityInfo[]

All entities within render distance

.nearbyPlayers
EntityInfo[]

All players within render distance (both teams)

.nearbyEnemies
EntityInfo[]

Enemy team players within render distance

Types

Types
interface Vec3 {
  x: number;
  y: number;
  z: number;
  distanceTo(other: Vec3): number;
}

interface EntityInfo {
  id: number;
  name: string;
  type: string;         // "player", "mob", etc.
  position: Vec3;
  health?: number;
}

interface GameState {
  matchId: string;
  gameType: string;     // "pvp", "bridge", "ctf"
  state: string;        // "countdown", "in_progress", "finished"
  durationMs: number;   // Time elapsed since match start
}

interface Item {
  name: string;
  count: number;
  slot: number;
}

Tips

  • onTick runs every 500ms — keep it fast. Avoid blocking operations.
  • Use nearbyEnemies instead of filtering nearbyPlayers yourself — it already excludes teammates.
  • goto() is non-blocking. Check position on the next tick to see if you've arrived.