SimpleLimbo

SimpleLimbo

A lightweight virtual limbo server plugin for Velocity proxy using LimboAPI.

Features

• Multiple Limbo Servers - Create unlimited virtual limbo instances with different configurations
• Auth Plugin Support - Compatible with JPremium and other authentication plugins
• Fallback System - Automatically catch players when backend servers go down
• AFK Detection - Move idle players to a dedicated limbo server
• Custom Worlds - Load schematic files for limbo environments
• Rich Display - Titles, action bars, boss bars, and chat messages
• Auto Reconnect - Automatically attempt to reconnect players to backend servers
• Velocity Bridge - Register virtual servers that redirect to limbos

Requirements

• Velocity 3.3.0+
• LimboAPI 1.1.27+
• Java 17+

Installation

1. Download LimboAPI and place it in your Velocity plugins folder
2. Download SimpleLimbo and place it in your Velocity plugins folder
3. Restart Velocity
4. Configure plugins/simplelimbo/config.yml

Configuration

Basic Limbo Setup

limbos:
  auth:
    enabled: true
    dimension: "OVERWORLD"
    gamemode: "ADVENTURE"
    world-time: 6000

    spawn:
      x: 0.0
      y: 100.0
      z: 0.0
      yaw: 0.0
      pitch: 0.0

    settings:
      read-timeout: 30000
      should-rejoin: true
      should-respawn: false
      disable-falling: true
      disable-falling-delay-ms: 5000

    commands:
      - "login"
      - "register"

    display:
      on-join:
        chat: "&eUse /login or /register"
        title:
          enabled: true
          title: "&eAuthentication"
          subtitle: "&7Please authenticate"

Velocity Bridge (Auth Plugin Compatibility)

For plugins like JPremium that expect players to be on a named server:

velocity-bridge:
  enabled: true
  register-aliases: true
  aliases:
    auth: "auth" # Maps server name "auth" to limbo "auth"

Then in your auth plugin config, set the limbo server to auth.

Anti-Fall Tuning

• disable-falling keeps players from dropping after join (Y lock mode).
• disable-falling-delay-ms controls when anti-fall starts.
• If players get slow join or "Loading Terrain" delay, increase disable-falling-delay-ms (for example: 1200, 1500, 2000).

Settings Notes

• should-rejoin: true keeps LimboAPI rejoin flow enabled (recommended for stability).
• should-respawn: false avoids extra respawn packet during join.

Fallback System

Automatically catch players when backend servers crash:

auto-triggers:
  fallback:
    enabled: true
    limbo: "fallback"
    kick-patterns:
      - ".*server.*closed.*"
      - ".*timed out.*"
    message: "&cServer offline. Moved to fallback."

AFK System

Move idle players to a dedicated limbo:

auto-triggers:
  afk:
    enabled: true
    limbo: "afk"
    idle-time: 300
    check-interval: 30
    exempt-permission: "simplelimbo.afk.exempt"

Custom World Files

Load schematic files for limbo environments:

limbos:
  lobby:
    world-file:
      enabled: true
      type: "SCHEMATIC"
      path: "plugins/simplelimbo/worlds/lobby.schem"
      offset:
        x: 0
        y: 64
        z: 0
      light-level: 15

Commands

Permissions

Auth Plugin Compatibility

SimpleLimbo includes compatibility features for authentication plugins that call player.getCurrentServer():

1. Set fake-server-name in your limbo config to a valid Velocity server name
2. Enable the velocity-bridge with matching alias
3. Configure your auth plugin to use this server name as the limbo server

Example for JPremium:

# SimpleLimbo config.yml
velocity-bridge:
  aliases:
    auth: "auth"

limbos:
  auth:
    fake-server-name: "auth"
    # ... other settings

# JPremium configuration.yml
limboServerNames: [auth]
mainServerNames: [lobby]

Building from Source

git clone https://github.com/ItsAzni/SimpleLimbo.git
cd SimpleLimbo
./gradlew shadowJar

The compiled JAR will be in build/libs/.

License

MIT License

Credits

• LimboAPI by Elytrium
• Velocity by PaperMC