VelocityVersionBouncer

VelocityVersionBouncer

A simple and fully automated way to connect players to the correct server based on their game version.

VelocityVersionBouncer is a plugin for the Velocity proxy that automatically selects the most compatible backend server for a connecting player, based on their protocol version (Minecraft game version).

---

🔧 How It Works

• Every time a client connects to your proxy the plugin will check all the registered servers and compare their protocol versions (game versions).
• By default, the first server that matches will be selected (you can change that in the config).
• There is a config file located in the plugins folder (plugins/velocityversionbouncer/config.toml).
• The clients can be routed automatically or based on the explicit routings set in the config.
• Optional features include: a fallback functionality as well as comparing versions for server list pings.
• You can also change the plugin's language (currently en_US, zh_CN and de_DE are available).

❓ Questions you may have:

• Is this also triggered when changing servers via /server? No, the version checking is only triggered when connecting initially (from the multiplayer server list) or when using the fallback functionality.
• What happens if no compatible server is found? The client will simply be disconnected with the according note/reason.
• Does this work with modded Minecraft servers? If you're using setups like Ambassador+ProxyCompatibleForge (more information) this plugin will route the client based on their protocol version (game version) and also checks whether the installed mods are accepted by the backend servers.

📦 Installation & 🛠️ Requirements

1. Download the .jar file of the last stable release (here) or build it yourself (the Gradle files are included).
2. Put the file in your server's plugins/ folder (only the proxy!) and restart the server once to generate the config file at plugins/velocityversionbouncer/config.toml.
3. When you're finished editing the config restart the proxy once more and everything should be working.
   Note: This plugin may not work properly if you are not running on Java 25 (or higher) and Velocity 4.2.1 (or higher).
4. If you're having problems: make sure you're not using a snapshot (as these are expected to be unstable and this README is always explaining the latest release anyway), if there's still a problem feel free to open an issue on the plugin's GitHub repository.

Compatibility

• VelocityVersionBouncer is built for the Velocity proxy (other proxies or forks may work, but they are not officially supported).
• Before v2.X.X VelocityVersionBouncer was compiled against Java 21 and Velocity 3.4.0, so to support Java 21 or Velocity 3.4.0 - 4.2.1 you may need to downgrade VelocityVersionBouncer to 1.6.0-release or 1.6.1-SNAPSHOT.
• You can of course also fork the project and compile against other versions. Most parts should work exactly the same.

Example Config:

# This config is used to determine how and if servers are checked for their protocol versions whenever a client tries to connect to a backend server (and optionally if they lost connection)

# en_US zh_CN de_DE
language = "en_US"

# 'whitelist' is a string array of server names to check for their protocol version when a client tries to connect.
# leaving this empty is equal to putting all registered servers in
# Example: ["server1", "server2"]
# Note: spaces outside the strings will be ignored.
whitelist = ["lobby1", "lobby2", "fun-minigame", "devServer", "best-modpack"]

# 'blacklist' is an array of strings to exclude from the temporary list of servers during version comparison.
# first the whitelist is added and then all servers contained in the blacklist are removed from that temporary list.
blacklist = ["devServer"]

# 'modded-servers' is an array of servers from the whitelist, which are tried before the unmodded servers to ensure,
# that modded clients don't end up on vanilla servers.
modded-servers = ["best-modpack"]

# If enabled this option ensures that joining players will be distributed evenly over all servers
# Options: (case-insensitive)
#   "FIRST-MATCH" - players will be sent to the first matching server
#   "BALANCED" - players will be evenly distributed over all matching servers
distribution = "FIRST-MATCH"

# This option if set to 'true' lets you override verlocity's way of determining the server list ping response by using the try-list of the config ('ping-passthrough')
# instead when a client sends a server ping it will use the same algorithm to determine a matching server as in the joining/fallback process
# be carefully when also using clientbrands in the explicit routings as these can't be used to match server pings
server-list-ping = false
# This option determines wether to use velocities ping-passthrough when no matching server was found for the ping response
# If set to true, things like the description will probably show but the client shows that the version doesn't match,
# otherwise the client will display "Can't connect to server"
# This option will also be ignored if 'server-list-ping' is set to false
default-to-ping-passthrough = true

# This defines how often all backend servers get pinged to refresh infos in the plugins ping cache
# in seconds
ping-intervall = 300

# If enabled this option ensures that whenever a client is kicked from a server (whether during login, via /kick, or for another reason),
# they will be automatically redirected (bounced) to another server instead of being disconnected. If a client disconnects explicitly via leaving the server they will not be redirected.
# The server the client was kicked from will be temporarily excluded from the fallback options.
# This prevents the client from being sent back there during fallback-bouncing and therefore also preventing a possible infinite loop.
enable-fallback-bouncing = true
# When there is a valid server name in 'explicit-fallback-server' the plugin won't search for a new server and instead only tries the specified server.
# Leave this empty, if you'd like to disable this option (also this is disabled when enable-fallback-bouncing is set to false).
# WARNING: this will not check whether the versions match or not
explicit-fallback-server = "lobby"

# ------ explicit routing ------
# Syntax
#   vX_X_X - game version
#   p000 - protocol version (Protocol version numbers for every release/snapshot can be found here: https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol_version_numbers)
#   cXYZ - Client brand (for example: vanilla, forge, fabric, Geyser (for player joining through GeyserMC), badlion, etc.
# either a game version (v) or a protocol version (p) is necessary but client brands (c) are completely optional
# when no client brand is defined the routing just takes every client joining with the defined game/protocol version
[explicit-routing]
# Example: v1_21_8cFORGE = "lobby-1"
# Example: p123 = "lobby-2"
# Example: cGeyser = "GeyserMC-server"