Renge Bot

Renge Bot 是一个面向 Minecraft 1.20.1 Forge 整合服的半自主游戏 Agent。

它使用 Mineflayer 登录服务器并执行玩家动作，通过 MCP、游戏聊天、HTTP API 或 CLI 接收指令；由于大型 Forge 整合服的方块注册表无法被 Mineflayer 完整解析，项目还包含一个只安装在服务端的 Forge World Bridge，用于提供可靠的方块、实体和寻路信息。

Bot 不负责启动 Minecraft 服务器。请先确保服务器已经运行，再单独启动 Bot。

功能

• Forge 1.20.1 FML3 登录兼容

• MCP stdio 服务，可供支持 MCP 的 Agent 调用

• 本地 HTTP API 与 CLI（不会创建第二个 Bot）

• 游戏内中文聊天指令与玩家白名单

• 自动重连与 RCON 自动恢复

• 聊天日志保存为 JSONL

• PANIC / CORE / WORK / REST / IDLE 行为优先级

• 通过服务端真实碰撞信息规划行走、跳跃、下落、开门、攀爬和游泳路线

• 远距离或跨维度时使用 RCON 传送，近距离优先正常行走

• 低血量、着火或落入熔岩时自动脱困

已注册任务：

Related MCP server: Minecraft MCP Server

架构

玩家 / MCP Agent / CLI
          │
          ▼
  Renge Bot（Node.js）
  ├─ MCP stdio
  ├─ HTTP API 127.0.0.1:21083
  ├─ 行为引擎与任务系统
  ├─ Mineflayer：登录、聊天、实体与物品交互
  └─ RCON：远距离/跨维传送与受控辅助
          │
          ▼
Forge World Bridge 127.0.0.1:21084
  ├─ 方块与实体查询
  └─ 服务端权威寻路
          │
          ▼
Minecraft Forge 1.20.1 服务端

World Bridge 是只读感知桥：不注册方块或实体，不写入存档，也不要求普通玩家客户端安装。

环境要求

• Node.js 18 或更高版本

• Java 17（仅构建 Forge Bridge 时需要）

• Minecraft 1.20.1

• Forge 47.3.33 或兼容的更高 47.x 版本

• 服务端已开启 RCON

• 服务端已安装 renge-world-bridge-1.0.0.jar

本项目当前默认使用：

• Minecraft：127.0.0.1:21082

• Bot HTTP API：127.0.0.1:21083

• World Bridge：127.0.0.1:21084

• RCON：127.0.0.1:25575

• 安全点：-804 227 -2960

安装

在项目根目录执行：

npm install
Copy-Item .env.example .env

编辑 .env：

MC_HOST=127.0.0.1
MC_PORT=21082
MC_USERNAME=Renge

RCON_HOST=127.0.0.1
RCON_PORT=25575
RCON_PASSWORD=填写服务端的RCON密码

HTTP_PORT=21083

DEFAULT_CONTROLLER_PLAYER=QDcvd
ALLOWED_PLAYERS=QDcvd,Squama_

WORLD_BRIDGE_URL=http://127.0.0.1:21084
WORLD_BRIDGE_TOKEN_FILE=G:\游戏分区\香草纪元\【⭐服务端⭐】(开服用，若不清楚请下载客户端\config\renge_world_bridge.token
WORLD_BRIDGE_TIMEOUT_MS=2500

也可以使用 WORLD_BRIDGE_TOKEN 直接提供令牌；若两者都填写，代码会优先使用显式令牌。

构建与部署 World Bridge

进入 Forge 子项目并构建：

cd forge-bridge
.\gradlew.bat clean build

构建产物：

forge-bridge/build/libs/renge-world-bridge-1.0.0.jar

部署步骤：

1. 停止 Minecraft 服务端。

2. 将 Jar 复制到服务端 mods 目录。

3. 启动服务端。

4. 确认生成 config/renge_world_bridge.token。

5. 将该令牌文件路径写入 Bot 的 .env。

Bridge 仅监听回环地址，并要求 Bearer Token。它通过 displayTest="IGNORE_ALL_VERSION" 声明服务端兼容性，因此玩家客户端不需要安装该 Mod。

启动

先启动 Minecraft 服务端，确认端口 21082、RCON 和 World Bridge 可用，然后在项目根目录运行：

npm start

该命令只启动一个 Bot 进程。这个进程同时承载：

• Mineflayer Bot

• MCP stdio 服务

• 本地 HTTP API

• 行为引擎

不要为了使用 CLI 再启动一份 bot.js；CLI 会通过 HTTP 控制已经运行的 Bot。

Bot 的 stdout 专门保留给 MCP 协议，运行日志写入 stderr。若由 MCP 客户端拉起进程，命令应直接指向：

node G:\游戏分区\香草纪元\botFormc\bot.js

CLI 用法

node cli.js status
node cli.js chat 大家好
node cli.js tasks
node cli.js task QDcvd follow
node cli.js task QDcvd farm
node cli.js task QDcvd patrol
node cli.js stop
node cli.js tp-player QDcvd
node cli.js tp-home
node cli.js messages 50
node cli.js autonomy true
node cli.js autonomy false

task 命令也可传入 JSON 选项：

node cli.js task QDcvd follow '{"distance":3}'

MCP 工具

MCP 客户端配置示例：

{
  "mcpServers": {
    "renge-bot": {
      "command": "node",
      "args": [
        "G:\\游戏分区\\香草纪元\\botFormc\\bot.js"
      ]
    }
  }
}

游戏内指令

只有 .env 中 ALLOWED_PLAYERS 列出的玩家可以控制 Bot。常用说法包括：

跟着我 / 过来 / 跟随
停下 / 待命
收作物 / 收菜 / 种田
收甘蔗 / 收西瓜 / 收可可豆
吃东西 / 吃饭
打怪 / 打僵尸 / 战斗
巡逻 / 开始巡逻
钓鱼
插火把
剪羊毛
挤奶
喂动物
睡觉
回家
状态 / 位置

新任务开始时会终止旧任务。Bot 与玩家处于同一维度且距离不超过 32 格时优先正常寻路；距离更远或跨维度时使用 RCON 传送到玩家附近，再执行任务。

HTTP API

HTTP API 只监听 127.0.0.1：

POST /api/chat
GET  /api/status
POST /api/task
POST /api/stop
GET  /api/task-status
POST /api/tp-player
POST /api/tp-home
GET  /api/messages?limit=50
POST /api/autonomy
GET  /api/tasks

示例：

Invoke-RestMethod http://127.0.0.1:21083/api/status

Invoke-RestMethod http://127.0.0.1:21083/api/task `
  -Method Post `
  -ContentType application/json `
  -Body '{"player":"QDcvd","task":"farm","options":{}}'

行为与寻路说明

在大型 Forge 整合服中，Mineflayer 可能无法把 Forge 全局方块状态 ID 映射为正确的方块名称，典型现象是：

• bot.blockAt() 返回 null 或 out_of_world

• bot.findBlocks() 返回空数组

• 原生 pathfinder 看不见地形并卡住

• 日志出现 Bits per block is too big

因此，本项目不再依赖 Mineflayer 的方块地图进行路线规划。World Bridge 在 Minecraft 服务端线程读取真实方块状态和碰撞形状，并返回包含 walk、jump、fall、open_door、climb、swim 等动作的路线，Bot 再按路线模拟真实玩家移动。

RCON 传送只用于：

• Bot 与目标玩家距离超过 32 格

• 跨维度跟随或开始任务

• 紧急脱困或返回安全点

• 连续寻路失败后的任务级兜底

日志与诊断

• 聊天日志：logs/chat-YYYY-MM-DD.jsonl

• stdout：仅 MCP JSON-RPC 数据

• stderr：连接、任务、寻路和错误日志

常用诊断：

node cli.js status
node cli.js tasks
node cli.js messages 50

如果 Bot 无法登录：

1. 确认 Minecraft 服务端已启动且 MC_HOST:MC_PORT 可访问。

2. 检查服务端是否允许离线用户名登录，以及 Bot 用户名是否被占用。

3. 查看 stderr 中的 FML 握手、踢出或断线原因。

4. 不要同时运行两个使用同一用户名的 Bot 实例。

如果任务原地不动：

1. 用 node cli.js status 查看 worldBridge.available。

2. 核对 Token 文件路径和内容。

3. 确认 Bridge 与 Bot 在同一台机器上，且 21084 正常监听。

4. 查看 mineflayerWorldError 和 lastTaskResult。

5. 用 node cli.js stop 清理旧任务后重试。

如果 RCON 不可用，聊天和部分实体交互仍可能工作，但远距离传送、跨维移动和紧急回家将不可用。

已知限制

• 主要支持原版方块、作物、物品和实体；自定义 Mod 内容不保证可识别或交互。

• 服务端感知与寻路已经迁移到 Bridge，但少数旧任务的方块交互仍受 Mineflayer 对 Modded 注册表的限制。

• 钓鱼依赖鱼漂与粒子事件，在模组服中可能需要超时重抛。

• 放置火把、补种可可豆等需要精确朝向的动作，在复杂地形上可能失败。

• 巡逻任务会主动攻击配置范围内的敌对生物；普通跟随和种田不会自动进入战斗。

• World Bridge 只查询已经加载的区块，不会为了寻路强制加载新区块。

项目结构

botFormc/
├─ bot.js                  # 主入口：Bot + MCP + HTTP
├─ cli.js                  # HTTP CLI 客户端
├─ src/
│  ├─ controller.js        # 连接、指令与任务调度
│  ├─ behavior-engine.js   # 行为优先级与任务生命周期
│  ├─ movement-service.js  # 统一路线执行器
│  ├─ world-bridge.js      # Forge Bridge HTTP 客户端
│  ├─ mcp-server.js        # MCP 工具
│  ├─ http-api.js          # 本地 HTTP API
│  └─ tasks/               # 各项游戏行为
├─ forge-bridge/           # Forge 1.20.1 服务端 Mod
├─ scripts/test-harness.js # RCON 自动化测试工具
├─ logs/                   # 聊天日志
├─ .env.example
└─ package.json

安全提示

• HTTP API 和 World Bridge 均应保持仅监听本机回环地址。

• 不要提交 .env、RCON 密码或 renge_world_bridge.token。

• 测试脚本会通过 RCON 发放物品、生成实体或修改测试环境，只应在允许随意改造的服务器中使用。

• 部署或移除 Forge Bridge 前先停止服务端；该 Mod 本身不写入存档数据，删除 Jar 后重启即可回滚。