Minecraft

基于 mineflayer 的 MC 服务器聊天机器人适配器。连接离线 / 正版服务器，接收游戏内聊天并回复，附带建房 / 传送 / 丢包等指令。

适配器类型："minecraft"　源码：src/adapter/minecraft/ 协议：mineflayer（Minecraft 客户端协议实现）。

说明

特点

连接离线/正版 MC 服务器，以玩家身份进入游戏
接收游戏内聊天、系统消息、玩家加入/退出/死亡/成就等事件
支持发送聊天、建房、传送、丢包等指令
mineflayer 按需动态加载，未安装依赖时跳过该适配器，不影响其他平台

原理

接收：mineflayer 客户端连接服务器，监听 chat / message / playerJoined 等事件
发送：调用 bot.chat() 发送聊天消息，或调用 mineflayer API 执行游戏内操作

前提

可连接的 Minecraft 服务器地址和端口
离线服务器用 auth: "offline"，正版用 "microsoft" 或 "mojang"
游戏版本与服务器匹配（留空自动协商）

安装

适配器安装

bash

van adapter install minecraft

依赖库

bash

npm install mineflayer mineflayer-pathfinder vec3

配置

jsonc

{
  "botId": "MC",
  "type": "minecraft",
  "host": "mc.ziyi.asia",
  "port": 25565,
  "username": "VanBot",
  "auth": "offline",
  "version": "1.20.1",
  "ignoreSelf": true
}

配置项	必填	说明
`host`	✅	服务器地址
`port`	可选	服务器端口，默认 25565
`username`	可选	机器人游戏名，默认 "VanBot"
`auth`	可选	offline（离线）/ microsoft（正版）/ mojang，默认 offline
`version`	可选	游戏版本，留空自动协商
`ignoreSelf`	可选	忽略机器人自己发的消息，默认 true
`houseSize`	可选	建房大小，默认 5
`wallHeight`	可选	建房墙高，默认 3

接收事件

服务器事件	框架事件	说明
玩家聊天 `chat`	`private_message`	玩家在游戏内发言，`userId` = 玩家名
系统消息 `message`	`private_message`	死亡 / 成就 / 系统提示等
玩家加入 `playerJoined`	`notice`	玩家进入服务器
玩家退出 `playerLeft`	`notice`	玩家离开服务器
玩家死亡 `playerDied`	`notice`	玩家在游戏内死亡
进度/成就 `advancement`	`notice`	玩家达成进度或成就
机器人死亡 `death`	`notice`	机器人自身死亡
机器人重生 `respawn`	`notice`	机器人重生
生命值/饥饿值变化 `health`	`notice`	机器人血量或饥饿值变化

事件对象字段：

{
  botId: "MC",
  selfId: "VanBot",
  userId: "Steve",
  groupId: undefined,
  message: [{ type: "text", data: { text: "你好" } }],
  postType: "private_message" | "notice",
  raw: { player, msg, platform: "minecraft", notice_type, ... }
}

Minecraft 聊天是全局广播，统一按私聊事件派发。消息段仅 text（MC 聊天只有纯文本）。

API 调用

发送聊天

MC 聊天为全局广播，三种 action 等价：

await bot.callApi("send_msg", { message: "大家好，我是机器人" })
await bot.callApi("send_private_msg", { user_id: "Steve", message: "你好" })
await bot.callApi("send_group_msg", { group_id: "0", message: "你好" })

message 支持字符串或消息段数组，非文本段会转为占位文本。

游戏指令

await bot.callApi("house")          // 泥土小屋（默认 5x5、墙高 3）
await bot.callApi("houseWood")      // 橡木木板小屋
await bot.callApi("undo")           // 撤销拆除上一次建造的房子
await bot.callApi("tp", { player: "Steve" })   // 传送到指定玩家身边
await bot.callApi("dropAll")        // 丢弃背包全部物品
await bot.callApi("get_me")         // 返回 { botId, selfId, host, port, online }

常见问题

连不上服务器：检查 host / port / version 是否正确；离线服务器用 auth: "offline"，正版用 "microsoft"。
提示缺 mineflayer 依赖：执行 npm i mineflayer mineflayer-pathfinder vec3 后重启。
机器人建房失败：建房区域必须是空地，被方块挡住会提示"有方块挡住"。
机器人被踢出：控制台会打印踢出原因（kicked），常见于服务器封禁 / 同名冲突。
断线重连：与服务器断开后自动按 reconnectDelay（默认 5000ms）重连。

Minecraft ​

说明 ​

特点 ​

原理 ​

前提 ​

安装 ​

适配器安装 ​

依赖库 ​

配置 ​

接收事件 ​

API 调用 ​

发送聊天 ​

游戏指令 ​

常见问题 ​

相关项目 ​