Sueta

Velocity Limbo Handler

2.0.0

A simple plugin for handling limbo reconnection/handling

·Plugin
DescriptionUpdates20Version history20AddonsDiscussionReviews
  1. 2.0.0latestVelocity Limbo Handler 2.0.0Sep 28, 2026
    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](https://github.com/AkselGlyholt/velocity-limbo-handler/wi… - 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/pu… * Optimize queue processing and runtime resource usage by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Version checker by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * feat(api): add stable developer API v1 by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    59 downloads
  2. 1.8.3v1.8.3Jun 8, 2026

    v1.8.3

    New features
    - Command blocking message configuration — The message shown when commands are blocked in limbo can now be customized via config. Also includes an updated event listener for command blocking. - Extended placeholders — Additional placeholders are now available for use in messages/config. - Toggleable connection warnings — Connection warning messages can now be enabled or disabled in config.
    Improvements
    - Disconnect reason handling — Refactored to use component inspection instead of string matching, making reason detection more robust and reliable across different server implementations.
    2406 downloads
  3. v1.8.2Velocity Limbo Handler 1.8.2Apr 12, 2026
    Added
    - /vlh reload and /vlh status admin commands. reload hot-reloads the plugin configuration without a server restart; status provides a runtime overview of the handler's current state.
    Changed
    - Refactored internal queue state management for improved reliability and clarity. - Introduced tiered priority to the reconnect queue, allowing higher-priority players or conditions to be processed ahead of the standard queue. This replaces the previous flat queue model.
    717 downloads
  4. 1.8.2-SNAPSHOT-26w07av1.8.2-SNAPSHOT-26w07aFeb 12, 2026

    26w07a Snapshot

    This is a development snapshot. Expect instability. Do not deploy blindly into production. Is more or less stable, but don't trust it 100% ---

    Added

    /vlh Admin Commands
    * Implemented /vlh reload * Implemented /vlh status These commands allow: * Reloading configuration without full proxy restart * Inspecting current limbo handler state ---

    FastStats Integration

    * Integrated FastStats metrics support [faststats.dev](https://www.faststats.dev) --- Full Changelog: [https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    863 downloads
  5. v1.8.1Feb 7, 2026
    📦 Release v1.8.1 ### What's Changed - State Management: Refactored PlayerManager to use UUID-based structures. This fixes stale Player object references and improves memory safety across reconnects. - Logic Fixes: - Fixed a bug in QueueNotifierTask where a single maintenance-queued player would abort the entire task. - Corrected ReconnectionTask maintenance bypass logic to properly handle permissions and whitelists. - Prevented player "starvation" by ensuring failed reconnection attempts no longer block the rest of the group. - Optimizations: Added cached reflective lookups in Utility for maintenance API checks, reducing overhead during heavy reconnect loops. ### 📊 Performance Improvements (May vary depending on setup) - CPU Optimization: Reduced core processing overhead by approximately 35% thanks to more efficient queue handling and cached reflection. - Memory Efficiency: Drastically improved heap management. By migrating to UUIDs and pruning stale references, the memory footprint is reduced by ~50% under load compared to v1.8.0. Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    602 downloads
  6. 1.8.0Velocity Limbo Handler 1.8.0Feb 6, 2026

    v1.8.0

    This release focuses on authentication improvements, internal structure, and developer experience. It also lays groundwork for safer iteration going forward.
    What’s Changed
    Deprecated `auth-timeout`* The legacy auth-timeout option is now deprecated. It remains available for compatibility but should be considered end-of-life. Plan migrations accordingly. PR: #48 Added NLogin authentication support* Introduces first-class support for NLogin, expanding authentication options and improving interoperability. PR: #54 Contributor: @ArturoAtomplay Improved developer experience with JSDoc* Core components are now documented with JSDoc, making the codebase easier to navigate and safer to extend. PR: #57 Added unit tests for core components* Core logic is now covered by unit tests, increasing confidence in refactors and reducing regression risk. PR: #59 Refactor: modularized codebase and extracted core logic* The internal structure has been cleaned up. Core logic is now more modular, easier to reason about, and simpler to test. This is not cosmetic, it materially improves maintainability. PR: #58
    New Contributors
    * @ArturoAtomplay made their first contribution with the NLogin authentication implementation. PR: #54
    Full Changelog
    [https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    67 downloads
  7. v1.8.0-snapshot.26w05aJan 31, 2026
    I've been busy lately, hence the gap in time since the last pre-release. I promise a full and stable release is coming soon!

    What's Changed

    * deprecated auth-timeout by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Add NLogin authentication support by @ArturoAtomplay in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Fix formatting issues in build.yml by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Added JSDoc to improve dev experience by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Add Unit Tests for Core Components by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Refactor: Modularize codebase and extract core logic by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu…

    New Contributors

    * @ArturoAtomplay made their first contribution in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    122 downloads
  8. v1.8.0-snapshot.26w01aJan 5, 2026

    Pre-release! May not be stable

    What's Changed

    * deprecated auth-timeout in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Added nLogin authentication support by in https://github.com/AkselGlyholt/velocity-limbo-handler/pu…

    New Contributors

    * @ArturoAtomplay made their first contribution in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    495 downloads
  9. 1.7.0v1.7.0Dec 17, 2025

    🚀 VelocityLimboHandler v1.7.0

    ⚠️ Important: Configuration Migration

    If you are updating from v1.6.2 or lower, your task-interval unit has changed. Old behavior:* Seconds (e.g., 3) New behavior:* Milliseconds (e.g., 3000) Action Required:* Please update your config.yml to reflect this change, otherwise, the plugin will attempt to reconnect players far too fast! ---

    🛠️ Performance & Stability

    This update brings major internal improvements to ensure the proxy remains responsive even under heavy load. Non-Blocking Reconnections: All server pings and connection requests are now handled asynchronously*. This prevents "Proxy Hangs" if a backend server is slow or timing out. Full Server Protection: Added a "Pre-flight" check. The plugin now pings the target server and checks player capacity before* attempting a connection. This eliminates the "Server is full" console spam and reduces network overhead. Memory Management:* Fixed several memory leaks where disconnected players were remaining in internal tracking maps.

    ✨ New Features & Fixes

    New Integration: Added support for LibreLoginNext* in the AuthManager. Queue Logic:* Fixed a bug where players could sometimes "skip" the queue under specific timing conditions. Smart Rerouting:* Improved the connection listener to detect "Intentional" reconnections, preventing players from getting stuck in a loop between Limbo and the Lobby.

    📦 Pull Requests

    * Added LibreLoginNext support (#41) * Unit migration: task-interval to milliseconds (#42) * Core: Async implementation and leak fixes (#43) * Fix: Logic to handle full backend servers (#44) * Bugfix: Resolved queue skipping issues (#45) Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    715 downloads
  10. 1.6.2v1.6.2Oct 5, 2025

    Patch Notes — v1.6.2

    What’s New
    Bugfix:* Improved CloudNet support. This update resolves issues that caused inconsistent behavior when using CloudNet with the plugin. Thanks to @AkselGlyholt for the fix!
    Links
    Full changelog: [v1.6.1 → v1.6.2](https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    1425 downloads
  11. 1.6.1v1.6.1Sep 10, 2025
    📦 Release Notes – VelocityLimboHandler v1.6.1
    Bug Fixes * Fixed an issue where players could still be kicked for auth timeout even after authenticating with LibreLogin. This happened due to event ordering between Velocity and LibreLogin. Blocking now happens earlier in the login pipeline, ensuring proper unblock order. Improvements * Logs are clearer: integration with LibreLogin is only logged if the plugin is truly active. Notes * This release should resolve the “authenticated but still kicked” bug some servers experienced with LibreLogin. Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    436 downloads
  12. 1.6.0Velocity Limbo Handler 1.6.0Aug 12, 2025

    🚀 Velocity Limbo Handler 1.6.0 – LibreLogin Integration

    This update adds native support for LibreLogin authentication and smarter queue handling for players who haven’t logged in yet. ---
    ✨ New Features
    #### LibreLogin Auto-Detection Automatically detects the `librelogin` plugin at runtime — no configuration needed*. * Uses reflection to hook into getLibreLogin().getEventProvider() and listen for the authenticated event. * Instantly unblocks players from Limbo as soon as they authenticate. #### Auth-Aware Queue System Players awaiting authentication are not placed* into the reconnect queue. * On successful authentication, players are seamlessly restored to their correct per-server queue position. * Configurable timeout for authentication waiting (-1 to disable). ---
    ⚡ Improvements
    Queue processing now skips blocked players*, so pending logins never delay others. * Player re-queuing after authentication happens automatically — no manual action required. ---
    🐛 Bug Fixes
    * Fixed rare edge cases where reconnects during authentication could misplace players in the queue. ---
    📝 Notes
    * If LibreLogin is not installed, the plugin behaves exactly as before. Tested on Velocity 3.4.0-SNAPSHOT* with the latest LibreLogin build.
    572 downloads
  13. 1.5.0v1.5.0Jul 30, 2025
    New Features
    Bypass Maintenance Mode:* Players with permission can now skip the queue even when maintenance mode is active. Per-Server Queues:* Added support for separate queues per target server.
    Improvements
    Maintenance Whitelist Respect:* Players on the Maintenance plugin’s whitelist are no longer blocked by the queue. Logging:* The logger now uses the Plugin name, instead of the Class
    Cleanup & Fixes
    * Fixed a bug where players weren't properly removed from the queue. * General code cleanup and refactoring for better maintainability.
    187 downloads
  14. 1.4.0v1.4.0Jul 28, 2025

    What's Changed

    You can now customize message inside the messages.yml file. Looking inside the file should be pretty self-explanatory, but further documentation will be added in the future. (On GitHub) * Feature/message config by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Added bStats Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    32 downloads
  15. 1.3.0Velocity Limbo Handler 1.3.0Jul 27, 2025

    What's Changed

    Will now handle when the Backend server is in maintenance mode, and prevent chat/console spam by not attempting to send players through, until maintenance is back off again * Feature/maintenance integration by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Fixed connection error bug, when no forced-hosts are set Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    34 downloads
  16. 1.2.0v1.2.0Jul 22, 2025

    What's Changed

    * Added command blocker by @AkselGlyholt in https://github.com/AkselGlyholt/velocity-limbo-handler/pu… Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co… New config section to edit disabled commands in limbo server 
    # A list of disabled commands, which will not work inside the Limbo server. Recommended commands are ones that the player can use to transfer server, like /server or /hub
disabled-commands: ["server", "lobby", "hub"]
    54 downloads
  17. 1.1.1v1.1.1Jul 20, 2025

    What's Changed

    * Fix queue message for disabled mode by @AkselGlyholt in [#7](https://github.com/AkselGlyholt/velocity-limbo-handler/pu… * Fixed player reconnected to direct-connect server, and not intended server when using forced-hosts by @AkselGlyholt in [#8](https://github.com/AkselGlyholt/velocity-limbo-handler/pu…
    34 downloads
  18. 1.1.0v1.1.0Apr 11, 2025

    VelocityLimboHandler v1.1.0 - Connection Error Handling Improvements

    Overview

    This update enhances the player experience by significantly improving how connection errors are handled. Players who are banned or not whitelisted on destination servers now remain in limbo with appropriate notifications rather than being disconnected.

    New Features

    - Players now receive clear, color-coded notifications when they cannot connect to a server due to bans or whitelist restrictions - Added persistent tracking of player connection issues (banned/not whitelisted) - Improved queue system to properly skip players with connection issues

    Bug Fixes

    - Fixed issue where banned players were kicked from the proxy entirely - Fixed queue system becoming blocked when a player with connection issues was at the front of the queue - Fixed error message detection to properly identify ban and whitelist messages

    Technical Improvements

    - Enhanced error detection by checking both exception messages and server response components - Improved connection failure handling with proper categorization of error types - Made connection issue notifications independent of queue status

    Configuration

    - Added "queue-enabled" to toggle if the queue should be enabled, or just use random selection from players (Only recommended for small servers to keep it fair) --- This release focuses on creating a more stable experience for players during server maintenance and restarts while preventing unnecessary disconnections. Full Changelog: https://github.com/AkselGlyholt/velocity-limbo-handler/co…
    139 downloads
  19. 1.0.1v1.0.1Feb 25, 2025

    Whats changed?

    Fixed servers config not loading custom server names properly.
    90 downloads
  20. 1.0.0Velocity Limbo Handler 1.0.0Feb 13, 2025
    First release!

    Features

    * Automatic reconnecting to previous server before crash * Automatic reconnecting to main server if full/down * Queue system for reconnecting players
    53 downloads

Similar projects

Plugin →

VeinMiner

Mine the whole vein on mining a single ore/block. Make the tedious mining experience to something satisfying and fun! FTB Ultimine alternative

99.3MSueta

Simple Voice Chat

A working voice chat in Minecraft!

76.3MSueta

Chunky

Pre-generates chunks, quickly and efficiently

20.8MSueta

VeinMiner Enchantment

Veinminer Addon - Adds vineminer enchantment to enchanting tables. Only tools with the enchantment can veinmine

18MSueta

JourneyMap

Real-time map used for mapping in-game or your browser as you explore.

14.7MSueta

WorldEdit

A Minecraft Map Editor... that runs in-game! With selections, schematics, copy and paste, brushes, and scripting. Use it in creative, or use it temporarily in survival.

11.6MSueta