BlackBoxPro — Minecraft 自动化黑盒测试框架

像真实玩家一样操作，像自动化测试一样验证。

模组版本需要额外开发，如有需要请反馈 GitHub Issues 或自主开发

源码地址: https://github.com/YsGqHY/BlackBoxPro

这是什么？

BlackBoxPro 是一套面向 Minecraft 服务端插件开发者的自动化黑盒测试框架。

它由两部分组成：安装在客户端的 Mod 和安装在服务端的 Plugin。服务端通过 Plugin Message Channel 或 HTTP API 向客户端下发 JSON 指令，Mod 在客户端模拟真实玩家的一切行为——走路、挖矿、打开箱子、点击 GUI、输入聊天、截图——然后将执行结果回传给服务端。

你不再需要手动登录游戏反复测试，也不需要写 Mock 来伪造客户端行为。BlackBoxPro 让你的测试脚本直接驱动一个真实的 Minecraft 客户端。

能做什么？

112 个 Action，覆盖玩家能做的一切

能力	举例
移动与寻路	走到指定坐标、A* 寻路、看向目标、跳跃、潜行、冲刺
方块交互	挖掘方块、放置方块、使用物品
实体交互	攻击实体、右键交互、挥手
容器操作	打开箱子、点击槽位、Shift 转移、悬停查看 Tooltip
聊天与命令	发送消息、执行命令、点击聊天中的可点击文本
截图验证	普通截图、Tooltip 渲染截图，保存到本地供视觉比对
状态查询	玩家状态、背包物品、方块信息、记分板、Boss Bar、聊天历史等 17 种查询
复合行为	批量执行、挖掘方块（自动看向+挖掘+等待）、合成配方
客户端控制	连接服务器、创建/加入/离开世界、修改客户端设置

双通道通讯

服务端插件 ──── Plugin Message Channel ────▶ 客户端 Mod
外部工具   ──── HTTP POST :38081 ──────────▶ 客户端 Mod
外部工具   ──── HTTP POST :38080 ──────────▶ 服务端插件 ──▶ 客户端 Mod

Plugin Message Channel：服务端插件直接向在线玩家的 Mod 下发指令，适合集成测试
HTTP API：任何外部工具（Python 脚本、CI 流水线、Postman）都能通过 HTTP 直接调用，零依赖接入

物理引擎驱动的移动

不是简单的 setPosition 传送。BlackBoxPro 通过 InjectedInput 注入键盘输入，让 Minecraft 原生物理引擎处理碰撞、重力、速度，移动行为与真实玩家完全一致。

支持的版本

Minecraft	Mod Loader	说明
1.21.11	Fabric / NeoForge	最新版，112 个 Action
1.21.1	Fabric / NeoForge	112 个 Action
1.12.2	Forge	兼容子集，105 个 Action

服务端插件基于 Paper/Spigot + TabooLib，兼容主流服务端。

快速上手

1. 安装

将对应版本的 Mod jar 放入客户端 mods/ 目录
将 Plugin jar 放入服务端 plugins/ 目录
启动服务端和客户端，玩家加入服务器后自动建立通讯通道

2. 发送第一条指令

通过服务端命令：

/blackbox exec <玩家名> query_player_state

或通过 HTTP API：

curl -X POST http://localhost:38081/execute \
  -H "Content-Type: application/json" \
  -d '{"id":"test-1","action":"query_player_state","params":{}}'

响应：

{
  "id": "test-1",
  "status": "success",
  "data": {
    "x": 100.5, "y": 64.0, "z": -200.3,
    "health": 20.0, "food": 20,
    "gameMode": "survival",
    "dimension": "minecraft:overworld"
  }
}

3. 编写测试脚本

用任何语言通过 HTTP API 编写自动化测试：

import requests, time

API = "http://localhost:38081/execute"

def action(action_id, params=None):
    resp = requests.post(API, json={
        "id": f"test-{time.time()}",
        "action": action_id,
        "params": params or {}
    })
    return resp.json()

# 走到商店 NPC 面前
action("navigate_to", {"x": 100, "y": 64, "z": -200, "speed": 1.0})

# 右键交互 NPC（实体 ID 42）
action("interact_entity", {"entityId": 42})

# 等待 GUI 打开，查询容器状态
time.sleep(1)
result = action("query_container_slots", {"windowId": 1})

# 截图留证
action("screenshot", {"testId": "shop_test", "prefix": "npc_gui"})

# 验证第一个槽位的物品
slots = result["data"]["slots"]
assert slots[0]["itemId"] == "minecraft:diamond_sword"
print("Test passed!")

4. 服务端插件 API（Java/Kotlin）

// 异步调用，CompletableFuture 风格
val future = BlackBoxApi.request(player, "query_player_state")
future.thenAccept { response ->
    val health = response.data?.get("health")?.asDouble
    println("玩家血量: $health")
}

// 批量执行
BlackBoxApi.fire(player, "batch", JsonObject().apply {
    add("actions", gson.toJsonTree(listOf(
        mapOf("action" to "sneak_start"),
        mapOf("action" to "wait", "params" to mapOf("ticks" to 20)),
        mapOf("action" to "sneak_stop")
    )))
})

典型使用场景

场景	做法
商店插件测试	走到 NPC → 右键打开 GUI → 点击购买槽位 → 查询背包验证物品
传送系统测试	执行 `/warp spawn` → 查询玩家坐标 → 断言位置正确
权限系统测试	以不同权限玩家执行命令 → 验证返回消息
GUI 视觉回归	打开 GUI → 截图 → 与基准图对比
战斗系统测试	切换武器 → 攻击实体 → 查询实体血量变化
聊天交互测试	触发带 ClickEvent 的消息 → 模拟点击 → 验证效果
记分板验证	查询 sidebar 记分板 → 断言分数与预期一致

项目架构

BlackBoxPro/
├── common/          # 共享协议层（JSON 消息模型）
├── mod/
│   ├── 1.21.11/     # Fabric + NeoForge（runtime 共享核心）
│   ├── 1.21.1/      # Fabric + NeoForge
│   └── 1.12.2/      # Forge（独立构建）
└── plugin/          # Bukkit 服务端插件（TabooLib）

Kotlin 全栈，Gradle 多模块聚合构建
runtime 模块承载跨 Loader 共享逻辑，Fabric/NeoForge 仅保留平台胶水代码
CI/CD 通过 GitHub Actions 自动构建，push 到 main 即发布 Release

开源地址

GitHub: https://github.com/YsGqHY/BlackBoxPro

MIT 协议开源，欢迎 Star、Fork、提 Issue。

构建

# 全量构建
./gradlew buildAll

# 产物收集在 build/libs/ 目录

也可以直接从 GitHub Releases 下载预编译 jar。

BlackBoxPro —— 专为AI Agent 全自动为 Minecraft 服务器插件、mod自动化测试