Mineflayer

🤖 Mineflayer#

Minecraft bot protocol client — the foundation all Moincraft agents are built on.

Essential Plugins#

Plugin	Purpose	Install
`mineflayer-pathfinder`	Mandatory. A* navigation	`npm i mineflayer-pathfinder`
`mineflayer-statemachine`	Complex AI behavior trees	`npm i mineflayer-statemachine`
`mineflayer-pvp`	Combat logic & timing	`npm i mineflayer-pvp`
`mineflayer-auto-eat`	Survival hygiene	`npm i mineflayer-auto-eat`
`mineflayer-collectblock`	Smart block collection	`npm i mineflayer-collectblock`
`mineflayer-armor-manager`	Auto equip best armor	`npm i mineflayer-armor-manager`
`minecraft-data`	Block/item/entity data per version	`npm i mineflayer` (included)
`prismarine-item`	Item parsing + crafting	`npm i prismarine-item`
`vec3`	3D vector math	`npm i vec3`

Basic Bot Template (Headless Optimized)#

const mineflayer = require('mineflayer')

const bot = mineflayer.createBot({
  host: 'localhost',
  username: 'Bot_1',
  viewDistance: 'tiny',    // ⚡ CRITICAL for swarm performance
  physicsEnabled: true     // Set false if just chatting
})

bot.on('kicked', console.log)
bot.on('error', console.log)

Pathfinding#

const { pathfinder, Movements, goals } = require('mineflayer-pathfinder')
const { GoalNear, GoalBlock, GoalFollow, GoalXZ } = goals

bot.loadPlugin(pathfinder)

function comeToMe(username) {
  const target = bot.players[username]?.entity
  if (!target) return

  const mcData = require('minecraft-data')(bot.version)
  const defaultMove = new Movements(bot, mcData)
  defaultMove.allowParkour = true
  defaultMove.canDig = true
  defaultMove.allowSprinting = true

  bot.pathfinder.setMovements(defaultMove)
  bot.pathfinder.setGoal(
    new GoalNear(target.position.x, target.position.y, target.position.z, 1)
  )
}

// Cancel navigation
bot.pathfinder.stop()

// Check if moving
bot.pathfinder.isMoving()

Custom Movement Tuning#

const defaultMove = new Movements(bot)
defaultMove.blocksCantBreak.add(bot.registry.blocksByName['chest'].id)
defaultMove.blocksToAvoid.add(bot.registry.blocksByName['lava'].id)
defaultMove.liquidCost = 3      // penalty for water
defaultMove.maxDropDown = 4     // max fall height

State Machine (Behavior Trees)#

Don’t write if/else hell — use states:

const { BotStateMachine, StateTransition } = require('mineflayer-statemachine')

const idleState = new BehaviorIdle(bot)
const followState = new BehaviorFollowEntity(bot, playerEntity)

const transitions = [
  new StateTransition({
    parent: idleState,
    child: followState,
    shouldTransition: () => playerEntity !== null
  })
]

const root = new NestedStateMachine(transitions, idleState)
const stateMachine = new BotStateMachine(bot, root)

PvP#

const pvp = require('mineflayer-pvp').plugin
bot.loadPlugin(pvp)
bot.pvp.attack(targetEntity)  // Handles crits, shields, timing automatically

Performance Tips for Swarms#

Disable physics for idle bots: bot.physicsEnabled = false
Disable chat patterns — bot.chatAddPattern regexes are expensive
Separate processes — NEVER run 10 bots in one Node process. Use child_process.fork(). Node is single-threaded; one heavy pathfinding calc freezes ALL bots.
Limit listeners — don’t add bot.on('chat', ...) inside loops (memory leak)
Tiny view distance — viewDistance: "tiny" for non-explorer bots