Developers - AkselGlyholt/velocity-limbo-handler GitHub Wiki

This page is for developers who want to dive into the internals of VelocityLimboHandler β€” whether you're contributing, debugging, or just curious about how it works under the hood.

Project Structure

The plugin is written in Java and built for the Velocity Minecraft proxy.

Here’s a simplified structure of the main components:

velocity-limbo-handler/
β”œβ”€β”€ src/
β”‚   └── main/
β”‚       └── java/
β”‚           └── com/akselglyholt/velocityLimboHandler/
β”‚               β”œβ”€β”€ VelocityLimboHandler.java        <-- Main plugin class
β”‚
β”‚               └── commands/
β”‚                   β”œβ”€β”€ CommandBlocker.java          <-- Stores blocked commands
β”‚                   └── CommandBlockRule.java        <-- Command blocking logic
β”‚
β”‚               └── listeners/
β”‚                   β”œβ”€β”€ CommandExecuteEventListener.java   <-- Handles command blocking events
β”‚                   └── ConnectionListener.java            <-- Manages player join/leave in the reconnect queue
β”‚
β”‚               └── misc/
β”‚                   β”œβ”€β”€ MessageFormater.java         <-- Formats messages (e.g. [queue-position])
β”‚                   └── Utility.java                 <-- Helper methods like isServerInMaintenance()
β”‚
β”‚               └── storage/
β”‚                   └── PlayerManager.java           <-- Manages player queue data and state

Core Flow

  1. Startup VelocityLimboHandler loads the config and registers event listeners.

  2. Join Event When a player connects to the Limbo server due to a failed backend, they are queued for reconnection using PlayerManager.

  3. Reconnect Loop A scheduled task checks each server’s queue and attempts to reconnect the first player if the backend becomes available.

  4. Command Handling If a player in Limbo runs a blocked command, CommandExecuteEventListener checks it against CommandBlocker and cancels it if matched.

Building From Source (Maven)

  1. Clone the repository:

    git clone https://github.com/AkselGlyholt/velocity-limbo-handler.git
cd velocity-limbo-handler

  2. Build with Maven:

    mvn clean package

  3. The compiled .jar will be in:

    target/

Make sure you have Java 17+ and Maven installed.

Testing Setup

To test the plugin locally:

  • Use Velocity with 2–3 dummy backend servers (lobby, main, limbo)
  • Simulate a backend outage by stopping main
  • Observe how players are queued in Limbo and reconnected automatically

Contributing

Contributions are welcome!

To contribute:

  1. Fork the repo
  2. Create a feature branch
  3. Make your changes
  4. Open a pull request with a clear explanation

Keep your code clean, documented, and aligned with the existing style.