BCDebugJavaAgent

Internally | BlockConnect uses a Minecraft‑debug‑level JavaAgent, which is suitable for bytecode‑level analysis and log retention for Minecraft in environments where AprismJDK is not used or unavailable.

Status: v26.0 GA

BCDebugJavaAgent is a JVM-level Java Agent for Minecraft Java Edition (1.12.2–26.2) that performs:

• Bytecode analysis & recording — instruments methods at class-load time using ASM, records entry/exit counts and timing
• JVM-level hook debugging — injects hooks into MC lifecycle methods (tick, render, world load) via SPI-discovered providers
• Log behavior export — exports JSONL logs and method statistics on JVM shutdown

BCDebugJavaAgent/
├── bc-agent-core/          # Core: ASM bytecode analysis, hook registry, logging, export
├── bc-agent/               # Agent: premain/agentmain entry, config, HTTP control server
├── bc-hooks-26/            # MC 26.x specific hooks (26.2, 26.1.2)
├── bc-hooks-legacy/        # MC legacy hooks (1.20.x, 1.21.x, Mojang mappings)
├── build.gradle             # Root build + fatJar task
├── gradle.properties        # Version config
└── settings.gradle          # Multi-project settings

$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21.0.11.10-hotspot"
.\gradlew.bat fatJar

Output: build/libs/bcdebug-javaagent-v26.0-Alpha.1.jar

# Minecraft client or dedicated server — a bare -javaagent is sufficient.
# The shim self-appends its embedded jar to the bootstrap classpath at runtime,
# so no -Xbootclasspath/a is required in any launch mode.
java -javaagent:bcdebug-javaagent.jar=logLevel=DEBUG,hookProfile=auto -jar minecraft.jar

# Obfuscated legacy jar (1.20.x / 1.21.x stock server/client): either point
# mappingsFile at Mojang's published ProGuard txt, or let the agent resolve
# and cache mappings automatically (mappingsAuto=true).
java -javaagent:bcdebug-javaagent.jar=logLevel=DEBUG,hookProfile=1.21,mappingsAuto=true,logFile=true -jar server.jar nogui

# Standalone test
java -javaagent:bcdebug-javaagent.jar=logLevel=DEBUG,classfilters=dev.blockconnect.bcagent.test -cp test-classes dev.blockconnect.bcagent.test.TestTarget

MDL (v26.2.0+) can register the agent persistently per instance:

mdl javaagent install <instance> bcdebug-javaagent.jar --params "hookProfile=auto,logFile=true"
mdl javaagent list <instance>

With enableHttp=true the agent prefers the JDK com.sun.net.httpserver frontend. In environments where that module is not linkable from bootstrap code (notably bundler-based dedicated servers), it automatically degrades to a raw-socket implementation serving the same endpoints.

• Legacy-version name obfuscation: stock Mojang jars for 1.20.x/1.21.x ship with obfuscated class and method names (aqu.a style); only entry points keep real names. Provide mappingsFile=<client.txt|server.txt> so hook targets written in Mojang names are translated to runtime names — classes and methods, with JVM descriptors disambiguating overloads. MC 26.x ships unobfuscated and needs no mappings.
• Method statistics report deobfuscated class and method names when mappings are active; unresolved methods keep their runtime names, and JVM descriptors always contain runtime references. Hook target classes are auto-added as dynamic statistics filters on translation; broader game-code coverage on legacy jars still needs manual classfilters prefixes.
• 1.12 profile remains planned (requires legacy JDK 8 artifact).

With hookProfile=auto (default), the agent resolves the active profile at startup:

1. System property bcdebug.mcversion=<ver> (explicit override)
2. System property minecraft.version
3. version.json in the game root (official launcher layout)
4. First versions/*/version.json under the game root

When detection fails, the default provider set (MC 26.x) is activated. The agent bytecode targets release 17, so the same fatJar loads on JDK 17+ game JVMs.

MIT License — Copyright (c) 2026 BlockConnect