MCME-Connect links MCME's servers into one network. On the Velocity proxy it handles teleports between players on different servers, server switching, restart orchestration, a server watchdog and join/leave messages; on each Paper backend it carries out what the proxy asks (teleports, commands, titles, restarts), syncs player statistics to MySQL and fires an event other plugins use to react to arrivals. The same jar goes on the proxy and on every backend. This page describes 3.1.1, the latest release, from MCME/MCME-Connect.

At a glance

BungeeCord and Waterfall support was removed in 3.0.0; the code is Velocity-only.

How the code is organised

Everything lives under com.mcmiddleearth.connect:

The proxy's commands are thin: each ConnectCommand does nothing in execute. CommandListener catches the command in Velocity's CommandExecuteEvent and passes it to CommandHandler. If the target is on another server, Connect handles it and the command stops there. If not (for example /tp to a player on your own server), the command is forwarded to the backend, where EssentialsX or vanilla answers it.

Building and testing

mvn clean verify

This runs the tests and builds the shaded jar target/MCME-Connect-<version>-<TYPE>-<commit>.jar. TYPE is RELEASE unless you pass -Dbuild.type=DEV; commit is the short hash, so two builds of one version can be told apart.

• JDK 25 is needed because paper-api 26.2 and mcme-base are Java 25 bytecode. The compiler emits Java 21 bytecode because maven-shade-plugin 3.5.3 cannot read Java 25 classes.
• Dependencies resolve from the MCME Maven repository (releases, snapshots, mirror), with the upstream repositories as fallbacks. mcme-base 2.0.1 and PluginUtils 2.0.2 are provided; mysql-connector-j and tbnbt are shaded into the jar.
• velocity-plugin.json is generated from the @Plugin annotation. Its version is a literal, so a release must change the version in pom.xml and in ConnectVelocityPlugin. VelocityPluginDescriptorTest fails the build when they differ.
• Tests are JUnit 5: PluginMessageHandlerTest, StatisticSnapshotTest, VelocityPluginDescriptorTest and HarnessTest.

CI (.github/workflows/build.yml) rejects version ranges in the pom, then builds and tests every push and pull request and keeps the jar as a workflow artifact. A v* tag must match the pom version and have a ## [X.Y.Z] section in CHANGELOG.md; it then deploys com.mcmiddleearth:MCME-Connect to repo.mcmiddleearth.com and creates the GitHub release "version X.Y.Z for mc 26.2" with the jar, its SHA-256 and the changelog section. A manual run (workflow_dispatch) also deploys to the Maven repository.

Configuration

One config.yml in the plugin folder, from the same file in the jar. Each side reads its own keys. The shipped file holds only proxy keys; the others take the built-in value shown.

Proxy keys

Backend keys

Other files: the proxy keeps playerServers.yml (each player's last server, used to pick the server they join), and both sides use a restart.nfo marker file: scheduled restarts and /restart expect a start script that starts the server again while the file exists. First-join date sync reads player data from a playerdata folder inside the plugin folder (see the comment in config.yml) and needs PluginUtils.

Commands and permissions

Most checks run on the proxy, which ignores plugin.yml defaults. Grant the nodes in the proxy's permission plugin as well as on the backends.

Proxy commands

From the proxy console, /reboot restarts the proxy.

Backend commands (declared in plugin.yml)

Permission nodes

mcmeconnect.tablist is still declared in plugin.yml but nothing checks it since the tab list was removed in 3.0.3.

APIs and extension points

Other backend plugins can depend on Connect (Maven: com.mcmiddleearth:MCME-Connect, provided, from the Maven repository) and use:

• com.mcmiddleearth.connect.events.PlayerConnectEvent, a Bukkit event fired on the backend once the proxy reports that a player arrived. getReason() returns a ConnectReason: JOIN_PROXY, COMMAND, KICK_REDIRECT, LOBBY_FALLBACK, PLUGIN, PLUGIN_MESSAGE, SERVER_DOWN_REDIRECT or UNKNOWN. Use it instead of PlayerJoinEvent when you need to know the player really arrived through the proxy.
• com.mcmiddleearth.connect.util.ConnectUtil, static helpers that send messages to the proxy through a player's connection:
  • teleportPlayer(Player, String server, String world, Location): teleport a player to a spot on any server.
  • sendMessage(Player sender, String server, String recipient, String message, int delay): deliver a chat line. An empty server and recipient ("") means every player on the network. The text arrives as legacy text, so click and hover events are lost.
  • sendTitle(Player sender, String server, String recipient, String title, String subtitle, int intro, int show, int extro, int delay): show a title.
  • sendDiscord(String discordChannel, String message): post to a DiscordSRV channel from this backend; @Name words become role or user mentions.

How it talks to other plugins and systems

Both halves use one plugin-message channel, mcme:connect. Every message starts with a UTF string naming the sub-channel, followed by that sub-channel's fields (Guava ByteArrayDataOutput). The proxy accepts mcme:connect messages only from backend servers, never from a player's client.

A multi-server /reboot hops: the proxy moves the issuing player to the first server and sends restart with the rest of the list; that backend restarts itself about three seconds later and sends the list back through the player, and the proxy continues only if the player has mcmeconnect.restart.

flowchart LR
    subgraph Proxy
        CV[MCME-Connect proxy plugin]
        MB1[mcme-base]
    end
    subgraph Backend
        CP[MCME-Connect backend plugin]
        MB2[MCME-Base]
        DS[DiscordSRV]
        PV[PremiumVanish]
        MV[Multiverse-Core]
        PU[PluginUtils]
        IN[MCME-Introduction]
        AR[MCME-Architect]
    end
    DB[(MySQL statistics)]
    CV ---|mcme:connect| CP
    CV --> MB1
    CP --> MB2
    CP --> DS
    CP --> PV
    CP --> MV
    CP --> PU
    CP ---|JDBC| DB
    IN -->|PlayerConnectEvent and ConnectUtil| CP
    AR -->|PlayerConnectEvent| CP

When a backend kicks a player (other than for idling or an unsupported client), the proxy tries to redirect them to a fallback server; the server names are hard-coded in ConnectionHandler.handleKick.

Further reading

• README and CHANGELOG on GitHub
• Setting up, Maven repository, mcme-base