DebugBridge

# DebugBridge

A Fabric client mod for Minecraft (1.19, 1.21.11, and 26.2 development snapshots) 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 It Does

DebugBridge runs a localhost-only WebSocket server (default port 9876, scans 9876–9885) 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 Lua 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 |
| `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 |

### Lua execution (`execute` endpoint)

Run Lua 5.2 scripts inside the Minecraft JVM with full access to Minecraft APIs via a Java reflection bridge. 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).

“`lua
— Convenience globals already available
print(“Player at: ” .. player:blockPosition():toShortString())
print(“Dimension: ” .. mc.level:dimension().location())

— Import anything else you need
local Vec3 = java.import(“net.minecraft.world.phys.Vec3”)

— Iterate Java collections
for entity in java.iter(level:entitiesForRendering()) do
if entity:distanceTo(player) < 10 then print("Nearby: " .. java.typeof(entity)) end end ``` ## 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 - **Lua inspector** — Drill-down object browser for Lua values and Java objects - **Console** — Interactive Lua REPL connected to the running client - **Chat history** — Recent client-side messages Start it with: ```bash 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/weikengchen/mcdev-mcp | +---------------+-------------------+ | WebSocket (localhost:9876–9885) +---------------v-------------------+ | DebugBridge Mod [THIS REPO] | | +-----------------------------+ | | | BridgeServer (WebSocket) | | | | Native endpoints + execute | | | | Lua runtime + Java bridge | | | | Mojang mapping resolver | | | +-----------------------------+ | +-----------------------------------+ ^ | WebSocket (same port) +---------------+-------------------+ | Vue Web UI (localhost:5173) | | Dashboard, Inspector, Console | +-----------------------------------+ ``` ## 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 26.2 development build targets Mojang-named snapshot classes directly and skips 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` is disabled by default (opt-in via config) - **Developer warning** — first-launch screen informs the user the mod is active ## Repo Layout ``` mod/ core/ — Shared Java: BridgeServer, Lua 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.2-dev/— Fabric mod for Minecraft 26.2 development snapshots web-ui/ — Vue 3 + Pinia + Tailwind inspection app ``` ## Building Requires **JDK 21+** for the stable Fabric modules, **JDK 25** for `fabric-26.2-dev` (matches the runtime declared by the snapshot's own version manifest), and **Node ≥20.19** for the web UI. ```bash # Fabric mods cd mod JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ./gradlew build # JARs -> mod/fabric-*/build/libs/

# 26.2 development snapshot 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`.

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

Covers the Lua 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.

“`bash
# 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
“`

**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.

“`bash
# 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–9885). 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_get_item_texture`, `mc_set_entity_glow`, `mc_set_block_glow`, `mc_clear_block_glow`
– **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:

“`json
{
“id”: “1”,
“type”: “execute”,
“payload”: {
“code”: “return player:blockPosition():toShortString()”
}
}
“`

Each request gets a matching `{id, type, payload}` response.

## Dependencies Bundled in JAR

– **LuaJ 3.0.1** — Pure Java Lua 5.2 (MIT)
– **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.

Death Sound Mod

**Adds a death sound when a player dies within your render distance. No installation on the server needed.**

# Features:
Adds a death sound, which makes deaths more dramatic and immersive! You can fully customize the sound, volume, pitch, delay, and even use your own sounds!
## Dependencies:
| Required | Optional|
| :—: | :—: |
| | |
| **Fabric API** | **Mod Menu** |



To open the settings menu, klick the button in the pause menu.

## How to use custom sounds
1. Install the mod
2. Enable the Resource Pack ‘DeathSound-Resources’
3. Klick the button ‘Open Sound Folder’ in the DeathSound Custom Sound Menu
4. Place your .ogg file(s) in this folder
5. Select your file in the Custom Sound Menu
6. Your custom deathsound should now be active!

## Important
The versions for 1.20 and below are **unsupported** and will not be updated anymore!
That also means that a lot of features are not available on these versions.

## Languages:
### The mod (only version 1.21 and above) is available in 7 languages including:

– Englisch
– German (Deutschland)
– Deitsch (Österreich)
– Boarisch (Bayern)
– Pirate Speech (The Seven Seas)
– Filipino (Pilipinas)
– Polski (Polska)

Some of these translations may NOT be 100% accurate!

Data API

### Join the discord to interact with me and others about Minecraft

##  OVERVIEW 
With this datapack I hope to improve Minecraft’s severe lack of tools for developer use

##  FEATURES 

– *Visit the wiki for more information*

##  ALSO CHECK OUT 

| Datapacks |
| :-: |
|     |

—
| Projects | Social | Support |
| :-: | :-: | :-: |
|     |   |   |

danlib

a lib for my mods and extends vanilla for future mods like keeping block guis open no matter what block calls them and tag based pois are planned it does nothing diffrent from vanilla thats visable to users other then guis it uses mixins to do this altering base class passivly

Cyan Rose (Classic)

#

## FAQ

### Does this require any external mods?
Nope. This Resource Pack does not need any external mods for it to function properly.

### Can you put this pack on CurseForge?
I do not plan to put this pack on CurseForge, and probably never will.

### On some versions of Minecraft it says “The pack is too old”
On these versions “supported_formats” in pack.mcmeta was not introduced yet, because of that it looks at “pack_format” and says on the lines of “Pack format 5? (pack format for 1.15.2) That is old. This pack must not work on me anymore” even though the pack supports that version. Best you can do is just ignore it and enable the pack anyway.

### Did you make the Pixel Art yourself? (Modern Version question)
Yes! and you are free to use it on whatever project your working on. Credit would be appreciated, but its not mandatory, just dont copy the Resource Pack outright and publish it claiming its your own.

crelay SMP Pack

# A vanilla-themed SMP pack, perfect for SMP gameplay, Mace, and competitive PvP.

– Clean, polished GUI
– Built-in low fire, side shield, and smaller totem
– Sleek dark mode design


## It retextures:

-GUI Elements

-Critt Particles

-Sword Texture

-Fire

-And more!


Crosshair small, HUD big

**This Mini Texture Pack is perfect for those of us who use the “Interface Size” at 4 or maximum and want to have a crosshair or sight at a smaller scale without changing the “Interface Size”.**

**In addition to being centered, and solving the problem of the off-center crosshair, it is more convenient due to its “vanilla” size**

**I hope you like it, as it was made for convenience and not to change the “GUI Scale”**

Crafting

—
## 
## 
## 
## 
—
—

## 🧩 Crafting – More Recipes, More Possibilities!

Crafting is a simple but powerful mod that adds new crafting recipes, items, and structures to enhance your Minecraft gameplay.
If you ever felt limited by vanilla crafting, this mod expands your world with fresh creations and new ways to progress.

—

## ✨ Features

## 🛠️ New Crafting Recipes

Adds multiple new recipes to improve early and late-game progression

Unlocks new crafting combinations inspired by survival and adventure gameplay

Designed to stay balanced while adding more options

## 📦 New Items

Introduces unique custom items

Items can be used for crafting, tools, building, or survival

—

## 🔧 Technical

Mod Loader: Fabric / NeoForge / Forge / (Quilt
)

Minecraft Versions: 1.20.x → 26.x

Environment: Client & Server compatible

Lightweight and optimized for all systems

—

## 🎮 Why Use This Mod?

Keeps the game fresh without breaking vanilla balance

Perfect for survival worlds

Compatible with most other mods

Ideal for modpacks

—

## 📥 Getting Started

1. Install the mod

2. Launch your world

3. Start crafting the new recipes!

—

## 📝 Future Plans

More items

More crafting recipes

Custom blocks

More world-gen structures

Configurable options

—

## 💬 Feedback

If you find bugs or have suggestions, feel free to share them!
Your feedback helps improve the mod.

## Report
—

Crafting Cloth

# A Nice Small Touch To A Block You Use Probably More Than Anything!

This is a small resource pack that adds a little cloth on top of your Crafting Table. That’s it!


## Includes Some Mod Support!
Supports Crafting Tables from More Crafting Tables (MCT), Variant Crafting Tables, BetterNether, and BetterEnd


To install just open your .minecraft/resourcepacks and throw the zip file in for your version. Then go into Minecraft, Options, Resource Packs, and add it and you are good to go!

I hope you enjoy it!

Craftable Uncraftable Objects [CUO]

A Minecraft Project that adds crafting recipes for normally uncraftable items in Survival mode, along with custom advancements for a more rewarding experience.

**✨ Features**
* **New Crafting Recipes**: Craft items like the Enchanted Golden Apple, Totem of Undying, Trident, Horse Armors, Chainmail Armors, and more.
* **Custom Advancements**: Unique rewards for crafting special items.
* **Wide Compatibility**: Supports Minecraft Java Edition from version 1.13.x up to the latest snapshots.

**🏆 Advancements** & **📜 Recipes**

**🗒️ News & Updates**

To see the latest News about my Projects:

Telegram Channel

Patreon

Discord: (Coming Soon..)

**📂 Source Code & Issues**

To see the Source Code of the Project:

GitLab

Report about a problem or tell a suggestion:

GitLab

**🗂️ Installation**

Linux:

World that already exists:
1. Go to this location “~/.minecraft/saves/” (Make sure you are showing the Hidden Folders and Files by pressing Left Ctrl + H).
2. Choose the world folder you want to put the Data Pack in it.
3. Open datapacks folder, then put the data pack.zip in the datapacks folder.
4. Reload the world by /reload command or by Quit the world and rejoin it.

New World:
1. Open Minecraft, then click on “Singleplayer”.
2. Click on “Create New World”, then click “More World Options…”.
3. Click on “Data Packs” button, then drag the data pack file into Minecraft.
4. Click “Done” and “Create New World”.

———————————————-

MacOS:

World that already exists:
1. Go to this location “~/Library/Application Support/minecraft”.
2. Choose the world folder you want to put the Data Pack in it.
3. Open datapacks folder, then put the data pack.zip in the datapacks folder.
4. Reload the world by /reload command or by Quit the world and rejoin it.

New World:
1. Open Minecraft, then click on “Singleplayer”.
2. Click on “Create New World”, then click “More World Options…”.
3. Click on “Data Packs” button, then drag the data pack file into Minecraft.
4. Click “Done” and “Create New World”.

———————————————-

Windows:

World that already exists:
1. Press Win + R, then type %appdata%, then press Enter.
2. Open “Roaming” folder, then “.minecraft” folder, then open “saves” (Make sure you are showing the Hidden Folders and Files by pressing Left Ctrl + Left Shift + . (period)).
4. Choose the world folder you want to put the Data Pack in it.
5. Open datapacks folder, then put the data pack.zip in the datapacks folder.
6. Reload the world by /reload command or by Quit the world and rejoin it.

New World:
1. Open Minecraft, then click on “Singleplayer”.
2. Click on “Create New World”, then click “More World Options…”.
3. Click on “Data Packs” button, then drag the data pack file into Minecraft.
4. Click “Done” and “Create New World”.

Enjoy.

# Important Thing!
I know this is a Minecraft Project and this project has Minecraft things but because my project is an open source, I will talk about this.

Starting September 2026, a silent update, nonconsensually pushed by Google, will block every Android app whose developer hasn’t registered with Google, signed their contract, paid up, and handed over government ID.
For more information: https://keepandroidopen.org/.