mineflayer

The table of contents in docs/api.md is automatically generated using doctoc. If you modify the API documentation, you must run the following command to refresh the table of contents:

doctoc docs/api.md

To create a bot, require the mineflayer module and call mineflayer.createBot(). By default, it attempts to connect to localhost on port 25565.

To specify a different server, pass an options object containing host and port.

const mineflayer = require('mineflayer')

const options = {
  host: 'localhost',
  port: 25565
}

const bot = mineflayer.createBot(options)

To avoid hardcoding sensitive information like passwords, you can use process.argv to pass configuration via the command line.

Example usage: node filename.js <host> <port> <username> <password>

const bot = mineflayer.createBot({
  host: process.argv[2],
  port: parseInt(process.argv[3]),
  username: process.argv[4],
  password: process.argv[5]
})

Item lore is stored in the item.nbt property. It is recommended to use the prismarine-nbt library to simplify the NBT data and prismarine-chat to convert the lore lines into readable strings.

function getLore (item) {
  let message = ''
  if (item.nbt == null) return message

  const nbt = require('prismarine-nbt')
  const ChatMessage = require('prismarine-chat')(bot.version)

  const data = nbt.simplify(item.nbt)
  const display = data.display
  if (display == null) return message

  const lore = display.Lore
  if (lore == null) return message
  for (const line of lore) {
    message += new ChatMessage(line).toString()
    message += '\n'
  }

  return message
}

External tests are located in test/externalTests/ and are run against a vanilla Minecraft server.

To create one, add a new file to test/externalTests/. The file must export a function that returns either a single function or an array of functions. Each function receives the bot object and a done callback as parameters. You should include assertions within these functions to verify the tested functionality.

Mineflayer supports plugins that add high-level APIs to the bot. To create a plugin, follow these steps:

1. Create a new repository.
2. In your index.js, export a function that initializes the plugin, accepting Mineflayer as an argument.
3. This initialization function must return a function that introduces the plugin to the bot object.
4. Inside that returned function, you can add new functionalities to the bot.

Important: Because the Mineflayer object is passed as an argument, your plugin should not depend on the mineflayer package directly (do not include mineflayer in your package.json dependencies).

You can run the test suite using npm commands. You can test the entire project, a specific Minecraft version, or a specific test case using the mocha_test script.

Test everything

Run all tests in the repository:

npm test

Test a specific Minecraft version

Use the -g flag followed by the version string (e.g., 1.12, 1.15.2):

npm run mocha_test -- -g <version>

Test a specific test name

Use the -g flag followed by the name of the test (e.g., bed, useChests, rayTrace):

npm run mocha_test -- -g <test_name>

Example: Test a specific feature for a specific version

To run the block finder test specifically for version 1.18.1:

npm run mocha_test -- -g "1.18.1.*BlockFinder"