Limbo Server (NexLimbo)

Relevant source files

The following files were used as context for generating this wiki page:

• API/src/main/java/xyz/xreatlabs/nexauth/api/integration/LimboIntegration.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/nanolimbo/NanoLimboIntegration.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/nanolimbo/NanoLimboConfig.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/integration/BungeeNanoLimboIntegration.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/integration/VelocityNanoLimboIntegration.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityNexAuth.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordNexAuth.java
• CHANGELOG.md
• README.md
• Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperPlatformHandle.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/VoidWorldGenerator.java

The Limbo Server is a critical feature in NexAuth, providing a secure, isolated environment for players before they complete the authentication process. For proxy setups like Velocity and BungeeCord, NexAuth integrates with NexLimbo, a lightweight, high-performance limbo server specifically designed and optimized for the plugin's authentication flow. This system ensures that unauthenticated players cannot interact with backend servers, enhancing overall network security.

Initially, the project used the NanoLimboPlugin, but it was replaced by the custom-built NexLimbo implementation to achieve tighter integration and better performance. For Paper servers running in standalone mode, a "limbo" concept is also available, which functions by placing players in a dedicated, isolated "void" world instead of a separate server instance.

Sources: README.md, CHANGELOG.md:12-16, PaperPlatformHandle.java:51-53

Architecture and Core Components

The limbo integration is designed with a generic API and platform-specific implementations for BungeeCord, Velocity, and Paper.

LimboIntegration API

The core of the system is the LimboIntegration<S> interface. It provides a standardized contract for creating limbo servers across different platforms.

• S createLimbo(String serverName): The single method defined in this interface. Its purpose is to create a new limbo server instance and return a platform-specific server object (ServerInfo for BungeeCord, RegisteredServer for Velocity).

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/integration/LimboIntegration.java:13-20

NanoLimboIntegration Abstract Class

This abstract class provides the foundational logic for proxy-based limbo server creation. It handles finding available network ports and instantiating the underlying LimboServer from the NexLimbo dependency.

Key responsibilities:

• Port Discovery: It parses a configured port range (limbo.port-range) and iterates through it to find an available local port for the new limbo server.
• Server Instantiation: It creates a LimboServer instance using a NanoLimboConfig and a platform-specific class loader.

The following diagram shows the class hierarchy for the limbo integration.

Initialization and Server Creation Flow

The limbo integration is initialized conditionally. NexAuth checks if the NexLimboBungee or nexlimbovelocity plugin is present on the proxy. If so, it creates an instance of the corresponding integration class.

The following sequence diagram illustrates the creation of a new limbo server.

This diagram shows the process from getting the integration to starting and registering the new limbo server with the proxy.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/VelocityNexAuth.java:214-219, Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/BungeeCordNexAuth.java:216-221, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/nanolimbo/NanoLimboIntegration.java:26-28

Platform-Specific Implementations

BungeeCord (BungeeNanoLimboIntegration)

• Server Creation: Uses ProxyServer.getInstance().constructServerInfo() to create a ServerInfo object for the new limbo server and adds it to the proxy's server list.
• Player Info Forwarding: Hardcoded to use legacy forwarding mode.

// Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/integration/BungeeNanoLimboIntegration.java:27-32
@Override
public ServerInfo createLimbo(String serverName) {
    SocketAddress address = findLocalAvailableAddress().orElseThrow(() -> new IllegalStateException("Cannot find available port for limbo server!"));
    LimboServer server = createLimboServer(address);
    // ... server.start() ...
    ServerInfo serverInfo = ProxyServer.getInstance().constructServerInfo(serverName, address, "", false);
    ProxyServer.getInstance().getConfig().getServers().put(serverInfo.getName(), serverInfo);
    return serverInfo;
}

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/bungeecord/integration/BungeeNanoLimboIntegration.java:15-42

Velocity (VelocityNanoLimboIntegration)

• Server Creation: Uses proxyServer.registerServer() to register the new limbo server with the Velocity proxy.
• Player Info Forwarding: Dynamically determines the forwarding mode (NONE, LEGACY, MODERN, BUNGEEGUARD) by using reflection to inspect the proxy's configuration. This provides robust compatibility with different Velocity setups without hardcoding values. If reflection fails, it safely falls back to NONE.

// Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/integration/VelocityNanoLimboIntegration.java:44-59
@Override
protected InfoForwarding createForwarding() {
    // Use reflection to safely access internal configuration
    try {
        Object velocityConfiguration = proxyServer.getConfiguration();
        Class<?> configClass = velocityConfiguration.getClass();
        
        // Try to get the forwarding mode using reflection
        Object forwardingMode = configClass.getMethod("getPlayerInfoForwardingMode").invoke(velocityConfiguration);
        String forwardingModeName = forwardingMode.toString();
        
        switch (forwardingModeName) {
            // ... cases for NONE, LEGACY, MODERN, BUNGEEGUARD
        }
    } catch (Exception e) {
        // If reflection fails, fallback to NONE forwarding
        return FORWARDING_FACTORY.none();
    }
}

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/velocity/integration/VelocityNanoLimboIntegration.java:19-75

Paper (Standalone)

On Paper servers, NexAuth does not use NexLimbo. Instead, it creates a dedicated, empty "void" world to serve as the limbo area.

• When a world is requested as a limbo world, a WorldCreator is configured with a custom VoidWorldGenerator.
• This generator creates a world that is almost entirely empty, except for a single barrier block at 0, 69, 0 to serve as a platform for the player.
• Game rules like DO_DAYLIGHT_CYCLE are disabled to keep the environment static.

This approach isolates unauthenticated players within a specific world on the same server, rather than on a separate proxy-level server instance.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperPlatformHandle.java:51-73, Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/VoidWorldGenerator.java:15-23

Limbo Server Configuration

The configuration for each dynamically created limbo server is defined in NanoLimboConfig.java. These settings are hardcoded to create a minimal, non-interactive environment.

Property	Value	Description
maxPlayers	-1	Disables the player count limit.
dimensionType	"the_end"	Sets the world dimension to The End.
gameMode	2	Puts the player in Adventure game mode.
readTimeout	30000 ms	Sets the connection read timeout to 30 seconds.
useBrandName	false	Disables sending a custom server brand.
useJoinMessage	false	Disables the join message.
useBossBar	false	Disables the boss bar.
useTitle	false	Disables sending a title on join.
usePlayerList	false	Disables the player list (tab list).
secureProfile	false	Disables secure profile enforcement, which is necessary for an authentication limbo.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/nanolimbo/NanoLimboConfig.java

Summary

The NexLimbo integration is a sophisticated system that provides a secure and isolated environment for player authentication on proxy servers. By dynamically creating and managing lightweight server instances, it ensures that unauthenticated players are completely separated from the main server network. The architecture is flexible, with platform-specific implementations for BungeeCord and Velocity, and a fallback "limbo world" system for standalone Paper servers. The evolution from a third-party dependency to the purpose-built NexLimbo highlights its importance to the NexAuth project's security and performance goals.

Sources: CHANGELOG.md:12-16, README.md:31-34