Queue System - AkselGlyholt/velocity-limbo-handler GitHub Wiki

🔁 How the Queue System Works

When a player tries to connect to a backend server that’s offline, crashed, or under maintenance, VelocityLimboHandler places them in a reconnect queue instead of disconnecting them or leaving them stuck.

This queue system is designed to be per server, meaning each backend server has its own separate queue. Players waiting to reconnect to server-a won’t be affected by players queued for server-b.

🚨 When Does the Queue Start?

Players are added to the queue when:

  • They attempt to connect to a backend server that’s unavailable
  • Velocity routes them to the limbo-name server defined in config.yml
  • The plugin detects that their intended destination is not currently connectable

📦 How Per-Server Queues Work

  • Each server has its own independent queue
  • Players are only queued for the specific backend they originally tried to connect to
  • The plugin keeps track of these separately, so if one server recovers, it doesn't affect queues for other servers

This avoids bottlenecks and ensures fair reconnection handling across a multi-server network.

🔄 Reconnect Process

Once in the queue for a specific server:

  1. The player stays in Limbo.

  2. Every task-interval seconds (default: 3), the plugin:

    • Checks if their target server is online
    • If available, reconnects them in the order they joined that server’s queue

  3. Every queue-notify-interval seconds (default: 30), the player sees a message like:

    "You're in queue position #2 for server-a. Reconnecting when possible..."

🛠 Maintenance-Aware Behavior

If a backend is marked as under maintenance, the plugin will pause reconnection attempts for that server’s queue until it’s back online.

This prevents spam and pointless retries while you’re intentionally keeping a server offline.

See Maintenance Mode for more.

🧼 When a Player Leaves the Queue

Players are removed from the queue if:

  • They successfully reconnect
  • They disconnect from the proxy
  • They’re kicked or moved from Limbo by another plugin
  • The plugin times them out and sends them to the direct-connect-server (if configured)

💡 Tips

  • Each backend has an isolated queue: fast recovery for one won’t affect the others
  • Queue processing continues in the background even if players don’t see queue messages
  • Velocity proxy restarts will reset the queues (they are stored in memory)