A high-level API over bedrock-protocol, styled after Mineflayer — designed for one bot or a hundred.

---

Table of Contents

• About
• Quickstart
• Installation
• API Reference
  • createBot
  • Bot
  • createFleet
  • Fleet
  • Group
• Auth
• Plugins
• Architecture
• Development
• License

---

🚀 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,bot1@example.com
BotTwo,pass456,bot2@example.com

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

_{Built on the PrismarineJS ecosystem. Inspired by Mineflayer.}