DebugBridge
一款用于 Minecraft(1.19、1.21.11、精确版 26.1 和稳定版 26.2)的 Fabric 客户端模组,通过本地 WebSocket 服务器暴露游戏状态,并附带一个 Vue Web UI 用于可视化检查。专为 AI 辅助 Minecraft 开发与调试而构建。
2.1.0 更新内容
v2.1.0 为所有受支持的目标版本提供了相同的稳定功能线:Minecraft 1.19.x、1.21.11、精确版 26.1 和稳定版 26.2。之前的 26.2 开发模块现已成为稳定版 26.2 分支;源目录仍为 mod/fabric-26.2-dev/。
相较于 2.0.0,此版本还增强了现有桥接功能的健壮性:
record_video 默认使用临时存储,具有 24 小时 TTL 和自动清理功能(storage: "persistent" 会将文件保存在游戏目录下)
runCommand 保持相同的选择加入式协议契约,但现在使用原生的按版本提供者,而非 Groovy 往返调用
- 配置值经过范围验证,对象引用有界,脚本执行复用其工作线程,并且更防御性地处理了录制/断开连接/纹理/实体刷新竞争条件
- 精确版 26.1 可以在标题屏幕上渲染物品纹理(
getItemTextureById 不再因 Components not bound yet 而失败)
- Web UI 的物品栏槽位、实体颜色和商店刷新行为更加可靠
Groovy 5 脚本模型和端点集与 v2.0.0 兼容。请从 v2.1.0 发布页面 获取匹配的 jar 包。
功能介绍
DebugBridge 在 Minecraft 内部运行一个仅限本地主机的 WebSocket 服务器(默认端口 9876,扫描 9876–9886)。外部工具——CLI 脚本、捆绑的 Vue Web UI 或 MCP 客户端(如 Claude Code)——可以通过两个互补的 API 检查和与正在运行的游戏进行交互:
原生端点(快速、高级)
专为返回单次往返的结构化 JSON 而设计的 Java 端点——无脚本开销:
| 端点 |
返回内容 |
snapshot |
玩家位置、生命值、食物值、维度、游戏模式、时间、天气 |
nearbyEntities |
范围内的实体:类型、位置、装备、距离(可选 includeIcons 以获取物品纹理) |
entityDetails |
完整的实体信息:带伤害/自定义名称的装备槽位、载具、乘客、属性、容器内容 |
lookedAtEntity |
玩家瞄准的实体(射线检测) |
nearbyBlocks |
范围内的区块实体:告示牌、箱子、旗帜、信标、熔炉等 |
blockDetails |
区块实体内容:告示牌行、箱子库存、头颅配置文件、信标等级 |
screenInspect |
当前打开的屏幕/gui:类型、标题、带物品堆叠的容器槽位(可选 includeIcons) |
chatHistory |
最近的客户端聊天消息(可选 includeJson 以获取样式化组件) |
screenshot |
将帧缓冲区捕获为 JPEG |
record_video |
将 N 个帧缓冲区帧捕获为默认为临时的 JPEG 网格或逐帧文件 |
getItemTexture / getItemTextureById / getEntityItemTexture |
将物品图标渲染为 PNG(尊重损坏度、自定义模型数据、染色皮革、玩家头颅) |
setEntityGlow / setBlockGlow / clearBlockGlow |
使用世界内的轮廓高亮显示实体或方块 |
search |
按名称模式搜索已加载的类 |
status |
服务器健康和连接信息 |
两个端点家族在 config/debugbridge.json 中默认被禁用:runCommand (run_command_enabled) 通过原生按版本提供者以玩家身份发送命令,以及会话控制三件套 disconnect / joinServer / quit (session_control_enabled) 允许自动化循环离开世界、加入服务器或关闭客户端。joinServer 预先接受服务器资源包,并推迟连接直到客户端稳定(没有加载叠加层——在启动资源重新加载期间加入会无声地丢弃服务器资源包),仅在连接尝试实际开始后确认;一旦桥接端口在启动后响应,即可安全触发。
Groovy 执行(execute 端点)
在 Minecraft JVM 内运行 Groovy 脚本,通过感知映射的 Java 桥接器完全访问 Minecraft API——编写 Mojang 名称,它们会自动解析为运行时(intermediary)名称,即使在混淆构建中也是如此。便捷的全局变量 mc、player 和 level 已预绑定。沙箱允许进行文件 I/O 以读写数据。每个请求都有可配置的超时时间(默认 10 秒,最大 5 分钟)。
// 便捷的全局变量已可用
println "Player at: " + player.blockPosition().toShortString()
println "Dimension: " + mc.level.dimension().location()
// 通过 Mojang 名称加载任何其他内容(在混淆构建中也有效)。
// 优先使用单引号:双引号的 GString 会插值 $,
// 例如 Display$TextDisplay 这样的内部类名称。
def Vec3 = java.type('net.minecraft.world.phys.Vec3')
// 迭代 Java 集合。将批量循环包装在 sync { } 中,以便每次调用的
// 反射调度批处理为单个游戏线程跳转。
sync {
java.list(level.entitiesForRendering()).each { entity ->
if (entity.distanceTo(player) < 10) {
println "Nearby: " + java.typeName(entity)
}
}
}
Vue Web UI
web-ui/ 目录包含一个基于 Vue 3 + Pinia + Tailwind 的应用程序,用于可视化检查游戏状态:
- Dashboard — 玩家快照概览
- Entities panel — 附近实体列表,带有详细钻取、装备图标、高亮切换
- Blocks panel — 附近区块实体浏览器(告示牌、箱子等)
- Screen inspector — 当前 GUI/物品栏槽位查看器
- Groovy inspector — Java 对象的钻取对象浏览器
- Console — 连接到运行中客户端的交互式 Groovy REPL
- Chat history — 最近的客户端消息
自 v2.0.0 起内置 —— 模组自身提供构建好的 UI,访问地址为
http://localhost:<bridge port + 100>(默认 ;
加入游戏时的聊天消息会以可点击链接的形式打印确切 URL)。
仅限本地回环、仅静态资源,且提供的页面会连接至为其提供服务的桥接实例,因此并排运行的多个游戏实例各自拥有独立的 UI。可在 config/debugbridge.json 中通过 "web_ui_enabled": false 禁用此功能。
对于 UI 开发,开发服务器仍然有效(支持 HMR):
cd web-ui
npm run dev # → http://localhost:5173
Web UI 直接连接到 WebSocket 服务器——无需 MCP 层。
架构
+-----------------------------------+
| MCP Client (Claude Code, etc.) |
+---------------+-------------------+
| MCP Protocol (stdio)
+---------------v-------------------+
| mcdev-mcp Server (TypeScript) |
| Runtime + static analysis tools |
| github.com/use-ai-for-mc/mcdev-mcp|
+---------------+-------------------+
| WebSocket (localhost:9876–9886)
+---------------v-------------------+
| DebugBridge Mod [THIS REPO] |
| +-----------------------------+ |
| | BridgeServer (WebSocket) | |
| | Native endpoints + execute | |
| | Groovy runtime + Java bridge | |
| | Mojang mapping resolver | |
| +-----------------------------+ |
+-----------------------------------+
^
| WebSocket (same port)
+---------------+-------------------+
| Vue Web UI (bundled, :9976; |
| npm dev server :5173) |
+-----------------------------------+
Mojang 映射支持
模组在启动时自动下载官方 Mojang 映射文件,并使用它们将人类可读的名称(如 net.minecraft.client.Minecraft)转换为运行时使用的混淆名称。在 1.21.11 及更高版本中,Mojang 提供未混淆的名称,映射操作变为空操作(no-op)。
针对精确的 26.1 和 26.2 稳定版本的构建直接面向 Mojang 命名的类,完全跳过映射下载和重映射过程。
安全模型
DebugBridge 仅绑定到 localhost (127.0.0.1)。 只有运行在同一台机器上的进程才能连接。调试端口永远不会暴露给网络。
这是一个开发和调试工具,而非远程管理系统。任何拥有 localhost 访问权限的人已经可以完全控制 Minecraft 进程,因此该桥接不会引入新的攻击面。
- 仅客户端 —— 完全在客户端运行,无法影响服务器或其他玩家
- 无出站连接 —— 仅在启动时从 Mojang 官方 API 下载映射文件
- 受控功能 ——
runCommand 和会话控制默认禁用(需通过配置手动启用)
- 开发者警告 —— 首次启动屏幕会告知用户模组已激活;在被接受之前不提供任何服务
- Web UI 服务器 —— 同样仅限本地回环;仅提供 jar 包内捆绑的静态资源(仅 GET 请求,无目录列表,拒绝路径遍历)
仓库结构
mod/
core/ — 共享 Java 代码:BridgeServer、Groovy 运行时、映射解析器、Provider 接口
fabric-1.19/ — 适用于 Minecraft 1.19.x 的 Fabric 模组(Provider 实现 + Mixins)
fabric-1.21.11/— 适用于 Minecraft 1.21.11 的 Fabric 模组(Provider 实现 + Mixins)
fabric-26.1/ — 适用于精确 Minecraft 26.1 版本的 Fabric 模组(Provider 实现 + Mixins)
fabric-26.2-dev/— 适用于 Minecraft 26.2 稳定版的 Fabric 模组
web-ui/ — Vue 3 + Pinia + Tailwind 检查应用
安装
从 GitHub releases 获取对应 Minecraft 版本的 jar 包
(debugbridge-1.19-*.jar、debugbridge-1.21.11-*.jar、debugbridge-26.1-*.jar 或
debugbridge-26.2-*.jar),将其放入实例的 mods/ 文件夹中,并使用 Fabric Loader 启动。仅限客户端——服务器端无需安装任何内容。
首次运行时,模组会在游戏内显示开发者警告,并在你接受之前保持非活跃状态;相同的验证机制会将 developer_mode_accepted 写入
config/debugbridge.json。一旦接受,内置 Web UI 位于
(游戏内启动消息会打印确切 URL)。
对于本地精确 26.1 Prism Launcher 实例,请使用仓库脚本:
JAVA_HOME_26_1=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home \
PRISM_INSTANCE_NAME=26.1 \
./build-and-deploy-26.1.sh
要在不构建或不触碰实例的情况下检查选定的 Prism 实例、Java 路径、解析的 Gradle 版本、目标模组目录以及冒烟测试端口:
JAVA_HOME_26_1=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home \
PRISM_INSTANCE_NAME=26.1 \
./build-and-deploy-26.1.sh --preflight
该脚本构建 mod/fabric-26.1,暂存 jar 包,使用
unzip -tq 进行验证,并原子式地将其替换到选定 Prism 实例的
mods/ 目录中。它会验证构建和暂存的 jar 包声明了确切的 Minecraft 26.1 版本以及 com.debugbridge.fabric261.DebugBridgeMod
入口点,然后才替换已安装的 jar 包。如果桥接在最终冒烟测试中使用非默认端口,请在调用脚本时设置 SMOKE_PORT=<port>;
部署后的命令提示将使用该端口。
构建
稳定的 1.x Fabric 模块需要 JDK 21+,fabric-26.1 和稳定版 26.2 需要 JDK 25(模块路径为 fabric-26.2-dev,与 26.x 版本清单声明的运行时匹配),Web UI 需要 Node >=20.19。
# Fabric mods
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew build
# JARs -> mod/fabric-*/build/libs/
# Exact 26.1 bridge
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :fabric-26.1:jar
# 26.2 stable bridge
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test :fabric-26.2-dev:jar
# Web UI
cd web-ui
npm install
npm run dev # dev server at http://localhost:5173
npm run build # production build → web-ui/dist/
测试
三层自动化,在关键处发力:
1. 核心单元测试 — 纯 JVM,不依赖 Minecraft。通过 .github/workflows/build.yml 在每个 PR 时运行。
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test
覆盖 Groovy 桥接运行时、映射解析器内核(使用存根化的 Fabric SPI),以及每个端点的 wire-contract 测试(使用存根提供者)。
2. 针对实时模组的冒烟测试 — tools/smoke-test.mjs。通过 WebSocket 连接,调用每个内核候选端点并验证响应。耗时约 30 秒。需要 Node 22+ 以支持内置的 WebSocket 全局对象。
# 对正在运行的 1.21.11 模组进行冒烟测试
node tools/smoke-test.mjs --port 9876 --version 1.21.11
# 同时测试 1.19(默认端口:1.21.11=9876, 1.19=9877)
node tools/smoke-test.mjs --port 9877 --version 1.19
# 部署到 Prism 实例后,精确测试 26.1
node tools/smoke-test.mjs --port 9876 --version 26.1 --game-dir-contains '/instances/26.1/' --include-textures
node tools/record-video-smoke.mjs --port 9876 --version 26.1 --game-dir-contains '/instances/26.1/'
3. Wire-shape 回归模式 — 同一脚本配合 --regression DIR 使用。将每个实时响应的结构形状(各层级的键集合、值类型)与捕获的基准文件进行比较;发现漂移则失败。
# 在已知良好的构建后一次性捕获基线
node tools/smoke-test.mjs --port 9876 --version 1.21.11 \
--fixtures tools/fixtures/1.21.11
# 之后,在新构建部署后,检查是否有漂移
node tools/smoke-test.mjs --port 9876 --version 1.21.11 \
--regression tools/fixtures/1.21.11
形状比较器容忍值差异(瞬态游戏状态),但会标记任何结构性变化——新增/移除的键、类型不匹配。条件字段可能导致误报: snapshot.target 仅在玩家瞄准某物时才存在;nearbyEntities[].primaryEquipment 仅在最近的实体穿戴物品时才存在。请从内容丰富的状态中捕获基准文件,或将条件字段差异视为预期行为。
用法
与 Claude Code / MCP 一起使用
安装 mcdev-mcp 并在你的 MCP 客户端中进行配置。MCP 服务器会自动连接到 DebugBridge(扫描端口 9876–9886)。工具包括:
- Runtime(需要此模组):
mc_execute、mc_snapshot、mc_nearby_entities、mc_entity_details、mc_looked_at_entity、mc_nearby_blocks、mc_block_details、mc_screen_inspect、mc_chat_history、mc_screenshot、mc_record_video、mc_get_item_texture、mc_set_entity_glow、mc_set_block_glow、mc_clear_block_glow
- Session control / dev loop(需要
session_control_enabled):mc_join_server、mc_leave_server、mc_quit_client,以及用于驱动 rebuild → relaunch → rejoin 循环的 mc_wait_for_bridge / mc_wait_until_in_world
- Static(离线可用):
mc_get_class、mc_get_method、mc_search、mc_find_refs、mc_find_hierarchy
直接 WebSocket
连接到 ws://127.0.0.1:9876 并发送 JSON:
{
"id": "1",
"type": "execute",
"payload": {
"code": "return player.blockPosition().toShortString()"
}
}
每个请求都会收到一个匹配的 {id, type, payload} 响应。
record_video 存储
录制文件默认为临时文件,以免 AI 驱动的冒烟测试填满游戏目录:
{
"id": "rec-1",
"type": "record_video",
"payload": {
"frames": 120,
"interval": "frame",
"output": "grid",
"storage": "temp",
"ttlHours": 24
}
}
storage 默认为 "temp",并写入系统临时目录下由 DebugBridge 拥有的子文件夹中。响应中包含 storage、directory 和 expiresAt。使用 "storage": "persistent" 可将输出保留在 <gameDir>/debugbridge-recordings/<requestId>/ 下;requestId 是一个可选的清理后的子目录名称,而非任意文件系统路径。
JAR 中捆绑的依赖
- Apache Groovy 5.0.6 — JVM 脚本运行时(Apache-2.0)
- Java-WebSocket 1.6.0 — WebSocket 服务器(MIT)
- Gson 2.14.0 — JSON 解析(Apache 2.0)
许可证
MIT License — 详见 LICENSE 文件。
DebugBridge
A Fabric client mod for Minecraft (1.19, 1.21.11, exact 26.1, and stable 26.2) that exposes game state over a local WebSocket server, plus a Vue web UI for visual inspection. Built for AI-assisted Minecraft development and debugging.
What's New in 2.1.0
v2.1.0 ships the same stable feature line for every maintained target: Minecraft 1.19.x, 1.21.11, exact 26.1, and stable 26.2. The former 26.2 development module is now the stable 26.2 line; the source directory is still mod/fabric-26.2-dev/.
Relative to 2.0.0 this release also hardens the existing bridge:
record_video defaults to temporary storage with a 24-hour TTL and automatic cleanup (storage: "persistent" keeps files under the game directory)
runCommand keeps the same opt-in wire contract, but now uses a native per-version provider instead of a Groovy round-trip
- Config values are range-validated, object refs are bounded, script execution reuses its worker, and recording / disconnect / texture / entity-refresh races are handled more defensively
- Exact 26.1 can render item textures on the title screen (
getItemTextureById no longer fails with Components not bound yet)
- Web UI inventory slots, entity colors, and store refresh behavior are more reliable
The Groovy 5 scripting model and endpoint set remain compatible with v2.0.0. Grab the matching jar from the v2.1.0 release.
What It Does
DebugBridge runs a localhost-only WebSocket server (default port 9876, scans 9876–9886) inside Minecraft. External tools — CLI scripts, the bundled Vue web UI, or MCP clients like Claude Code — can inspect and interact with the running game through two complementary APIs:
Native endpoints (fast, high-level)
Purpose-built Java endpoints that return structured JSON in a single round-trip — no scripting overhead:
| Endpoint |
What it returns |
snapshot |
Player position, health, food, dimension, gamemode, time, weather |
nearbyEntities |
Entities within range: type, position, equipment, distance (with optional includeIcons for item textures) |
entityDetails |
Full entity info: equipment slots with damage/custom names, vehicle, passengers, attributes, frame contents |
lookedAtEntity |
The entity the player is aiming at (raycast) |
nearbyBlocks |
Block-entities within range: signs, chests, banners, beacons, furnaces, etc. |
blockDetails |
Block-entity contents: sign lines, chest inventory, skull profile, beacon level |
screenInspect |
Current open screen/gui: type, title, container slots with item stacks (with optional includeIcons) |
chatHistory |
Recent client-side chat messages (with optional includeJson for styled components) |
screenshot |
Capture the framebuffer as JPEG |
record_video |
Capture N framebuffer frames as a temp-by-default JPEG grid or per-frame files |
getItemTexture / getItemTextureById / getEntityItemTexture |
Render item icons as PNG (honors damage, custom model data, dyed leather, player heads) |
setEntityGlow / setBlockGlow / clearBlockGlow |
Highlight entities or blocks with an in-world outline |
search |
Search loaded classes by name pattern |
status |
Server health and connection info |
Two endpoint families are gated off by default in config/debugbridge.json: runCommand (run_command_enabled) sends commands as the player through a native per-version provider, and the session-control trio disconnect / joinServer / quit (session_control_enabled) lets an automation loop leave a world, join a server, or shut the client down. joinServer pre-accepts the server resource pack and defers the connect until the client has settled (no loading overlay — joining during the startup resource reload would silently drop the server pack), acking only once the connect attempt has actually started; it's safe to fire the moment the bridge port answers after a launch.
Groovy execution (execute endpoint)
Run Groovy scripts inside the Minecraft JVM with full access to Minecraft APIs via a mapping-aware Java bridge — write Mojang names and they resolve to the runtime (intermediary) names automatically, even on obfuscated builds. Convenience globals mc, player, and level are pre-bound. The sandbox allows file I/O for reading/writing data. Each request has a configurable timeout (default 10s, max 5 min).
// Convenience globals already available
println "Player at: " + player.blockPosition().toShortString()
println "Dimension: " + mc.level.dimension().location()
// Load anything else by Mojang name (works on obfuscated builds too).
// Prefer single quotes: double-quoted GStrings interpolate the $ in
// inner-class names like Display$TextDisplay.
def Vec3 = java.type('net.minecraft.world.phys.Vec3')
// Iterate Java collections. Wrap a bulk loop in sync { } so the per-call
// reflective dispatch batches into a single game-thread hop.
sync {
java.list(level.entitiesForRendering()).each { entity ->
if (entity.distanceTo(player) < 10) {
println "Nearby: " + java.typeName(entity)
}
}
}
Vue Web UI
The web-ui/ directory contains a Vue 3 + Pinia + Tailwind app for visual inspection of game state:
- Dashboard — Player snapshot overview
- Entities panel — Nearby entity list with detail drill-down, equipment icons, glow toggling
- Blocks panel — Nearby block-entity browser (signs, chests, etc.)
- Screen inspector — Current GUI/inventory slot viewer
- Groovy inspector — Drill-down object browser for Java objects
- Console — Interactive Groovy REPL connected to the running client
- Chat history — Recent client-side messages
Bundled since v2.0.0 — the mod serves the built UI itself at
http://localhost:<bridge port + 100> (default ;
the join-time chat message prints the exact URL as a clickable link).
Loopback-only, static
assets only, and the served page connects to the bridge instance that served
it, so side-by-side game instances each get their own UI. Disable with
"web_ui_enabled": false in config/debugbridge.json.
For UI development, the dev server still works (with HMR):
cd web-ui
npm run dev # → http://localhost:5173
The web UI connects directly to the WebSocket server — no MCP layer required.
Architecture
+-----------------------------------+
| MCP Client (Claude Code, etc.) |
+---------------+-------------------+
| MCP Protocol (stdio)
+---------------v-------------------+
| mcdev-mcp Server (TypeScript) |
| Runtime + static analysis tools |
| github.com/use-ai-for-mc/mcdev-mcp|
+---------------+-------------------+
| WebSocket (localhost:9876–9886)
+---------------v-------------------+
| DebugBridge Mod [THIS REPO] |
| +-----------------------------+ |
| | BridgeServer (WebSocket) | |
| | Native endpoints + execute | |
| | Groovy runtime + Java bridge | |
| | Mojang mapping resolver | |
| +-----------------------------+ |
+-----------------------------------+
^
| WebSocket (same port)
+---------------+-------------------+
| Vue Web UI (bundled, :9976; |
| npm dev server :5173) |
+-----------------------------------+
Mojang Mapping Support
The mod automatically downloads official Mojang mappings at startup and uses them to translate human-readable names (net.minecraft.client.Minecraft) to the obfuscated names used at runtime. In 1.21.11+, Mojang ships unobfuscated names and mapping is a no-op.
The exact 26.1 and 26.2 stable builds target Mojang-named classes directly and skip mapping download/remap entirely.
Security Model
DebugBridge binds exclusively to localhost (127.0.0.1). Only processes running on the same machine can connect. The debug port is never exposed to the network.
This is a development and debugging tool, not a remote administration system. Anyone with localhost access already has full control over the Minecraft process, so the bridge does not introduce new attack surface.
- Client-side only — runs entirely on the client, cannot affect servers or other players
- No outbound connections — only startup mapping downloads from Mojang's official APIs
- Gated features —
runCommand and session control are disabled by default (opt-in via config)
- Developer warning — first-launch screen informs the user the mod is active; nothing serves until accepted
- Web UI server — same loopback-only posture; serves only the static assets bundled in the jar (GET-only, no directory listing, path-traversal rejected)
Repo Layout
mod/
core/ — Shared Java: BridgeServer, Groovy runtime, mapping resolver, provider interfaces
fabric-1.19/ — Fabric mod for Minecraft 1.19.x (provider impls + mixins)
fabric-1.21.11/— Fabric mod for Minecraft 1.21.11 (provider impls + mixins)
fabric-26.1/ — Fabric mod for exact Minecraft 26.1 (provider impls + mixins)
fabric-26.2-dev/— Fabric mod for Minecraft 26.2 stable
web-ui/ — Vue 3 + Pinia + Tailwind inspection app
Installation
Grab the jar for your Minecraft version from the
GitHub releases
(debugbridge-1.19-*.jar, debugbridge-1.21.11-*.jar, debugbridge-26.1-*.jar, or
debugbridge-26.2-*.jar), drop it into your instance's mods/ folder, and
launch with Fabric Loader. Client-side only — nothing to install on a server.
On first run the mod shows a developer warning in-game and stays inactive
until you accept it; the same gate writes developer_mode_accepted into
config/debugbridge.json. Once accepted, the bundled web UI is at
(the in-game startup message prints the exact URL).
For the local exact-26.1 Prism Launcher instance, use the repo script:
JAVA_HOME_26_1=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home \
PRISM_INSTANCE_NAME=26.1 \
./build-and-deploy-26.1.sh
To check the selected Prism instance, Java path, parsed Gradle version, target
mods directory, and smoke-test port without building or touching the instance:
JAVA_HOME_26_1=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home \
PRISM_INSTANCE_NAME=26.1 \
./build-and-deploy-26.1.sh --preflight
The script builds mod/fabric-26.1, stages the jar, verifies it with
unzip -tq, and atomically swaps it into the selected Prism instance's
mods/ directory. It verifies the built and staged jars declare exact
Minecraft 26.1 and the com.debugbridge.fabric261.DebugBridgeMod
entrypoint before replacing the installed jar. If the bridge uses a non-default
port for the final smoke run, set SMOKE_PORT=<port> when invoking the script;
the post-deploy command hints will use that port.
Building
Requires JDK 21+ for the stable 1.x Fabric modules, JDK 25 for
fabric-26.1 and stable 26.2 (module path fabric-26.2-dev, matching the runtime declared by the
26.x version manifests), and Node >=20.19 for the web UI.
# Fabric mods
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew build
# JARs -> mod/fabric-*/build/libs/
# Exact 26.1 bridge
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :fabric-26.1:jar
# 26.2 stable bridge
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test :fabric-26.2-dev:jar
# Web UI
cd web-ui
npm install
npm run dev # dev server at http://localhost:5173
npm run build # production build → web-ui/dist/
Testing
Three layers, automated where it pays off:
1. Core unit tests — pure JVM, no Minecraft. Runs every PR via .github/workflows/build.yml.
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test
Covers the Groovy bridge runtime, mapping resolver kernel (with stubbed Fabric SPI), and wire-contract tests for every endpoint (using stub providers).
2. Smoke test against a live mod — tools/smoke-test.mjs. Connects via WebSocket, hits each kernel-candidate endpoint, validates the response. ~30 seconds. Requires Node 22+ for the built-in WebSocket global.
# Smoke test against running 1.21.11 mod
node tools/smoke-test.mjs --port 9876 --version 1.21.11
# 1.19 alongside (default ports: 1.21.11=9876, 1.19=9877)
node tools/smoke-test.mjs --port 9877 --version 1.19
# Exact 26.1 after deploying to a Prism instance
node tools/smoke-test.mjs --port 9876 --version 26.1 --game-dir-contains '/instances/26.1/' --include-textures
node tools/record-video-smoke.mjs --port 9876 --version 26.1 --game-dir-contains '/instances/26.1/'
3. Wire-shape regression mode — same script with --regression DIR. Compares each live response's structural shape (key sets at every level, value types) against a captured fixture; fails on drift.
# Capture baselines once after a known-good build
node tools/smoke-test.mjs --port 9876 --version 1.21.11 \
--fixtures tools/fixtures/1.21.11
# Later, after deploying a new build, check for drift
node tools/smoke-test.mjs --port 9876 --version 1.21.11 \
--regression tools/fixtures/1.21.11
The shape comparator tolerates value differences (transient game state) but flags any structural change — added/removed keys, type mismatches. Conditional fields can produce false positives: snapshot.target is only present when the player is aiming at something; nearbyEntities[].primaryEquipment only when the closest entity wears something. Capture fixtures from a richly-populated state, or treat conditional-field diffs as expected.
Usage
With Claude Code / MCP
Install mcdev-mcp and configure it in your MCP client. The MCP server auto-connects to DebugBridge (scans ports 9876–9886). Tools include:
- Runtime (requires this mod):
mc_execute, mc_snapshot, mc_nearby_entities, mc_entity_details, mc_looked_at_entity, mc_nearby_blocks, mc_block_details, mc_screen_inspect, mc_chat_history, mc_screenshot, mc_record_video, mc_get_item_texture, mc_set_entity_glow, mc_set_block_glow, mc_clear_block_glow
- Session control / dev loop (requires
session_control_enabled): mc_join_server, mc_leave_server, mc_quit_client, plus mc_wait_for_bridge / mc_wait_until_in_world for driving rebuild → relaunch → rejoin loops
- Static (works offline):
mc_get_class, mc_get_method, mc_search, mc_find_refs, mc_find_hierarchy
Direct WebSocket
Connect to ws://127.0.0.1:9876 and send JSON:
{
"id": "1",
"type": "execute",
"payload": {
"code": "return player.blockPosition().toShortString()"
}
}
Each request gets a matching {id, type, payload} response.
record_video storage
Recordings are temporary by default so AI-driven smoke tests do not fill the
game directory:
{
"id": "rec-1",
"type": "record_video",
"payload": {
"frames": 120,
"interval": "frame",
"output": "grid",
"storage": "temp",
"ttlHours": 24
}
}
storage defaults to "temp" and writes under a DebugBridge-owned subfolder of
the system temp directory. The response includes storage, directory, and
expiresAt. Use "storage": "persistent" to keep output under
<gameDir>/debugbridge-recordings/<requestId>/; requestId is an optional
sanitized subdirectory name, not an arbitrary filesystem path.
Dependencies Bundled in JAR
- Apache Groovy 5.0.6 — JVM scripting runtime (Apache-2.0)
- Java-WebSocket 1.6.0 — WebSocket server (MIT)
- Gson 2.14.0 — JSON parsing (Apache 2.0)
License
MIT License — see LICENSE file for details.
评论 0
登录后参与评分
还没有评论,来抢沙发吧