| 🇺🇸 English | 🇷🇺 Russian | 🇪🇸 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
- 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.
Checkout this page to see what are our current projects.
First install nodejs >= 14 from nodejs.org then:
npm install mineflayer
| 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 |
Please read CONTRIBUTING.md and prismarine-contribute
Videos
A tutorial video explaining the basic set up process for a bot can be found here.
If you want to learn more, more video tutorials are there, and the corresponding source codes for those bots is there.
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".
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
auth: 'mojang' // optional; by default uses mojang, if using a microsoft account, set to 'microsoft'
})
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))Thanks to prismarine-viewer project, it's possible to display in a browser window what your bot is doing.
Just run npm install prismarine-viewer and add this to your bot:
const mineflayerViewer = require('prismarine-viewer').mineflayer
bot.once('spawn', () => {
mineflayerViewer(bot, { port: 3007, firstPerson: true })
})And you'll get a live view looking like this:
| 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
A lot of the active development is happening inside of small npm packages which are used by mineflayer.
"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"
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 |
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
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 :
- pathfinder - advanced A* pathfinding with a lot of configurable features
- prismarine-viewer - simple web chunk viewer
- web-inventory - web based inventory viewer
- statemachine - A state machine API for more complex bot behavors
- Armor Manager - automatic armor managment
- Collect Block - Quick and simple block collection API.
- Dashboard - Frontend dashboard for mineflayer bot
- PVP - Easy API for basic PVP and PVE.
- auto-eat - Automatic eating of food.
- Tool - A utility for automatic tool/weapon selection with a high level API.
- Hawkeye - A utility for using auto-aim with bows.
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)
- rom1504/rbot
- Darthfett/Helperbot
- vogonistic/voxel - visualize what the bot is up to using voxel.js
- JonnyD/Skynet - log player activity onto an online API
- MinecraftChat (last open source version, built by AlexKvazos) - Minecraft web based chat client https://minecraftchat.net/
- Cheese Bot - Plugin based bot with a clean GUI. Made with Node-Webkit. http://bot.ezcha.net/
- Chaoscraft - Minecraft bot using genetic algorithms, see its youtube videos
- hexatester/minetelegram - Minecraft - Telegram bridge, build on top of mineflayer & telegraf.
- ProZedd/mineflayer-printer - Prints minecraft schematics
- and hundreds more - All the projects that github detected are using mineflayer
Some setup is required after first cloning the project but after that is done it's very easy to run them.
In order to get all tests to run successfully you must first:
- create a new folder in which to store minecraft server jars
- set the MC_SERVER_JAR_DIR to this folder
Example:
mkdir server_jarsexport MC_SERVER_JAR_DIR=/full/path/to/server_jars
Where the "/full/path/to/" is the fully qualified path name.
Simply run: npm test
Run npm test -- -g <version>, where <version> is a minecraft version like 1.12, 1.15.2...
Run npm test -- -g <test_name>, where <test_name> is a name of the test like bed, useChests, rayTrace...