DebugBridge

DebugBridge

Клиентский мод для Fabric (Minecraft 1.19, 1.21.11, exact 26.1 и stable 26.2), который отдаёт состояние игры через локальный WebSocket-сервер, плюс веб-интерфейс на Vue для визуального просмотра. Создан для разработки и отладки Minecraft с помощью ИИ.

Что нового в 2.1.0

v2.1.0 выпускает одну и ту же стабильную линейку функций для всех поддерживаемых целей: Minecraft 1.19.x, 1.21.11, exact 26.1 и stable 26.2. Бывший dev-модуль 26.2 теперь стал стабильной линейкой 26.2; каталог исходников по-прежнему mod/fabric-26.2-dev/.

Относительно 2.0.0 этот релиз также укрепляет существующий мост:

• record_video по умолчанию пишет во временное хранилище с TTL 24 часа и автоочисткой (storage: "persistent" сохраняет файлы в каталоге игры)
• runCommand сохраняет тот же opt-in контракт, но теперь использует нативный провайдер под каждую версию вместо круга через Groovy
• Значения конфига проверяются по диапазону, ссылки на объекты ограничены, выполнение скриптов переиспользует свой воркер, а гонки при записи / отключении / текстурах / обновлении ссылок на сущности обрабатываются более защищённо
• Exact 26.1 умеет рендерить текстуры предметов на титульном экране (getItemTextureById больше не падает с Components not bound yet)
• Слоты инвентаря в веб-интерфейсе, цвета сущностей и поведение обновления стора стали надёжнее

Модель скриптинга на Groovy 5 и набор эндпоинтов остаются совместимы с v2.0.0. Скачайте подходящий jar из релиза v2.1.0.

Что он делает

DebugBridge запускает внутри Minecraft WebSocket-сервер, доступный только с localhost (порт по умолчанию 9876, сканирует 9876–9886). Внешние инструменты — CLI-скрипты, встроенный веб-интерфейс на Vue или MCP-клиенты вроде Claude Code — могут просматривать запущенную игру и взаимодействовать с ней через два взаимодополняющих API:

Нативные эндпоинты (быстрые, высокоуровневые)

Специализированные Java-эндпоинты, возвращающие структурированный JSON за один запрос — без накладных расходов на скриптинг:

Два семейства эндпоинтов отключены по умолчанию в config/debugbridge.json: runCommand (run_command_enabled) отправляет команды от имени игрока через нативный провайдер под каждую версию, а трио управления сессией disconnect / joinServer / quit (session_control_enabled) позволяет циклу автоматизации выйти из мира, подключиться к серверу или выключить клиент. joinServer заранее принимает ресурспак сервера и откладывает подключение, пока клиент не устаканится (без оверлея загрузки — подключение во время перезагрузки ресурсов при запуске молча отбросило бы серверный пак), подтверждая только после того, как попытка подключения действительно началась; его безопасно вызывать сразу, как только порт моста отвечает после запуска.

Выполнение Groovy (endpoint execute)

Запускай Groovy-скрипты внутри JVM Minecraft с полным доступом к API Minecraft через мост Java с поддержкой маппингов — пиши имена Mojang, и они автоматически разрешатся в имена времени выполнения (intermediary), даже на обфусцированных сборках. Удобные глобалы mc, player и level уже привязаны. Песочница разрешает файловый ввод-вывод для чтения/записи данных. У каждого запроса есть настраиваемый таймаут (по умолчанию 10 с, максимум 5 мин).

// Удобные глобалы уже доступны
println "Player at: " + player.blockPosition().toShortString()
println "Dimension: " + mc.level.dimension().location()

// Загружай что угодно ещё по имени Mojang (работает и на обфусцированных сборках).
// Предпочитай одинарные кавычки: GStrings в двойных кавычках интерполируют $ в
// именах внутренних классов вроде 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/ содержит приложение на 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:<порт моста + 100> (по умолчанию http://localhost:9976; сообщение в чате при подключении печатает точный URL кликабельной ссылкой). Только loopback, только статические ресурсы, и раздаваемая страница подключается к тому экземпляру моста, который её раздал, так что параллельно запущенные экземпляры игры получают каждый свой UI. Отключается через "web_ui_enabled": false в config/debugbridge.json.

Для разработки UI dev-сервер по-прежнему работает (с HMR):

cd web-ui
npm run dev          # → http://localhost:5173

Веб-интерфейс подключается напрямую к 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 поставляет необфусцированные имена, и маппинг ничего не делает.

Стабильные сборки 26.1 и 26.2 обращаются напрямую к классам с именами от Mojang и полностью пропускают скачивание маппингов и ремап.

Модель безопасности

DebugBridge слушает только localhost (127.0.0.1). Подключиться могут лишь процессы на той же машине. Отладочный порт никогда не выставляется в сеть.

Это инструмент для разработки и отладки, а не система удалённого администрирования. У любого, у кого есть доступ к localhost, уже есть полный контроль над процессом Minecraft, так что мост не создаёт новых точек атаки.

• Только клиентская часть — работает целиком на клиенте, не может влиять на серверы или других игроков
• Никаких исходящих соединений — только скачивание маппингов при запуске с официальных API Mojang
• Функции под ограничением — runCommand и управление сессией отключены по умолчанию (включаются вручную через конфиг)
• Предупреждение для разработчика — экран при первом запуске сообщает пользователю, что мод активен; ничего не работает, пока не будет принято
• Сервер веб-интерфейса — та же привязка только к loopback; отдаёт лишь статические файлы, встроенные в jar (только GET, без листинга каталогов, обход путей отклоняется)

Структура репозитория

mod/
  core/          — Общий Java-код: BridgeServer, среда Groovy, резолвер маппингов, интерфейсы провайдеров
  fabric-1.19/   — Fabric-мод для Minecraft 1.19.x (реализации провайдеров + миксины)
  fabric-1.21.11/— Fabric-мод для Minecraft 1.21.11 (реализации провайдеров + миксины)
  fabric-26.1/   — Fabric-мод для точной версии Minecraft 26.1 (реализации провайдеров + миксины)
  fabric-26.2-dev/— Fabric-мод для стабильной Minecraft 26.2
web-ui/          — Приложение для инспекции на Vue 3 + Pinia + Tailwind

Установка

Скачайте jar для своей версии Minecraft из релизов на GitHub (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. После принятия встроенный веб-интерфейс доступен по адресу http://localhost:9976 (сообщение при запуске в игре выводит точный URL).

Для локального инстанса Prism Launcher с точной версией 26.1 используйте скрипт из репозитория:

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, целевую папку mods и порт для смоук-теста без сборки и без изменений в инстансе:

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 и атомарно подменяет его в папке mods/ выбранного инстанса Prism. Перед заменой установленного jar он проверяет, что собранный и подготовленный jar-файлы объявляют точную версию Minecraft 26.1 и точку входа com.debugbridge.fabric261.DebugBridgeMod. Если мост использует нестандартный порт для финального смоук-запуска, задайте `SMOKE_PORT=` при вызове скрипта; подсказки команд после развёртывания будут использовать этот порт.

Сборка

Требуется JDK 21+ для стабильных модулей Fabric 1.x, JDK 25 для fabric-26.1 и стабильной 26.2 (путь модуля fabric-26.2-dev, в соответствии со средой выполнения, объявленной в манифестах версии 26.x), и Node >=20.19 для веб-интерфейса.

# Fabric-моды
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew build
# JAR-файлы -> mod/fabric-*/build/libs/

# Мост для точной 26.1
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :fabric-26.1:jar

# Мост для стабильной 26.2
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@25/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test :fabric-26.2-dev:jar

# Веб-интерфейс
cd web-ui
npm install
npm run dev          # dev-сервер на http://localhost:5173
npm run build        # продакшн-сборка → web-ui/dist/

## Тестирование

Три уровня, автоматизированные там, где это оправдано:

**1. Основные юнит-тесты** — чистый JVM, без Minecraft. Запускаются на каждом PR через `.github/workflows/build.yml`.

```bash
cd mod
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew :core:test

Покрывают рантайм Groovy-моста, ядро резолвера маппингов (со заглушкой Fabric SPI) и тесты wire-контрактов для каждой конечной точки (с использованием заглушек провайдеров).

2. Smoke-тест против живого мода — tools/smoke-test.mjs. Подключается через WebSocket, дёргает каждую конечную точку-кандидат ядра, проверяет ответ. ~30 секунд. Требует Node 22+ для встроенного глобала WebSocket.

# 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-формы — тот же скрипт с --regression DIR. Сравнивает структурную форму каждого живого ответа (наборы ключей на каждом уровне, типы значений) с сохранённым фикстуром; падает при расхождении.

# 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

Компаратор формы терпим к различиям значений (преходящее состояние игры), но помечает любое структурное изменение — добавленные/удалённые ключи, несовпадения типов. Условные поля могут давать ложные срабатывания: 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_enabled): mc_join_server, mc_leave_server, mc_quit_client, плюс mc_wait_for_bridge / mc_wait_until_in_world для циклов пересборка → перезапуск → переподключение
• Статические (работают офлайн): 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-управляемые smoke-тесты не забивали игровую директорию:

{
  "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", чтобы сохранить вывод в `/debugbridge-recordings//; 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.