/mineflayer

Create Minecraft bots with a powerful, stable, and high level JavaScript API.

Primary LanguageJavaScriptMIT LicenseMIT

Mineflayer

NPM version Build Status Discord Gitter Irc

Try it on gitpod

US English RU Russian ES Spanish

Create Minecraft bots with a powerful, stable, and high level JavaScript API.

First time using node.js ? You may want to start with the tutorial

Features

  • Supports Minecraft 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15 and 1.16.
  • Entity knowledge and tracking.
  • Block knowledge. You can query the world around you. Milliseconds to find any block.
  • Physics and movement - handle all bounding boxes
  • Attacking entities and using vehicles.
  • Inventory management.
  • Crafting, chests, dispensers, enchantment tables.
  • Digging and building.
  • Miscellaneous stuff such as knowing your health and whether it is raining.
  • Activating blocks and using items.
  • Chat.

Roadmap

Checkout this page to see what are your current projects.

Installation

npm install mineflayer

Documentation

link description
tutorial Begin with node.js and mineflayer
FAQ.md Got a question ? go there first
api.md unstable_api.md The full API reference
history.md The changelog for mineflayer
examples/ Checkout all the mineflayer examples

Contribute

Please read CONTRIBUTING.md and prismarine-contribute

Usage

Video

A tutorial video explaining the basic set up process for a bot can be found here.

Getting Started

Without version specified, the version of the server will be guessed automatically, you can set a specific one using the version option. For example version:"1.8".

Echo Example

const mineflayer = require('mineflayer')

const bot = mineflayer.createBot({
  host: 'localhost', // optional
  port: 25565,       // optional
  username: 'email@example.com', // email and password are required only for
  password: '12345678',          // online-mode=true servers
  version: false                 // false corresponds to auto version detection (that's the default), put for example "1.8.8" if you need a specific version
})

bot.on('chat', function (username, message) {
  if (username === bot.username) return
  bot.chat(message)
})

// Log errors and kick reasons:
bot.on('kicked', (reason, loggedIn) => console.log(reason, loggedIn))
bot.on('error', err => console.log(err))

More Examples

example description
viewer display your bot world view in the browser
pathfinder make your bot go to any location automatically
chest Use chests, furnaces, dispensers, enchantment tables
digger Learn how to create a simple bot that is capable of digging the block
discord connect a discord bot with a mineflayer bot
jumper Learn how to move, jump, ride vehicles, attack nearby entities

And many mores in the examples folder

Modules

A lot of the active development is happening inside of small npm packages which are used by mineflayer.

The Node Way™

"When applications are done well, they are just the really application-specific, brackish residue that can't be so easily abstracted away. All the nice, reusable components sublimate away onto github and npm where everybody can collaborate to advance the commons." — substack from "how I write modules"

Modules

These are the main modules that make up mineflayer:

module description
minecraft-protocol Parse and serialize minecraft packets, plus authentication and encryption.
minecraft-data Language independent module providing minecraft data for minecraft clients, servers and libraries.
prismarine-physics Provide the physics engine for minecraft entities
prismarine-chunk A class to hold chunk data for Minecraft
node-vec3 3d vector math with robust unit tests
prismarine-block Represent a minecraft block with its associated data
prismarine-chat A parser for a minecraft chat message (extracted from mineflayer)
node-yggdrasil Node.js library to interact with Mojang's authentication system, known as Yggdrasil
prismarine-world The core implementation of worlds for prismarine
prismarine-windows Represent minecraft windows
prismarine-item Represent a minecraft item with its associated data
prismarine-nbt An NBT parser for node-minecraft-protocol
prismarine-recipe Represent minecraft recipes
prismarine-biome Represent a minecraft biome with its associated data
prismarine-entity Represent a minecraft entity

Debug

You can enable some protocol debugging output using DEBUG environment variable:

DEBUG="minecraft-protocol" node [...]

On windows :

set DEBUG=minecraft-protocol
node your_script.js

Third Party Plugins

Mineflayer is pluggable; anyone can create a plugin that adds an even higher level API on top of Mineflayer.

The most updated and useful are :

But also check out :

  • navigate - get around easily using A* pathfinding. YouTube Demo
  • radar - web based radar interface using canvas and socket.io. YouTube Demo
  • blockfinder - find blocks in the 3D world
  • scaffold - get to a target destination even if you have to build or break blocks to do so. YouTube Demo
  • auto-auth - chat-based bot authentication
  • Bloodhound - determine who and what is responsible for damage to another entity
  • tps - get the current tps (processed tps)

Projects Using Mineflayer

Testing

Some setup is required after first cloning the project but after that is done it's very easy to run them.

Setup

In order to get all tests to run successfully you must first:

  1. create a new folder in which to store minecraft server jars
  2. set the MC_SERVER_JAR_DIR to this folder

Example:

  1. mkdir server_jars
  2. export MC_SERVER_JAR_DIR=/full/path/to/server_jars

Where the "/full/path/to/" is the fully qualified path name.

Testing everything

Simply run: npm test

Testing specific version

Run npm test -g <version>, where <version> is a minecraft version like 1.12, 1.15.2...

Testing specific test

Run npm test -g <test_name>, where <test_name> is a name of the test like bed, useChests, rayTrace...

Licence

MIT