MeshBridge

MeshBridge connects a network of Paper servers into a single mesh over Redis. Every server is a peer publishing and subscribing on the same channel; there's no central hub. Together they share a live view of who's online and which servers are up, and can query each other in real time.

Requirements

• Paper (or a Paper fork) for Minecraft 26.2
• Java 25
• A reachable Redis server (6.0+ if you want ACL username/password auth)

Installation

1. Grab the latest MeshBridge-<version>-all.jar from Releases, or build it yourself:

   ./gradlew shadowJar
   

   The output jar will be in build/libs/.
2. Drop it in your server's plugins/ folder and start the server once to generate config.yml.
3. Edit plugins/MeshBridge/config.yml to point at your Redis instance (see below).
4. Give every server in your network a unique server-id, and make sure they all use the same channel.
5. Restart. You should see Connected to Redis at <host>:<port> in the console.

Configuration

redis:
  host: localhost
  port: 6379
  username: ""
  password: ""
  database: 0

server-id: server-1
channel: meshbridge

discovery:
  heartbeat-interval-seconds: 15
  timeout-seconds: 45

Key	Description
redis.host / redis.port	Where your Redis server is reachable.
redis.username	Only needed if your Redis uses ACL-based auth (Redis 6+). Leave blank for legacy password-only auth.
redis.password	Leave blank if your Redis has no auth configured.
redis.database	Redis logical database index.
server-id	This server's unique name on the network. Must be different on every server.
channel	The shared Redis pub/sub channel every server in the mesh talks on. Must be identical on every server.
discovery.heartbeat-interval-seconds	How often a server announces that it's still up.
discovery.timeout-seconds	How long a server can go quiet before the rest of the network considers it offline. Has to be longer than the heartbeat interval.

The config is read once at startup, so editing it on a running server does nothing until the next restart. Values that don't make sense get logged and replaced with a working default rather than left to misbehave quietly.

If you're using a managed or shared Redis instance, some providers issue ACL credentials restricted to a key pattern, like myapp:*. That restriction usually doesn't cover pub/sub channels, since Redis governs channel access separately from key access. A NOPERM error on startup means channel needs to match whatever channel pattern your provider actually grants that user.

What it does

Connects to Redis and subscribes to the configured channel. MeshBridge refuses to enable without a working connection rather than running as a no-op. If the connection drops later it retries with backoff and re-announces itself once the subscription is actually live again.

Tracks player presence across the whole network, not just the local server. A starting server announces the players it already has and asks everyone else to do the same, so it catches up right away. Players moving between servers are handled correctly no matter which of the two announcements lands first.

Tracks which servers are up through periodic heartbeats. A server that stops heartbeating gets dropped once the timeout passes, and its players go with it. Every server works this out independently from the same heartbeats, so nothing extra goes over the wire. A clean shutdown announces itself instead of waiting to be timed out.

Sends messages as typed, structured data rather than raw strings. Each one carries a message id so redeliveries are ignored, and a protocol version so a server running a mismatched build is skipped with a single warning instead of being misread.

Publishing happens on a background thread. Nothing MeshBridge does puts a Redis round trip on the main server thread.

Building on top of MeshBridge

Other plugins can hook into MeshBridge directly. Add MeshBridge as a softdepend (or depend) in your plugin.yml, then grab the instance:

val meshBridge = Bukkit.getPluginManager().getPlugin("MeshBridge") as MeshBridge

meshBridge.eventBus handles broadcasting and listening for typed messages, with publish(type, payload) and subscribe(type) { event -> ... }. meshBridge.requestBus handles asking the network something and collecting answers, with request(type, payload, ResponseClass::class.java) { responses -> ... } and handle(type) { payload -> ... }. meshBridge.playerRegistry tells you who's online anywhere on the network. meshBridge.serverRegistry tells you which servers are currently online.

Request handlers and finished request callbacks always run on the main server thread, so it's safe to touch Bukkit's API directly inside them. The same goes for playerRegistry, which reads the local player list straight from Bukkit.

eventBus.subscribe handlers are the exception: those run on the Redis subscriber thread, so schedule your own task if one of them needs the Bukkit API. An exception thrown out of a handler gets logged and contained, it won't take the subscription down with it.

A request goes out to the other servers on the mesh and never back to the caller. Servers with no handler for that type still reply, so a request finishes as soon as everyone has answered instead of always running out its timeout. A handler returning null counts as "nothing from here" and adds nothing to the result list. With no other server online the callback fires straight away with an empty list.

serverRegistry.onlineServers() is likewise about the other servers on the mesh and doesn't include the local one. isOnline() does account for it.

Building from source

git clone <this repo>
cd MeshBridge
./gradlew build

Run ./gradlew runServer to spin up a local test server with the plugin pre-installed.