Plugin Messaging Skill — Waterfall
Purpose
Reference this skill when a Waterfall proxy plugin needs to send or receive plugin messages to/from backend Paper/Purpur servers via the BungeeCord channel or custom plugin channels.
When to Use This Skill
- Intercepting
BungeeCordchannel messages at the proxy - Building custom backend ↔ proxy communication on Waterfall
- Forwarding messages between backend servers via the proxy
API Quick Reference
| Class / Method | Purpose | Notes |
|---|---|---|
ProxyServer#registerChannel(String) |
Register a channel for listening | Must be called before handling messages |
ProxyServer#unregisterChannel(String) |
Unregister a channel | Call in onDisable |
PluginMessageEvent |
Fires when a plugin message arrives at the proxy | net.md_5.bungee.api.event.PluginMessageEvent |
event.getSender() |
Connection |
The backend server or player who sent it |
event.getReceiver() |
Connection |
The destination |
event.getData() |
byte[] |
Raw payload |
event.setCancelled(boolean) |
Prevent forwarding | Use when handling internally |
event.getTag() |
String |
The channel name |
ProxiedPlayer#sendData(String, byte[]) |
Send plugin message to player's backend | Proxy → Backend |
Code Pattern
package com.yourorg.waterfallplugin.messaging;
import com.google.common.io.ByteArrayDataInput;
import com.google.common.io.ByteArrayDataOutput;
import com.google.common.io.ByteStreams;
import net.md_5.bungee.api.ProxyServer;
import net.md_5.bungee.api.chat.TextComponent;
import net.md_5.bungee.api.config.ServerInfo;
import net.md_5.bungee.api.connection.ProxiedPlayer;
import net.md_5.bungee.api.connection.Server;
import net.md_5.bungee.api.event.PluginMessageEvent;
import net.md_5.bungee.api.plugin.Listener;
import net.md_5.bungee.api.plugin.Plugin;
import net.md_5.bungee.event.EventHandler;
import java.util.logging.Logger;
public class WaterfallMessagingHandler implements Listener {
private static final String CUSTOM_CHANNEL = "myplugin:network";
private static final String BUNGEE_CHANNEL = "BungeeCord";
private final Plugin plugin;
private final Logger logger;
public WaterfallMessagingHandler(Plugin plugin) {
this.plugin = plugin;
this.logger = plugin.getLogger();
}
public void register() {
ProxyServer proxy = plugin.getProxy();
proxy.registerChannel(CUSTOM_CHANNEL);
// BungeeCord channel is always registered by Waterfall itself
proxy.getPluginManager().registerListener(plugin, this);
}
public void unregister() {
plugin.getProxy().unregisterChannel(CUSTOM_CHANNEL);
}
@EventHandler
public void onPluginMessage(PluginMessageEvent event) {
String tag = event.getTag();
if (CUSTOM_CHANNEL.equals(tag)) {
handleCustomMessage(event);
} else if (BUNGEE_CHANNEL.equals(tag)) {
handleBungeeCordMessage(event);
}
}
private void handleCustomMessage(PluginMessageEvent event) {
// Only handle messages from backend servers
if (!(event.getSender() instanceof Server backendServer)) return;
ByteArrayDataInput in = ByteStreams.newDataInput(event.getData());
String action = in.readUTF();
switch (action) {
case "BROADCAST" -> {
String message = in.readUTF();
plugin.getProxy().broadcast(new TextComponent("§6[Network] §f" + message));
event.setCancelled(true); // Don't forward to player
}
case "MOVE_PLAYER" -> {
String playerName = in.readUTF();
String targetServer = in.readUTF();
movePlayer(playerName, targetServer);
event.setCancelled(true);
}
case "GET_PLAYER_COUNT" -> {
int count = plugin.getProxy().getOnlineCount();
respondToBackend(event, "PLAYER_COUNT_RESPONSE", out -> out.writeInt(count));
event.setCancelled(true);
}
default -> logger.warning("Unknown action: " + action);
}
}
private void handleBungeeCordMessage(PluginMessageEvent event) {
// Intercept specific BungeeCord sub-channels for logging/auditing
ByteArrayDataInput in = ByteStreams.newDataInput(event.getData());
String subChannel = in.readUTF();
if ("Connect".equals(subChannel)) {
String targetServer = in.readUTF();
logger.info("BungeeCord Connect request → " + targetServer);
// Allow Waterfall to process it normally
}
// Most BungeeCord sub-channels should be forwarded — don't cancel them
}
private void movePlayer(String playerName, String targetServer) {
ProxiedPlayer player = plugin.getProxy().getPlayer(playerName);
if (player == null) return;
ServerInfo server = plugin.getProxy().getServerInfo(targetServer);
if (server == null) return;
player.connect(server);
}
private void respondToBackend(PluginMessageEvent event,
String responseAction,
java.util.function.Consumer<ByteArrayDataOutput> writer) {
if (!(event.getReceiver() instanceof ProxiedPlayer player)) return;
ByteArrayDataOutput out = ByteStreams.newDataOutput();
out.writeUTF(responseAction);
writer.accept(out);
player.sendData(CUSTOM_CHANNEL, out.toByteArray());
}
// Send from proxy → specific backend server
public void sendToServer(String serverName, byte[] data) {
// Must route via an online player on that server
plugin.getProxy().getPlayers().stream()
.filter(p -> p.getServer() != null
&& serverName.equals(p.getServer().getInfo().getName()))
.findFirst()
.ifPresent(p -> p.sendData(CUSTOM_CHANNEL, data));
}
}
Register in main class:
private WaterfallMessagingHandler messagingHandler;
@Override
public void onEnable() {
messagingHandler = new WaterfallMessagingHandler(this);
messagingHandler.register();
}
@Override
public void onDisable() {
if (messagingHandler != null) {
messagingHandler.unregister();
}
}
Common Pitfalls
Using
MinecraftChannelIdentifieron Waterfall: This is a Velocity class. On Waterfall, channel names are plain strings ("myplugin:network").Not cancelling
PluginMessageEventwhen handled: If you handle a message internally but don't cancel the event, Waterfall forwards it to the player. Callevent.setCancelled(true)for messages you handle yourself.Cancelling BungeeCord sub-channels: Cancelling built-in
BungeeCordchannel messages (likeConnect,GetServer) prevents Waterfall from processing them. Only cancel if you're fully replacing Waterfall's handling.Sending without a player on that server: To send data from the proxy to a specific backend, you need a player on that backend to route the message. If no player is on the target server, queue the message.
Version Notes
- Waterfall 1.21: Plugin messaging API unchanged from older BungeeCord.
event.getData()returns a byte array. Guava'sByteStreams(bundled with BungeeCord) handles serialization.
Related Skills
- bungeecord-channels.md — Full BungeeCord channel sub-channel reference
- ../events/SKILL.md — Waterfall event system
- ../../paper/messaging/plugin-channels.md — Paper backend messaging
- ../../velocity/messaging/plugin-messages.md — Equivalent Velocity messaging