Waterdog-LobbyBalancer

WaterdogPE plugin for balancing lobbies

中文文档

Lobby servers are gathered from the WaterdogPE config with the lobby prefix. By default, this is lobby.

With the default configuration, lobby1, lobby2, and lobby3 would be detected as lobby servers, but game1 or game2 would not.

You can transfer players to a pseudo-random lobby server by sending a transfer packet with the lobby prefix. By default, /server lobby will send them to a pseudo-random lobby server.

Downloads

Download from Jenkins CI

Building

Build and compile with maven using mvn package

Config

#Any lobbies must start with this string. Anything after it doesn't matter
#Transfers to this prefix will send a player to a lobby, acting the same as if they join
lobbyprefix: lobby

#Minimum players in a lobby before balancing to another server
#A lobby must have x amount of players before another lobby starts getting players
#Helps your server in theory not look dead if all lobbies barely have players
#By default, lobbies below this threshold are prioritized first.
#Once all lobby servers reach the minimum players, the plugin uses randomized least-load selection.
minplayers: 10

#Whether to register the /lobby command
#Set to false to disable the lobby command
lobbycommand: true

#Whether to use MOTD query to get real player counts from downstream servers
#Enable this for multi-proxy deployments where each proxy only knows its own players
#When enabled, player counts are fetched directly from servers via UDP MOTD protocol
use-motd-query: false

#MOTD query interval in seconds
motd-query-interval: 30

#How many random lobby samples to compare for each assignment
#2 is recommended for multi-proxy deployments because it reduces herd effects
#Higher values move closer to strict least-loaded selection
balance-choice-sample-size: 2

#How long a locally assigned transfer should count as pending before expiring
#Set to 0 to automatically derive it from the MOTD interval
pending-transfer-ttl-ms: 0

MOTD Query

In a multi-proxy deployment, each WaterdogPE proxy only knows the players routed through itself. This leads to inaccurate load balancing.

When use-motd-query is enabled, the plugin queries each downstream server directly via UDP MOTD protocol to get the real total player count. Servers that fail to respond are considered offline and excluded from balancing.

Multi-Proxy Burst Protection

To reduce cases where several proxies observe the same stale low player count and all send players to one lobby at once, the balancer now combines two techniques:

1. Randomized least-load selection: sample balance-choice-sample-size lobby candidates with replacement, then choose the one with the lowest effective load.
2. Pending transfer reservations: each proxy temporarily counts the players it has just assigned until the next observed player-count update catches up.

This does not require a shared datastore, but it substantially reduces short burst overshoot compared to strict global least-loaded selection.

Commands/Permissions

Command	Permission	Description
/<lobbyprefix>	lobbybalancer.lobby	Sends executer to a lobby server