BlockWarriors/ docs
DashboardHome

Getting Started

Set up your development environment and run your first bot in under 10 minutes.

Prerequisites

  • Node.js 20+ — Download from nodejs.org
  • npm or pnpm — Comes with Node.js
  • A code editor — VS Code recommended
  • BlockWarriors account — Sign up at blockwarriors.ai
Step 1

Clone the starter bot

git clone https://github.com/project-blockwarriors/starter-bot.git
cd starter-bot
npm install
Step 2

Write your strategy

Open src/my-bot.ts and implement the Strategy interface. Here's a minimal PvP bot:

src/my-bot.ts
import { Strategy, BotAPI, GameState } from '@blockwarriors/sdk';

export const myStrategy: Strategy = {
  onSpawn(bot: BotAPI) {
    console.log('Bot spawned! Waiting for match to start...');
  },

  onTick(bot: BotAPI, state: GameState) {
    // Find the nearest enemy player
    const enemy = bot.nearbyEnemies[0];
    if (!enemy) return;

    const dist = bot.position.distanceTo(enemy.position);

    if (dist > 3) {
      // Move toward the enemy
      bot.goto(enemy.position.x, enemy.position.y, enemy.position.z);
    } else {
      // Close enough — attack!
      bot.attack();
    }
  },

  onDeath(bot: BotAPI) {
    console.log('Bot died!');
  },
};
Step 3

Get your match token

When a tournament match is created, each team member receives a unique token. Find yours on the Dashboard → My Matches page.

Step 4

Run your bot

npm start -- --host play.blockwarriors.ai --port 25565 --ign YourBotName --token YOUR_TOKEN

Your bot will connect to the server, authenticate with /login TOKEN, and wait for the match to start. Once all players are connected, the countdown begins automatically.

Running multiple bots (team games)

For 4v4 games like CTF, you need to run 4 bots. Use the team launcher:

npm run team -- --host play.blockwarriors.ai --port 25565 \
  --tokens TOKEN1,TOKEN2,TOKEN3,TOKEN4

What's next?