Installation - AkselGlyholt/velocity-limbo-handler GitHub Wiki

Setting up VelocityLimboHandler is simple and only takes a few steps. This guide assumes you're already running a Velocity proxy, and have a Limbo Server setup, such as LOOHP's Limbo

Get the latest version of VelocityLimboHandler from one of these sources:

• Modrinth
• Hangar (PaperMC)
• GitHub Releases

Make sure the version is compatible with your current Velocity version.

1. Stop your Velocity proxy if it's running.

2. Drop the downloaded .jar file into your plugins folder:

   /your-velocity-server/plugins/
   

3. Start the proxy again.

The plugin will generate a default config.yml and messages.yml on first launch.

After first startup:

• Open plugins/VelocityLimboHandler/config.yml

• Adjust settings like:

  • limbo-name (the Velocity server name of your Limbo server)
  • direct-connect-server
  • task-interval
  • queue-notify-interval
  • disabled-commands

You can learn more about these settings on the Configuration page.

Make sure players are sent to Limbo when a backend is unavailable. You can configure this in your velocity.toml:

try = ["main-server", "limbo"]

Or use forced hosts like:

[forced-hosts]
"play.example.com" = ["main-server", "limbo"]

📝 Important: Your limbo-name in the config must match the server ID in velocity.toml.

It’s recommended to:

• Block /server, /lobby, etc. while in Limbo to prevent escaping the queue
• Use LuckPerms with context-based permissions to limit commands in the Limbo server

More info in the Command Blocking

Now if you don't like the default messages, you can change them inside the messages.yml config file. Looks like this:

file-version: 1

# You can change all messages inside this file.
# Messages use minimessage format: https://docs.advntr.dev/minimessage/index.html

# Messages can include placeholders such as:
# [queue-position] which will display queue position

# These messages are for errors under reconnection, such as not whitelisted or banned.
bannedMessage: "<red>⛔ You are banned from that server.</red>"
notWhitelisted: "<red>⚠ You are not whitelisted on that server.</red>"

maintenanceMode: "<red>The server you're trying to connect to is currently in maintenance mode! You will be reconnected once it's available again."

# This is the message being sent as a notification to the player about their position in the queue
queuePosition: "<yellow>Queue position: [queue-position]"

# The notification the user gets of their position in the queue when joining.
# This is separate from the welcomeMessage, as the queue is toggleable.
queuePositionJoin: "<yellow>You are in the queue. Position: [queue-position]"

# Welcome messages
welcomeMessage: "<blue>🌌 You were sent to Limbo.</blue> \n<gray>You will be reconnected when the system allows.</gray>"

Last updated 29. July 2025, but the file will always contain information on where the message is used :)

Once installed and configured:

• Players will be sent to Limbo when their target server is down
• They'll automatically be queued and reconnected when it’s back
• You can monitor behavior in the Velocity logs

Next up: → Configuration