mineflayer Logo

mineflayer

创建 Minecraft 机器人的高级 JavaScript 框架

MineflayerMinecraft机器人APIJavaScriptGithub开源项目

Mineflayer 是一个功能全面的 JavaScript 框架,专为创建 Minecraft 机器人而设计。支持 Minecraft 1.8 至 1.20.4 版本,提供实体追踪、方块操作、物理模拟和库存管理等核心功能。开发者可通过 Mineflayer 实现自动化任务、聊天交互和复杂 AI 行为。该项目具有活跃的社区支持和丰富的插件生态,适用于多种 Minecraft 自动化场景。

Mineflayer

NPM版本 构建状态 在Gitpod上尝试 在Colab中打开 GitHub赞助商

官方Discord

使用强大、稳定且高级的JavaScript API创建Minecraft机器人,也可以在Python中使用。

第一次使用Node.js?你可能想从教程开始。了解Python?查看一些Python示例并尝试Google Colab上的Mineflayer

特性

  • 支持Minecraft 1.8至1.20.4版本(1.8、1.9、1.10、1.11、1.12、1.13、1.14、1.15、1.16、1.17、1.18、1.19和1.20)
  • 实体知识和跟踪
  • 方块知识。你可以查询周围的世界。毫秒级找到任何方块
  • 物理和移动 - 处理所有碰撞箱
  • 攻击实体和使用载具
  • 物品栏管理
  • 合成、箱子、发射器、附魔台
  • 挖掘和建造
  • 其他杂项,如了解你的生命值和是否下雨
  • 激活方块和使用物品
  • 聊天

路线图

查看此页面以了解我们当前的项目。

安装

首先从nodejs.org安装Node.js 18或更高版本,然后:

npm install mineflayer

要更新mineflayer(或任何Node.js包)及其依赖项,请使用

npm update --depth 9999

文档

链接描述
教程从Node.js和mineflayer开始
FAQ.md有问题?先看这里
api.md
unstable_api.md
完整的API参考
history.mdmineflayer的更新日志
examples/查看所有mineflayer示例

贡献

请阅读CONTRIBUTING.mdprismarine-contribute

使用

视频

解释机器人基本设置过程的教程视频可以在这里找到。

如果你想了解更多,更多视频教程在这里,这些机器人的相应源代码在这里

教程1 教程2 教程3 教程4

入门

如果未指定版本,将自动猜测服务器的版本。 如果未指定身份验证,将猜测为mojang身份验证样式。

Echo 示例

const mineflayer = require('mineflayer')

const bot = mineflayer.createBot({
  host: 'localhost', // Minecraft 服务器 IP
  username: 'Bot', // 如果 auth 为 'offline',则为加入时使用的用户名,否则为此账户的唯一标识符。如果想切换账户,请修改此项
  auth: 'microsoft' // 对于离线模式服务器,可以将此项设置为 'offline'
  // port: 25565,              // 如果需要使用非 25565 端口,请设置此项
  // version: false,           // 仅当需要特定版本或快照时才设置(如:"1.8.9" 或 "1.16.5"),否则将自动设置
  // password: '12345678'      // 如果想使用基于密码的认证,请设置此项(可能不稳定)。如果指定了密码,则 'username' 必须是一个电子邮件地址
})

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

// 记录错误和被踢出的原因:
bot.on('kicked', console.log)
bot.on('error', console.log)

如果 auth 设置为 microsoft,你将被提示在浏览器中使用代码登录 microsoft.com。在浏览器中登录后,机器人将自动获取并缓存认证令牌(使用你指定的用户名),这样你就不需要再次登录。

要切换账户,请更新提供的 username。默认情况下,缓存的令牌将存储在你用户的 .minecraft 文件夹中,或者如果指定了 profilesFolder,则会存储在那里。 有关机器人选项的更多信息,请参阅 node-minecraft-protocol 的 API 文档

连接到领域(Realm)

要加入你的 Minecraft 账户被邀请的领域,你可以传递一个带有选择器函数的 realms 对象,如下所示:

const client = mineflayer.createBot({
  username: 'email@example.com', // Minecraft 用户名
  realms: {
    // 此函数会收到一个账户可以加入的领域数组。它应该返回想要加入的那个。
    pickRealm: (realms) => realms[0]
  },
  auth: 'microsoft'
})

查看你的机器人在做什么

感谢 prismarine-viewer 项目,现在可以在浏览器窗口中显示你的机器人在做什么。 只需运行 npm install prismarine-viewer 并将以下代码添加到你的机器人中:

const { mineflayer: mineflayerViewer } = require('prismarine-viewer')
bot.once('spawn', () => {
  mineflayerViewer(bot, { port: 3007, firstPerson: true }) // port 是 Minecraft 服务器端口,如果 firstPerson 为 false,你将获得一个鸟瞰视角
})

然后你将得到一个看起来像这样的实时视图:

viewer

更多示例

示例描述
viewer在浏览器中显示你的机器人世界视图
pathfinder让你的机器人自动前往任何位置
chest使用箱子、熔炉、发射器、附魔台
digger学习如何创建一个能够挖掘方块的简单机器人
discord将 Discord 机器人与 Mineflayer 机器人连接
jumper学习如何移动、跳跃、乘坐载具、攻击附近实体
ansi在终端中显示你的机器人的聊天内容,包括所有聊天颜色
guard让机器人守卫一个特定区域,防御附近的怪物
multiple-from-file添加一个包含账户信息的文本文件,并让所有账户登录

examples 文件夹中还有更多示例。

模块

大量的活跃开发正在小型 npm 包中进行,这些包被 Mineflayer 使用。

Node 之道™

"当应用程序做得好时,它们只是那些真正特定于应用程序的、难以轻易抽象的残余部分。所有优秀的、可重用的组件都会升华到 GitHub 和 npm 上,让每个人都能协作推进公共资源。" — substack 摘自 "我如何编写模块"

模块

以下是构成 Mineflayer 的主要模块:

模块描述
minecraft-protocol解析和序列化 Minecraft 数据包,以及身份验证和加密。
minecraft-data为 Minecraft 客户端、服务器和库提供独立于语言的 Minecraft 数据。
prismarine-physics为 Minecraft 实体提供物理引擎。
prismarine-chunk用于保存 Minecraft 区块数据的类。
node-vec3具有可靠单元测试的 3D 向量数学库。
prismarine-block表示带有相关数据的 Minecraft 方块。
prismarine-chatMinecraft 聊天消息解析器(从 mineflayer 中提取)。
node-yggdrasil用于与 Mojang 的身份验证系统(称为 Yggdrasil)交互的 Node.js 库。
prismarine-worldPrismarine 世界的核心实现。
prismarine-windows表示 Minecraft 窗口。
prismarine-item表示带有相关数据的 Minecraft 物品。
prismarine-nbt用于 node-minecraft-protocol 的 NBT 解析器。
prismarine-recipe表示 Minecraft 配方。
prismarine-biome表示带有相关数据的 Minecraft 生物群系。
prismarine-entity表示 Minecraft 实体。

调试

您可以使用 DEBUG 环境变量启用一些协议调试输出:

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

在 Windows 上:

set DEBUG=minecraft-protocol
node your_script.js

第三方插件

Mineflayer 是可插拔的;任何人都可以创建在 Mineflayer 之上提供更高级 API 的插件。

最新和最有用的插件包括:

  • pathfinder - 具有许多可配置功能的高级 A* 寻路
  • prismarine-viewer - 简单的网页区块查看器
  • web-inventory - 基于网页的物品栏查看器
  • statemachine - 用于更复杂机器人行为的状态机 API
  • Armor Manager - 自动盔甲管理
  • Dashboard - Mineflayer 机器人的前端仪表板
  • PVP - 基本 PVP 和 PVE 的简易 API
  • Auto Eat - 自动食用食物
  • Auto Crystal - 自动放置和破坏末影水晶
  • Tool - 具有高级 API 的自动工具/武器选择实用程序
  • Hawkeye - 使用弓箭的自动瞄准实用程序
  • GUI - 使用 async/await 与嵌套的 GUI 窗口交互
  • Projectile - 获取投射物所需的发射角度
  • Movement - 流畅逼真的玩家移动,最适合 PvP
  • Collect Block - 快速简单的方块收集 API

另外还可以查看:

  • radar - 使用 canvas 和 socket.io 的基于网页的雷达界面。YouTube 演示
  • auto-auth - 基于聊天的机器人身份验证
  • Bloodhound - 确定谁和什么对另一个实体造成伤害
  • tps - 获取当前 tps(处理后的 tps)
  • panorama - 为您的世界拍摄全景图像
  • player-death-event - 在 Mineflayer 中触发玩家死亡事件

使用 Mineflayer 的项目

测试

测试所有内容

只需运行:

npm test

测试特定版本

运行

npm run mocha_test -- -g <版本>

其中<版本>是Minecraft版本,如1.121.15.2

测试特定测试

运行

npm run mocha_test -- -g <测试名称>

其中<测试名称>是测试的名称,如beduseChestsrayTrace

示例

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

运行1.18.1版本的方块查找器测试

许可证

MIT