Velocity Limbo Handler

VLH 2.0.0 adds a public Developer API, so other Velocity plugins can work with limbo and the reconnect queue. For server owners it's a drop-in upgrade from 1.8.x.

New features

• Developer API v1: Velocity plugins can move players into limbo, pause players or whole servers with holds, change a player's destination, read queue state, and react to limbo events. See the Developer API v1 guide.
• Holds in /vlh status: The status command now shows how many players and servers are currently held.
• Version checker: On startup, VLH checks for a newer release in the background and logs a download link if one is available. Startup continues normally if the check fails.
• Debug option: Set debug: true to log virtual-host resolution, queue assignment, and ping results when troubleshooting a setup or plugin conflict.

Improvements

• Performance on large networks: Queue lookups are indexed and queue positions are cached. Only queues with players waiting are processed. Backend pings are coalesced, cached briefly, and back off for servers that are offline.
• Tuning options: reconnect-batch-size (default 8) and queue-notify-batch-size (default 64) spread reconnect and notification work across ticks, so large networks can balance catch-up speed against scheduler load.
• Safer reloads and startup: /vlh reload applies the new configuration all at once and rejects invalid server names instead of half-applying them. VLH stops at startup if the configuration can't be loaded.

Fixes

• Players are recovered correctly after their backend disconnects.
• Maintenance status is rechecked after backend pings.
• Disconnect reason matching no longer depends on the server's locale.
• Scheduled work is cancelled cleanly on proxy shutdown.

Upgrading

• Replace the plugin JAR. Your existing config.yml is updated automatically with the new options, and no other changes are needed.
• Java 21 is still required.
• VLH is now licensed under MIT (previously GPL-3.0).

For developers

Add the API as a compileOnly/provided dependency from JitPack, and declare velocity-limbo-handler as a required Velocity dependency. Don't shade it.

compileOnly("com.github.AkselGlyholt.velocity-limbo-handler:velocity-limbo-handler-api:v2.0.0")

The internal getPlayerManager() and getReconnectBlocker() accessors are deprecated. Use VelocityLimboApi.get(proxy) instead.

What's Changed

• Debug option by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pull/78
• Optimize queue processing and runtime resource usage by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pull/81
• Version checker by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pull/83
• feat(api): add stable developer API v1 by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pull/82

Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/compare/v1.8.3...v2.0.0