mineflayer-mcefly

mineflayer-mcefly is an advanced Elytra flight controller plugin for Mineflayer bots.
It enables autonomous long-distance Elytra flight with terrain scanning, firework boosting, water avoidance, automatic elytra replacement, and precision landing.

This plugin is designed for survival servers and handles takeoff, navigation, and landing automatically with enhanced safety features.

Features

Flight System

• Automatic Elytra equip
• Auto-equip spare Elytra when broken ✨ NEW
• Automatic takeoff
• Firework-assisted flight
• Speed limiting and smoothing
• Precision landing system
• Emergency landing handling
• Configurable flight timeout for ultra-long distances ✨ NEW

Navigation & Safety

• Terrain scanning ahead of the bot
• Dynamic flight height adjustment
• Obstacle and mountain avoidance
• Advanced water detection and avoidance system ✨ NEW
• Smart landing spot selection (avoids water) ✨ NEW
• Extended safe landing search (50m radius) ✨ NEW
• Safe landing spot selection
• Elytra durability monitoring with auto-replacement
• Firework availability monitoring

Developer Friendly

• Simple API
• Runtime configuration
• Detailed flight status
• Event-based system
• Works as a Mineflayer plugin

Requirements

• Node.js 16+
• Mineflayer 4.x or newer
• Minecraft 1.16+
• Elytra in inventory (auto-equipped)
• Firework rockets (recommended)
• Multiple Elytra recommended for long flights ✨ NEW

Installation

npm install mineflayer-mcefly

Loading the Plugin

const mineflayer = require('mineflayer')
const mcefly = require('mineflayer-mcefly')

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

bot.loadPlugin(mcefly)

After loading, the API is available at:

bot.mcefly

Basic Usage

const { Vec3 } = require('vec3')

bot.once('spawn', async () => {
  console.log('Bot spawned')

  // Fly to a location
  await bot.mcefly.goto(new Vec3(100, 80, 100))

  console.log('Arrived at destination')
})

Advanced Usage with Custom Configuration

const mineflayer = require('mineflayer')
const mcefly = require('mineflayer-mcefly')

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

// Load plugin with custom configuration
bot.loadPlugin(mcefly)

// Configure for ultra-long distance flights
bot.mcefly.setConfig({
  flightTimeout: 36600000, // 10+ hours for extremely long flights
  navigationSpeed: 0.08,
  waterLandingAvoidance: true, // Avoid water landings (enabled by default)
  autoEquipElytra: true, // Auto-equip spare elytra (enabled by default)
  quiet: false // Show detailed flight logs
})

bot.once('spawn', async () => {
  try {
    // Fly thousands of blocks away
    await bot.mcefly.goto(new Vec3(50000, 80, 50000))
    console.log('Long journey complete!')
  } catch (err) {
    console.error('Flight failed:', err.message)
  }
})

// Listen to new events
bot.on('mcefly_water_avoidance', (data) => {
  console.log(`Water detected! Redirecting from ${data.original} to ${data.new}`)
})

bot.on('mcefly_elytra_auto_equipped', (data) => {
  console.log(`Elytra broke! Auto-equipped spare. ${data.remaining} remaining.`)
})

bot.on('mcefly_elytra_critical_warning', (data) => {
  console.log('CRITICAL: No spare elytra available!')
})

API Reference

bot.mcefly.start()

Starts Elytra flight.

await bot.mcefly.start()

• Equips Elytra if needed
• Checks for broken elytra state ✨ NEW
• Performs takeoff
• Begins safety monitoring

Throws: Error if elytra is broken and no spare is available

bot.mcefly.goto(destination)

Flies to a destination and lands automatically.

await bot.mcefly.goto(new Vec3(200, 90, -50))

• Pre-checks destination for water and finds safe landing ✨ NEW
• Handles takeoff if not already flying
• Avoids terrain and water
• Uses fireworks when needed
• Re-checks landing spot for water during approach ✨ NEW
• Lands precisely near the target

Returns a Promise that resolves when landing is complete.

bot.mcefly.stop()

Requests a safe landing.

await bot.mcefly.stop()

• Cancels navigation
• Performs controlled descent
• Lands safely

bot.mcefly.kill()

Emergency stop.

bot.mcefly.kill()

• Immediately stops all flight logic
• Clears control states
• Emits a killed event

bot.mcefly.getStatus()

Returns detailed flight status.

const status = bot.mcefly.getStatus()
console.log(status)

Includes:

• Flying / landing / takeoff state
• Elytra broken state ✨ NEW
• Elytra count in inventory ✨ NEW
• Original destination (before water avoidance) ✨ NEW
• Current position & velocity
• Current speed
• Destination
• Distance to destination
• Fireworks used & remaining
• Terrain type
• Current & target flight height
• Obstacle detection state

bot.mcefly.getElytraCount() ✨ NEW

Returns the number of elytra in the bot's inventory.

const elytraCount = bot.mcefly.getElytraCount()
console.log(`Elytra available: ${elytraCount}`)

bot.mcefly.setConfig(config)

Update configuration at runtime.

bot.mcefly.setConfig({
  navigationSpeed: 0.08,
  maxSpeed: 2.0,
  minFlightHeight: 30,
  flightTimeout: 36600000, // 10+ hours
  waterLandingAvoidance: true,
  autoEquipElytra: true,
  quiet: true
})

Configuration Options

| Option | Default | Description | |--------|---------|-------------| | navigationSpeed | 0.06 | Forward flight speed | | maxSpeed | 1.5 | Maximum allowed velocity | | velocityUp | 0.15 | Upward flight force | | velocityDown | 0.08 | Downward flight force | | minFlightHeight | 25 | Minimum height above ground | | clearanceHeight | 130 | Height added above obstacles | | fireworkCooldown | 2000 | Delay between fireworks (ms) | | terrainScanDistance | 40 | Distance to scan terrain | | terrainScanInterval | 1500 | How often terrain is scanned (ms) | | landingPrecision | 0.5 | How accurate landing must be | | quiet | false | Disable console logs | | elytraCheck | true | Enable Elytra safety checks | | flightTimeout ✨ NEW | 600000 | Flight timeout in ms (10 min default) | | waterLandingAvoidance ✨ NEW | true | Avoid landing in water | | autoEquipElytra ✨ NEW | true | Auto-equip spare elytra when broken |

Recommended Timeout Values

// Short flights (< 1000 blocks)
flightTimeout: 300000  // 5 minutes

// Medium flights (1000-5000 blocks) 
flightTimeout: 600000  // 10 minutes (default)

// Long flights (5000-20000 blocks)
flightTimeout: 1800000  // 30 minutes

// Ultra-long flights (20000+ blocks)
flightTimeout: 36600000  // 10+ hours

Events

The plugin emits events on the bot instance.

bot.on('mcefly_start', () => {})
bot.on('mcefly_takeoff_complete', data => {})
bot.on('mcefly_goto_start', dest => {})
bot.on('mcefly_landing_approach', () => {})
bot.on('mcefly_landing_start', () => {})
bot.on('mcefly_landed', stats => {})
bot.on('mcefly_elytra_warning', () => {})
bot.on('mcefly_firework_warning', data => {})
bot.on('mcefly_elytra_broken', () => {})
bot.on('mcefly_killed', () => {})

// NEW EVENTS ✨
bot.on('mcefly_elytra_auto_equipped', data => {
  // data = { remaining: number }
  console.log(`Spare elytra equipped. ${data.remaining} remaining.`)
})

bot.on('mcefly_elytra_critical_warning', data => {
  // data = { message: string }
  console.log('CRITICAL: No spare elytra available!')
})

bot.on('mcefly_water_avoidance', data => {
  // data = { original: Vec3, new: Vec3 }
  console.log(`Water avoided. Redirecting from ${data.original} to ${data.new}`)
})

Enhanced Safety Behavior ✨

Auto-Equip Broken Elytra

• Automatically detects when elytra breaks during flight
• Equips spare elytra from inventory instantly
• Shows console warnings with remaining elytra count
• Prevents flight startup if elytra is broken with no spares
• Emits events for monitoring

🔧 Elytra broken! Equipping spare elytra... (2 available)
✓ Spare elytra equipped successfully

Water Landing Avoidance

• Pre-checks destination for water before takeoff
• Scans for water during landing approach
• Extended search radius (50m) to find safe ground
• Automatically redirects to nearest safe landing spot
• Shows distance to safe spot in console

⚠️ Destination is water! Finding safe landing spot...
✓ Safe landing spot found 12.3m from original destination

Other Safety Features

• Stops flight if Elytra breaks (with no spare)
• Warns if fireworks run out
• Searches for safe nearby landing spots
• Automatically boosts when losing altitude or speed

Console Output Examples

Successful Long-Distance Flight

[FlyBot][mcefly] Flying to destination (45230m away)
⚠️ Destination is water! Finding safe landing spot...
✓ Safe landing spot found 8.7m from original destination
[FlyBot][mcefly] Landed (45230m traveled, 8.7m accuracy)

Elytra Replacement During Flight

[FlyBot][mcefly] Flying to destination (12500m away)
🔧 Elytra broken! Equipping spare elytra... (3 available)
✓ Spare elytra equipped successfully
[FlyBot][mcefly] Landed (12500m traveled, 1.2m accuracy)

Critical Warning - No Spare Elytra

[FlyBot][mcefly] Flying to destination (8000m away)
⚠️ CRITICAL WARNING: Elytra broken and no spare elytra in inventory!

Notes

• Designed for survival gameplay
• Not intended for creative flight
• Best used on open terrain and long distances
• Fireworks are required for long-range travel
• Multiple elytra recommended for ultra-long journeys ✨ NEW
• Default timeout (10 Hours) suitable for most flights ✨ NEW
• Increase timeout for 20,000+ block journeys ✨ NEW

Troubleshooting

Flight times out

Increase the flightTimeout configuration:

bot.mcefly.setConfig({ flightTimeout: 36600000 }) // 10+ hours

Bot lands in water

Ensure waterLandingAvoidance is enabled (it is by default):

bot.mcefly.setConfig({ waterLandingAvoidance: true })

Elytra breaks and bot falls

• Ensure you have spare elytra in inventory
• Check that autoEquipElytra is enabled (it is by default)
• Listen to mcefly_elytra_critical_warning event to get notified

TODO

• Improve logging
• Add support for custom landing strategies
• Implement path replay system

License

MIT License