Bridge: the Java plugin, unblocked

Closes #19, closes #20, closes #21.

These were blocked on 'no Maven, no Paper API jar here'. Both were soluble:
repo.papermc.io serves paper-api over plain HTTPS, and the wall behind it was
that Paper's API is compiled against Adventure - javac needs adventure-api,
adventure-key and examination-api on the classpath even though the plugin never
names them. With those, JDK 21's javac + jar are enough.

bridge/ holds the plugin (hello/tick/players/event/bye over stdout), a
dependency-free Json writer split out so it is testable, a SelfTest harness that
is excluded from the jar, and build.mjs. No Maven or Gradle: three source files
with no runtime dependencies, and a second build system to produce a 6 KB jar
would put it out of reach of most people who might want to change it.

Verified by parsing the plugin's REAL output with the app's own parseBridgeLine:
all six message shapes parse, a name carrying a quote, backslash, newline and a
control character round-trips intact, NaN encodes as null, and a log4j2-prefixed
line is still found by the marker.

NOT run inside a live server - there is no Paper instance here. Said plainly in
the plugin README, the protocol doc and the main README.

Author: CaYatur

README.md

@@ -449,9 +449,11 @@ That transport choice is the point: no extra port, no socket, no firewall rule,
 
 The app side is implemented: protocol v1 parsing, and a freshness rule that falls back to RCON the moment the bridge goes quiet — so a crashed plugin cannot leave a frozen TPS on screen.
 
-⚠️ **The Java plugin itself does not exist yet**, so nothing currently emits these lines on a real server. Tracked in #19–#21.
+The plugin itself lives in [`bridge/`](bridge/README.md) and builds with a JDK and Node alone — `node bridge/build.mjs` — no Maven or Gradle. Its output is verified against the app's own parser without needing a Minecraft server.
 
-📖 **[Protocol documentation → `docs/bridge-protocol.md`](docs/bridge-protocol.md)**
+⚠️ It has **not yet been run inside a live server**, so treat the first run as a test.
+
+📖 **[Protocol documentation → `docs/bridge-protocol.md`](docs/bridge-protocol.md)** · **[Plugin README → `bridge/README.md`](bridge/README.md)**
 
 ---
 

bridge/.gitignore

@@ -0,0 +1,2 @@
+build/
+.deps/

bridge/README.md

@@ -0,0 +1,52 @@
+# MSMS Bridge (Java plugin)
+
+Reports what the console cannot: true TPS and **MSPT** read off the tick loop, player positions, and structured world events.
+
+It prints one marked line per message to the server's **standard output** — a stream MSMS already reads. No port, no socket, no firewall rule, no credentials. See [`docs/bridge-protocol.md`](../docs/bridge-protocol.md) for the wire format.
+
+## Build
+
+```bash
+node bridge/build.mjs
+```
+
+Produces `bridge/build/MSMS-Bridge-1.0.0.jar`. Requires **JDK 21+** and Node; compile dependencies are downloaded once into `bridge/.deps/` and cached.
+
+There is no Maven or Gradle here on purpose. The plugin is three small source files with **no runtime dependencies**, and requiring a second build system to produce a 6 KB jar would put it out of reach of most people who want to change it.
+
+## Install
+
+Drop the jar into your server's `plugins/` folder and restart. Works on Paper and its forks (Purpur, Folia) and on any Bukkit-API server that provides `getTPS()`.
+
+`config.yml`:
+
+```yaml
+# How often the bridge reports TPS, MSPT and player positions.
+interval-seconds: 5
+```
+
+MSMS picks the bridge up automatically — the Dashboard starts showing **ms/tick** and "Bridge active" once the first `hello` arrives, and falls back to RCON within ~2.5 intervals if the plugin stops reporting.
+
+## Verify the wire format without a server
+
+```bash
+node bridge/build.mjs --selftest
+```
+
+Prints one of every message shape — built with the **same** `Json` helpers the plugin uses — including a player name carrying a quote, a backslash, a newline and a control character, and a line wrapped in a log4j2 prefix. Pipe it through the app's `parseBridgeLine` to confirm end-to-end conformance.
+
+## Layout
+
+| | |
+|---|---|
+| `MsmsBridge.java` | the plugin: hello / tick / players / event / bye |
+| `Json.java` | dependency-free JSON writing, split out so it is testable |
+| `SelfTest.java` | prints every message shape; **not** shipped in the jar |
+| `build.mjs` | fetch deps, compile, package |
+
+## Status and limits
+
+- **Not run against a live Minecraft server in development.** The jar compiles against the Paper 1.21.4 API and its output is verified byte-for-byte against the app's parser, but no one has watched it start inside a real server here. Treat the first run as a test.
+- `getAverageTickTime()` and `getTPS()` are Paper/Spigot extensions. A server that lacks them will not load the plugin.
+- The heartbeat runs on the **main thread** — reading the player list and their locations is main-thread state. It is a handful of field reads every few seconds, but it is not free.
+- Events are currently only `player.death`. Joins and leaves are deliberately left to the console parser, which already handles them, so the two do not double-count.

bridge/build.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Build the MSMS Bridge plugin jar with nothing but a JDK and Node.
+ *
+ * Deliberately not Maven or Gradle. The whole plugin is three small source
+ * files with no runtime dependencies, and requiring a second build system to
+ * produce a 6 KB jar would make it something most contributors cannot build.
+ * Compile dependencies are fetched once into `bridge/.deps/` and cached.
+ *
+ *   node bridge/build.mjs            build the jar
+ *   node bridge/build.mjs --selftest build, then verify the wire format
+ */
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, existsSync, writeFileSync, copyFileSync, rmSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const DEPS = join(HERE, '.deps')
+const OUT = join(HERE, 'build')
+const CLASSES = join(OUT, 'classes')
+
+/**
+ * Paper's API is compiled against Adventure, and javac needs those class files
+ * on the classpath even though the plugin never names them itself.
+ */
+const DEPENDENCIES = [
+  {
+    name: 'paper-api.jar',
+    url:
+      'https://repo.papermc.io/repository/maven-public/io/papermc/paper/paper-api/' +
+      '1.21.4-R0.1-SNAPSHOT/paper-api-1.21.4-R0.1-20250925.065901-231.jar'
+  },
+  { name: 'adventure-api.jar', url: mvn('net/kyori', 'adventure-api', '4.17.0') },
+  { name: 'adventure-key.jar', url: mvn('net/kyori', 'adventure-key', '4.17.0') },
+  { name: 'examination-api.jar', url: mvn('net/kyori', 'examination-api', '1.3.0') }
+]
+
+function mvn(group, artifact, version) {
+  return `https://repo1.maven.org/maven2/${group}/${artifact}/${version}/${artifact}-${version}.jar`
+}
+
+async function fetchDeps() {
+  mkdirSync(DEPS, { recursive: true })
+  for (const d of DEPENDENCIES) {
+    const dest = join(DEPS, d.name)
+    if (existsSync(dest)) continue
+    process.stdout.write(`fetching ${d.name}… `)
+    const r = await fetch(d.url)
+    if (!r.ok) throw new Error(`${d.name}: HTTP ${r.status}`)
+    const buf = Buffer.from(await r.arrayBuffer())
+    if (buf.length === 0) throw new Error(`${d.name}: empty download`)
+    writeFileSync(dest, buf)
+    console.log(`${buf.length} bytes`)
+  }
+}
+
+const sep = process.platform === 'win32' ? ';' : ':'
+const cp = () => DEPENDENCIES.map((d) => join(DEPS, d.name)).join(sep)
+const run = (cmd, args) => execFileSync(cmd, args, { stdio: 'inherit' })
+
+const SRC = join(HERE, 'src', 'main', 'java', 'dev', 'cayadev', 'msms', 'bridge')
+const RES = join(HERE, 'src', 'main', 'resources')
+
+async function build({ selftest }) {
+  await fetchDeps()
+  rmSync(CLASSES, { recursive: true, force: true })
+  mkdirSync(CLASSES, { recursive: true })
+
+  const sources = readdirSync(SRC)
+    .filter((f) => f.endsWith('.java'))
+    // SelfTest is a harness, not part of the plugin.
+    .filter((f) => selftest || f !== 'SelfTest.java')
+    .map((f) => join(SRC, f))
+
+  console.log('compiling…')
+  run('javac', ['-encoding', 'UTF-8', '--release', '21', '-cp', cp(), '-d', CLASSES, ...sources])
+
+  if (selftest) {
+    console.log('--- self test output ---')
+    run('java', ['-cp', CLASSES, 'dev.cayadev.msms.bridge.SelfTest'])
+    return
+  }
+
+  for (const f of readdirSync(RES)) copyFileSync(join(RES, f), join(CLASSES, f))
+  const jar = join(OUT, 'MSMS-Bridge-1.0.0.jar')
+  run('jar', ['--create', '--file', jar, '-C', CLASSES, '.'])
+  console.log(`\nbuilt ${jar}`)
+  console.log('Drop it in your server\'s plugins/ folder and restart.')
+}
+
+build({ selftest: process.argv.includes('--selftest') }).catch((e) => {
+  console.error('build failed:', e.message)
+  process.exit(1)
+})

bridge/src/main/java/dev/cayadev/msms/bridge/Json.java

@@ -0,0 +1,60 @@
+package dev.cayadev.msms.bridge;
+
+/**
+ * Minimal JSON writing, deliberately dependency-free.
+ *
+ * Split out of {@link MsmsBridge} so it can be exercised without a running
+ * Minecraft server: {@link SelfTest} prints one of every message shape through
+ * these helpers, and the repository's protocol parser reads them back. That is
+ * the only part of the bridge whose correctness the app depends on.
+ */
+final class Json {
+
+    private Json() {
+    }
+
+    /** JSON number, or `null` for anything not finite - NaN is not valid JSON. */
+    static String num(double d) {
+        if (Double.isNaN(d) || Double.isInfinite(d)) return "null";
+        return String.valueOf(Math.round(d * 100.0) / 100.0);
+    }
+
+    /**
+     * A quoted, escaped string. Control characters are escaped rather than
+     * passed through: a raw newline in a player name would split the line and
+     * the message would arrive as two unparsable halves.
+     */
+    static String str(String s) {
+        StringBuilder b = new StringBuilder("\"");
+        for (int i = 0; i < s.length(); i++) {
+            char c = s.charAt(i);
+            switch (c) {
+                case '"':
+                    b.append("\\\"");
+                    break;
+                case '\\':
+                    b.append("\\\\");
+                    break;
+                case '\n':
+                    b.append("\\n");
+                    break;
+                case '\r':
+                    b.append("\\r");
+                    break;
+                case '\t':
+                    b.append("\\t");
+                    break;
+                default:
+                    if (c < 0x20) b.append(String.format("\\u%04x", (int) c));
+                    else b.append(c);
+            }
+        }
+        return b.append('"').toString();
+    }
+
+    /** Append `,"key":"value"`, skipping a null value entirely. */
+    static void field(StringBuilder b, String key, String value) {
+        if (value == null) return;
+        b.append(",\"").append(key).append("\":").append(str(value));
+    }
+}

bridge/src/main/java/dev/cayadev/msms/bridge/MsmsBridge.java

@@ -0,0 +1,153 @@
+package dev.cayadev.msms.bridge;
+
+import org.bukkit.Bukkit;
+import org.bukkit.Location;
+import org.bukkit.World;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.Listener;
+import org.bukkit.event.entity.PlayerDeathEvent;
+import org.bukkit.plugin.java.JavaPlugin;
+
+import java.util.List;
+
+/**
+ * MSMS Bridge - reports telemetry the console cannot otherwise expose.
+ *
+ * Transport is the server's own standard output: one marked line per message.
+ * That needs no port, no socket, no firewall rule and no credentials, and it
+ * works identically for a LAN server, a box behind NAT, and a host with every
+ * port closed. See docs/bridge-protocol.md for the wire format.
+ *
+ * Everything here runs on the main thread and does almost nothing: reading the
+ * tick rate and the player list must not itself become a source of lag.
+ */
+public final class MsmsBridge extends JavaPlugin implements Listener {
+
+    private static final String MARKER = "[MSMS-BRIDGE]";
+    private static final int PROTOCOL = 1;
+
+    private long intervalMs;
+
+    @Override
+    public void onEnable() {
+        saveDefaultConfig();
+        int seconds = Math.max(1, getConfig().getInt("interval-seconds", 5));
+        this.intervalMs = seconds * 1000L;
+
+        emitHello();
+        getServer().getPluginManager().registerEvents(this, this);
+
+        // Sync, because the player list and their locations are main-thread
+        // state. The work is a handful of field reads every few seconds.
+        long ticks = seconds * 20L;
+        getServer().getScheduler().runTaskTimer(this, this::heartbeat, ticks, ticks);
+    }
+
+    @Override
+    public void onDisable() {
+        emit("{\"v\":" + PROTOCOL + ",\"t\":\"bye\"}");
+    }
+
+    // ---- messages ----
+
+    private void emitHello() {
+        StringBuilder b = new StringBuilder();
+        b.append("{\"v\":").append(PROTOCOL).append(",\"t\":\"hello\"");
+        Json.field(b, "plugin", getName());
+        Json.field(b, "pluginVersion", getPluginMeta().getVersion());
+        Json.field(b, "server", getServer().getName());
+        Json.field(b, "mc", getServer().getMinecraftVersion());
+        b.append(",\"interval\":").append(intervalMs);
+        b.append("}");
+        emit(b.toString());
+    }
+
+    private void heartbeat() {
+        emitTick();
+        emitPlayers();
+    }
+
+    private void emitTick() {
+        double[] tps = getServer().getTPS();
+        StringBuilder b = new StringBuilder();
+        b.append("{\"v\":").append(PROTOCOL).append(",\"t\":\"tick\"");
+        // The app treats these as reported and does no clamping, so a warming-up
+        // server showing 20.4 stays visible rather than being tidied away.
+        b.append(",\"tps\":").append(Json.num(tps.length > 0 ? tps[0] : Double.NaN));
+        b.append(",\"tps5\":").append(Json.num(tps.length > 1 ? tps[1] : Double.NaN));
+        b.append(",\"tps15\":").append(Json.num(tps.length > 2 ? tps[2] : Double.NaN));
+        b.append(",\"mspt\":").append(Json.num(getServer().getAverageTickTime()));
+        b.append("}");
+        emit(b.toString());
+    }
+
+    private void emitPlayers() {
+        List<? extends Player> online = List.copyOf(getServer().getOnlinePlayers());
+        StringBuilder b = new StringBuilder();
+        b.append("{\"v\":").append(PROTOCOL).append(",\"t\":\"players\",\"online\":").append(online.size());
+        b.append(",\"list\":[");
+        boolean first = true;
+        for (Player p : online) {
+            if (!first) b.append(',');
+            first = false;
+            Location loc = p.getLocation();
+            World w = loc.getWorld();
+            b.append('{');
+            b.append("\"name\":").append(Json.str(p.getName()));
+            b.append(",\"uuid\":").append(Json.str(p.getUniqueId().toString()));
+            if (w != null) {
+                b.append(",\"world\":").append(Json.str(w.getName()));
+                b.append(",\"dim\":").append(Json.str(dimension(w)));
+            }
+            b.append(",\"x\":").append(Json.num(loc.getX()));
+            b.append(",\"y\":").append(Json.num(loc.getY()));
+            b.append(",\"z\":").append(Json.num(loc.getZ()));
+            b.append('}');
+        }
+        b.append("]}");
+        emit(b.toString());
+    }
+
+    @EventHandler
+    public void onDeath(PlayerDeathEvent e) {
+        // A death is exactly the kind of thing the console cannot report in a
+        // structured way - the death message is free text and locale-dependent.
+        Player p = e.getEntity();
+        Location loc = p.getLocation();
+        World w = loc.getWorld();
+        StringBuilder b = new StringBuilder();
+        b.append("{\"v\":").append(PROTOCOL).append(",\"t\":\"event\",\"kind\":\"player.death\"");
+        Json.field(b, "text", p.getName());
+        b.append(",\"data\":{");
+        b.append("\"player\":").append(Json.str(p.getName()));
+        if (w != null) b.append(",\"world\":").append(Json.str(w.getName()));
+        b.append(",\"x\":").append(Json.num(loc.getX()));
+        b.append(",\"y\":").append(Json.num(loc.getY()));
+        b.append(",\"z\":").append(Json.num(loc.getZ()));
+        b.append("}}");
+        emit(b.toString());
+    }
+
+    // ---- plumbing ----
+
+    private static String dimension(World w) {
+        switch (w.getEnvironment()) {
+            case NETHER:
+                return "nether";
+            case THE_END:
+                return "the_end";
+            default:
+                return "overworld";
+        }
+    }
+
+    /**
+     * One message per line. A newline inside the payload would split the
+     * message, so every string is escaped and nothing is pretty-printed.
+     */
+    private void emit(String json) {
+        System.out.println(MARKER + " " + json);
+    }
+
+}