@sectersion/rockbot

v0.1.0

Published

a month ago

Multi-bot orchestration for Minecraft Bedrock

0High
0Medium
0Low

sectersion

minecraft bedrock bot automation fleet multi-bot

🚀 About

rockbot turns bedrock-protocol's raw packet stream into a Mineflayer-style API — events, entity tracking, movement controls, chat — and then layers a Fleet primitive on top so you can spawn, manage, and coordinate N bots without managing N arrays of EventEmitters.

Mineflayer-style per-bot API — bot.chat(), bot.blockAt(), bot.pathfinder.goto(), bot.setControlState(), events, plugins
First-class fleet management — createFleet() with auth provider integration, named bots, event aggregation, sub-team groups
Automatic tick loop — PlayerAuthInput at 20hz keeps every bot alive regardless of what user code is doing
Entity tracking in real time — position, rotation, metadata for every player in view distance
Graceful shutdown — SIGINT/SIGTERM handled, clean disconnect on exit
Plugin system — Mineflayer-compatible plugin injection

⚡ Quickstart

Single bot

import { createBot } from 'rockbot'

const bot = createBot({
  host: 'play.lbsg.net',
  username: 'RockBot',
})

bot.on('spawn', () => {
  console.log(`${bot.username} spawned at ${bot.position}`)
  bot.chat('Hello from rockbot!')
})

bot.on('chat', (username, message) => {
  console.log(`<${username}> ${message}`)
})

Fleet of bots

import { createFleet } from 'rockbot'

const fleet = createFleet({
  defaults: { host: 'play.lbsg.net' },
  auth: { provider: 'file', source: './accounts.csv' },
})

fleet.on('spawn', (bot) => console.log(`${bot.username} joined`))
fleet.on('chat', (bot, user, msg) => console.log(`[${bot.name}] <${user}> ${msg}`))

await fleet.spawn(5)
fleet.broadcast('We come in peace.')

📦 Installation

npm install @sectersion/rockbot

Requires Node.js 18+.

📖 API Reference

createBot(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | host | string | '127.0.0.1' | Server address | | port | number | 19132 | Server port | | username | string | required | Bot name | | offline | boolean | false | Skip Xbox Live auth | | version | string | auto-detect | Protocol version | | viewDistance | number | 8 | Chunk radius | | connectTimeout | number | 9000 | Connection timeout (ms) | | plugins | PluginDeclaration[] | — | Mineflayer-style plugins |

Bot

const bot = createBot({ host: 'localhost', username: 'Bot1', offline: true })

| Method | Returns | Description | |--------|---------|-------------| | bot.chat(msg) | void | Send chat message | | bot.whisper(user, msg) | void | Send private message | | bot.look(yaw, pitch) | void | Set rotation | | bot.lookAt(point) | void | Look at a Vec3 position | | bot.setControlState(control, bool) | void | Set movement flag | | bot.clearControlStates() | void | Reset all movement flags | | bot.quit(reason?) | void | Disconnect cleanly | | bot.end(reason?) | void | Alias for quit |

Movement controls: forward, back, left, right, jump, sneak, sprint

| Property | Type | Description | |----------|------|-------------| | bot.username | string | Current username | | bot.entity | Entity | Self entity (id, position, rotation) | | bot.entities | Map<number, Entity> | All tracked entities | | bot.position | Vec3 | Current position | | bot.rotation | { yaw, pitch } | Current rotation | | bot.health | number | HP (0–20) | | bot.food | number | Hunger (0–20) | | bot.game | object | { dimension, difficulty, gameMode } |

| Event | Arguments | Description | |-------|-----------|-------------| | spawn | — | Bot fully joined the server | | login | — | Authenticated and connected | | chat | (username, message) | Chat message received | | whisper | (username, message) | Private message | | message | (text) | System message | | health | — | HP or food changed | | entitySpawn | (entity) | Entity entered view distance | | entityGone | (entity) | Entity left view distance | | kicked | (reason) | Bot was kicked | | error | (error) | Error occurred | | end | — | Connection closed | | respawn | — | Bot respawned after death | | game | — | Game data received |

createFleet(options)

| Option | Type | Description | |--------|------|-------------| | defaults | Partial<BotOptions> | Default options for every bot | | auth | AuthConfig | Credential provider | | plugins | PluginDeclaration[] | Fleet-level plugins |

Fleet

const fleet = createFleet({
  defaults: { host: 'play.lbsg.net' },
  auth: { provider: 'file', source: './accounts.csv' },
})

| Method | Returns | Description | |--------|---------|-------------| | fleet.spawn(n) | Promise<Bot[]> | Spawn N bots | | fleet.spawn(opts) | Promise<Bot> | Spawn one with per-bot options | | fleet.despawn(name) | — | Disconnect and remove a bot | | fleet.despawnAll() | — | Disconnect all bots | | fleet.bot(name) | Bot \| undefined | Get a bot by name | | fleet.broadcast(msg) | — | Chat from every bot | | fleet.group(names) | Group | Create a sub-team |

| Event | Arguments | Description | |-------|-----------|-------------| | spawn | (bot) | A bot joined | | chat | (bot, username, message) | Any bot heard chat | | kicked | (bot, reason) | A bot was kicked | | end | (bot) | A bot disconnected | | error | (bot, error) | A bot error |

Group

const miners = fleet.group(['miner-1', 'miner-2'])
miners.broadcast('Starting dig job!')
const results = await miners.call('chat', 'ready')

| Method | Description | |--------|-------------| | group.add(bot) | Add a bot | | group.remove(bot) | Remove a bot | | group.broadcast(msg) | Chat from all group members | | group.call(method, ...args) | Call a method on all bots in parallel | | group.on(event, fn) | Forward events from group bots |

🔐 Auth

File provider (CSV)

username,password,email
BotOne,pass123,[email protected]
BotTwo,pass456,[email protected]

createFleet({
  auth: { provider: 'file', source: './accounts.csv' },
})

Environment provider

createFleet({
  auth: { provider: 'env' },
})
// Reads: BOT_USERNAME, BOT_PASSWORD, BOT_EMAIL

Custom provider

import type { AuthProvider, Account } from 'rockbot'

class MyAuth implements AuthProvider {
  async acquire(): Promise<Account> {
    return { username: 'Bot', token: '...' }
  }
  async release(account: Account, reason?: string): Promise<void> {}
}

createFleet({
  auth: { provider: new MyAuth() },
})

🔌 Plugins

Plugins inject functionality into a bot at construction time — same pattern as Mineflayer.

function autoEat(bot: Bot, options?: any) {
  bot.on('health', () => {
    if (bot.food < 6) bot.chat('/eat')
  })
}

const bot = createBot({
  host: 'localhost',
  username: 'Bot',
  offline: true,
  plugins: [[autoEat, { threshold: 10 }]],
})

Fleet-level plugins are automatically applied to every spawned bot.

🏗 Architecture

┌────────────────────────────────────────────┐
│              rockbot                        │
│                                            │
│  Bot           Mineflayer-style per-bot API │
│  ├── events    spawn, chat, health, ...    │
│  ├── tick      PlayerAuthInput at 20hz     │
│  └── plugins   Plugin injection            │
│                                            │
│  Fleet         Multi-bot manager           │
│  ├── spawn()   Auth provider integration   │
│  ├── group()   Sub-team coordination       │
│  └── events    Aggregated from all bots    │
│                                            │
│  AuthProvider  Pluggable credential source  │
└────────────────┬───────────────────────────┘
                 │
┌────────────────▼───────────────────────────┐
│  bedrock-protocol                          │
│  (RakNet, Xbox Live, packet I/O)           │
└────────────────────────────────────────────┘

Dependencies

| Package | Role | |---------|------| | bedrock-protocol | RakNet networking, auth, packet I/O | | vec3 | 3D vector math | | minecraft-data | Block/item ID registry |

🛠 Development

git clone https://github.com/sectersion/rockbot
cd rockbot
npm install
npm run build

Test on a live server

npx tsx test/lifeboat.ts

The first run triggers a Microsoft device-code login flow — visit the printed URL, enter the code, and the bot connects.

📄 License

MIT