Optimizing Mineflayer Bots - A Comprehensive Guide

Creating efficient and performant Minecraft bots with Mineflayer requires understanding various optimization strategies. This guide covers scaling multiple bots, configuration options, and performance best practices.

Scaling with Node.js Worker Threads

When running multiple Mineflayer bots, memory management becomes critical. Each bot must independently track the world state, which can quickly consume significant resources. Users have reported that running around 50 bots can consume approximately 5GB of RAM.

Implementation with Worker Threads

The recommended approach is using Node.js worker_threads for managing multiple bot instances:

Main Thread (main.js):

main.js

const { Worker } = require('worker_threads');
const path = require('path');

const bots = [];
const BOT_COUNT = 10;

for (let i = 0; i < BOT_COUNT; i++) {
  const worker = new Worker(path.join(__dirname, 'bot-worker.js'), {
    workerData: {
      username: `Bot_${i}`,
      host: 'localhost',
      port: 25565,
    }
  });

  worker.on('message', (msg) => {
    console.log(`Bot ${i}: ${msg}`);
  });

  worker.on('error', (err) => {
    console.error(`Bot ${i} error:`, err);
  });

  worker.on('exit', (code) => {
    if (code !== 0) {
      console.error(`Bot ${i} stopped with code ${code}`);
    }
  });

  bots.push(worker);
}

Worker Thread (bot-worker.js):

bot-worker.js

const { parentPort, workerData } = require('worker_threads');
const mineflayer = require('mineflayer');

const bot = mineflayer.createBot({
  host: workerData.host,
  port: workerData.port,
  username: workerData.username,
  physicsEnabled: false, // Disable if not needed
  checkTimeoutInterval: 60 * 1000,
});

bot.once('spawn', () => {
  parentPort.postMessage(`Spawned as ${bot.username}`);
});

bot.on('error', (err) => {
  parentPort.postMessage(`Error: ${err.message}`);
});

// Bot logic here

Performance Benefits

This worker thread approach provides:

Process isolation: Each bot runs in its own V8 isolate
Shared memory efficiency: Better than child processes
Error isolation: One bot crashing doesn't affect others
Resource monitoring: Track CPU/memory per worker

Performance Configuration Options

Mineflayer offers several configuration options to optimize performance:

bot-config.js

const bot = mineflayer.createBot({
  host: 'localhost',
  username: 'bot',

  // Disable physics if bot doesn't need collision detection
  physicsEnabled: false,

  // Adjust view distance (lower = less data to process)
  viewDistance: 'tiny', // Options: tiny, short, normal, far

  // Connection management
  checkTimeoutInterval: 60 * 1000, // Keepalive check (default: 30s)

  // Custom client for proxy support
  client: null, // Use custom minecraft-protocol client instance

  // Brand customization for servers requiring specific clients
  brand: 'vanilla',

  // Disable auto-respawn for manual control
  respawn: false,

  // Token storage location
  profilesFolder: './profiles',
})

Key Optimization Techniques

1. Disable Physics When Not Needed

If your bot doesn't need to walk or interact with the physical world:

disable-physics.js

bot.physicsEnabled = false;

2. Limit Entity Tracking

Reduce processing overhead by ignoring entities you don't care about:

limit-entity-tracking.js

bot.on('entitySpawn', (entity) => {
  // Only track specific entity types
  if (entity.type !== 'player') {
    return; // Ignore other entities
  }
});

3. Optimize Chunk Loading

Control which chunks the bot processes:

optimize-chunk-loading.js

// Reduce view distance
bot.settings.viewDistance = 2; // Minimum viable distance

// Unload distant chunks manually if needed
bot.on('chunkColumnLoad', (pos) => {
  const distance = Math.hypot(pos.x - bot.entity.position.x, pos.z - bot.entity.position.z);
  if (distance > 96) {
    bot.world.unloadColumn(pos.x, pos.z);
  }
});

4. Efficient Pathfinding

Use pathfinding wisely to avoid excessive CPU usage:

efficient-pathfinding.js

const { goals, Movements } = require('mineflayer-pathfinder');

const defaultMove = new Movements(bot);
// Reduce computational complexity
defaultMove.canDig = false; // Don't dig blocks
defaultMove.allowSprinting = false; // Simpler movement
defaultMove.allowParkour = false; // No parkour moves

bot.pathfinder.setMovements(defaultMove);

Optimization Recommendations

For optimal bot performance:

Disable physics if your bot doesn't need to move (physicsEnabled: false)
Set view distance to minimum required (use 'tiny' or custom value)
Limit entity tracking to only necessary entity types
Configure pathfinding movements to reduce computational complexity
Monitor memory usage regularly, especially when scaling multiple bots

Runtime Comparison: Node.js vs Bun

Node.js is the recommended runtime for Mineflayer bots:

Advantages:

Long-running optimization: Bots run for extended periods where Node.js V8 excels
Ecosystem maturity: Better library compatibility and community support
Production stability: LTS releases and battle-tested in production
Worker thread support: Excellent for scaling multiple bot instances
Memory management: Mature garbage collection for long-running processes

Best for:

Production deployments
Running multiple bots simultaneously
Long-term bot operations
Enterprise applications

For most Mineflayer use cases, stick with Node.js LTS versions.

Bun offers impressive startup times and I/O performance:

Advantages:

Fast startup: Quick iteration during development
Built-in utilities: Integrated test runner and bundler
TypeScript support: Native TypeScript execution
Modern APIs: Web-standard APIs built-in

When to consider Bun:

Development/testing with faster iteration cycles
Scripts that start and stop frequently
Simple I/O-bound automation tasks
TypeScript-heavy projects

Limitations for Mineflayer:

Less mature ecosystem compatibility
Fewer production use cases
May have edge cases with some Node.js-specific libraries

Essential Plugins

Anti-AFK Detection

For servers with AFK detection, use plugins like mineflayer-antiafk:

anti-afk-plugin.js

const antiafk = require('mineflayer-antiafk');
bot.loadPlugin(antiafk);

// Performs randomized actions: walking, looking, etc.

Authentication

For servers using AuthMe or requiring Microsoft accounts:

authentication.js

const bot = mineflayer.createBot({
  host: 'server.example.com',
  username: 'email@example.com',
  auth: 'microsoft', // or 'mojang'
});

Memory Management

Monitor and Clean Up:

memory-management.js

// Track memory per bot
function getMemoryUsage() {
  const usage = process.memoryUsage();
  return {
    rss: `${Math.round(usage.rss / 1024 / 1024)}MB`,
    heapUsed: `${Math.round(usage.heapUsed / 1024 / 1024)}MB`,
  };
}

// Clean shutdown
function shutdownBot(bot) {
  bot.removeAllListeners(); // Prevent memory leaks
  bot.quit();
  bot._client.end(); // Close socket
}

// Periodic cleanup
setInterval(() => {
  if (global.gc) {
    global.gc(); // Run with --expose-gc flag
  }
}, 5 * 60 * 1000); // Every 5 minutes

Run with memory limits:

Terminal

node --max-old-space-size=4096 --expose-gc bot.js

Error Handling and Reconnection

Robust error handling is essential:

error-handling.js

function createBot(config) {
  const bot = mineflayer.createBot(config);

  bot.on('error', (err) => {
    console.error('Bot error:', err);
  });

  bot.on('kicked', (reason) => {
    console.log('Kicked:', reason);
    setTimeout(() => createBot(config), 5000);
  });

  bot.on('end', () => {
    console.log('Connection lost, reconnecting...');
    setTimeout(() => createBot(config), 5000);
  });

  return bot;
}

Production Best Practices

Production Deployment Tips

Gradual Scaling: Start with 5-10 bots, monitor resource usage, then scale
Resource Monitoring: Track CPU, memory, and network per bot
Logging: Use structured logging (winston, pino) for debugging
Process Management: Use PM2 for automatic restarts and monitoring
Rate Limiting: Stagger bot logins to avoid overwhelming servers

Example PM2 config:

ecosystem.config.js

module.exports = {
  apps: [{
    name: 'bot-fleet',
    script: './main.js',
    instances: 1,
    max_memory_restart: '2G',
    env: {
      NODE_ENV: 'production'
    }
  }]
}

Conclusion

Optimizing Mineflayer bots requires:

Worker threads for scaling multiple instances
Configuration tuning based on your bot's needs (physics, view distance)
Memory management with proper cleanup and monitoring
Robust error handling for production reliability

Key takeaways:

Use Node.js worker threads for multiple bot instances
Disable physics and reduce view distance when possible
Implement proper error handling and reconnection logic
Monitor resources and scale gradually
Start with Node.js LTS for production deployments

By following these strategies, you can create efficient, reliable Minecraft bots that scale to your needs.