Interface ProxyServer

public interface ProxyServer
Main entry point for the Numdrassl API.

Numdrassl is a QUIC reverse proxy for Hytale that sits between players and backend servers. Players connect to the proxy, which terminates TLS using its own certificates and forwards traffic to backend servers. The proxy intercepts all packets flowing in both directions, inspecting, modifying, or relaying them as needed while keeping the connection transparent to both endpoints.

Authentication happens normally: the proxy validates player tokens and relays the authenticated session to backends, which see standard Hytale protocol traffic with no modifications needed. No certificate changes, no custom authentication handling, and no protocol adjustments required on the server side.

Numdrassl authenticates with Hytale backend servers by replicating the exact authentication flow used by the official Hytale client/server. The proxy extracts the player's authentication token during the initial handshake, then establishes its own connection to the backend server, presenting the same credentials as if it were a legitimate Hytale client. Since the proxy implements the Hytale protocol natively, mimicking the behavior of the official JAR, backend servers cannot distinguish between a direct player connection and one proxied through Numdrassl.

For server transfers, the proxy sends a ClientReferral packet directing the client to reconnect to the proxy's public address (not the backend directly), then routes them to the new backend server.

  • Method Details

    • getEventManager

      @Nonnull EventManager getEventManager()
      Get the event manager for registering event listeners.
      Returns:
      the event manager

    • getCommandManager

      @Nonnull CommandManager getCommandManager()
      Get the command manager for registering commands.
      Returns:
      the command manager

    • getConsoleCommandSource

      @Nonnull CommandSource getConsoleCommandSource()
      Get the console command source.

      The console command source represents the server console and can be used to execute commands programmatically or to identify console-originated actions. It is also a PermissionSubject for permission checks.

      Returns:
      the console command source

    • getPluginManager

      @Nonnull PluginManager getPluginManager()
      Get the plugin manager for managing plugins.
      Returns:
      the plugin manager

    • getChannelRegistrar

      @Nonnull ChannelRegistrar getChannelRegistrar()
      Get the channel registrar for plugin messaging.

      Plugin message channels allow communication between the proxy and backend servers. This is used by plugins like LuckPerms to synchronize data.

      Returns:
      the channel registrar

    • getScheduler

      @Nonnull Scheduler getScheduler()
      Get the scheduler for scheduling tasks.
      Returns:
      the scheduler

    • getPermissionManager

      @Nonnull PermissionManager getPermissionManager()
      Get the permission manager for managing permissions.

      The permission manager allows external permission plugins (like LuckPerms) to register their permission providers.

      Returns:
      the permission manager

    • getMessagingService

      @Nonnull MessagingService getMessagingService()
      Get the messaging service for cross-proxy communication.

      The messaging service enables pub/sub communication between proxy instances in a distributed deployment. Returns a no-op implementation if clustering is disabled.

      Returns:
      the messaging service

    • getBackendMessagingService

      @Nonnull BackendMessagingService getBackendMessagingService()
      Get the backend messaging service for proxy-to-backend communication.

      The backend messaging service enables bidirectional communication between the proxy and backend servers running the Bridge plugin. Unlike player-based plugin messaging, this works even when no players are connected.

      Returns:
      the backend messaging service

    • getClusterManager

      @Nonnull ClusterManager getClusterManager()
      Get the cluster manager for managing proxy instances.

      The cluster manager tracks all online proxies, aggregates global state, and provides methods for cross-proxy coordination.

      Returns:
      the cluster manager

    • getGlobalPlayerCount

      int getGlobalPlayerCount()
      Get the total player count across all proxies in the cluster.

      If clustering is disabled, returns the local player count.

      Returns:
      the global player count

    • getAllPlayers

      @Nonnull Collection<Player> getAllPlayers()
      Get all currently connected players.
      Returns:
      an unmodifiable collection of connected players

    • getPlayer

      @Nonnull Optional<Player> getPlayer(@Nonnull UUID uuid)
      Get a player by their UUID.
      Parameters:
      uuid - the player's UUID
      Returns:
      the player, or empty if not connected

    • getPlayer

      @Nonnull Optional<Player> getPlayer(@Nonnull String username)
      Get a player by their username.
      Parameters:
      username - the player's username (case-insensitive)
      Returns:
      the player, or empty if not connected

    • getPlayerCount

      int getPlayerCount()
      Get the number of currently connected players.
      Returns:
      the player count

    • getAllServers

      @Nonnull Collection<RegisteredServer> getAllServers()
      Get all registered backend servers.
      Returns:
      an unmodifiable collection of registered servers

    • getServer

      @Nonnull Optional<RegisteredServer> getServer(@Nonnull String name)
      Get a registered server by its name.
      Parameters:
      name - the server name (case-insensitive)
      Returns:
      the server, or empty if not registered

    • registerServer

      @Nonnull RegisteredServer registerServer(@Nonnull String name, @Nonnull InetSocketAddress address)
      Register a new backend server.
      Parameters:
      name - the server name
      address - the server address
      Returns:
      the newly registered server

    • unregisterServer

      boolean unregisterServer(@Nonnull String name)
      Unregister a backend server.
      Parameters:
      name - the server name
      Returns:
      true if the server was unregistered

    • getBoundAddress

      @Nonnull InetSocketAddress getBoundAddress()
      Get the address the proxy is bound to.
      Returns:
      the bound address

    • getPublicAddress

      @Nonnull InetSocketAddress getPublicAddress()
      Get the public address players should use to connect.
      Returns:
      the public address, or the bound address if not configured

    • getDataDirectory

      @Nonnull Path getDataDirectory()
      Get the proxy's data directory.
      Returns:
      the path to the data directory

    • getConfigDirectory

      @Nonnull Path getConfigDirectory()
      Get the proxy's configuration directory.
      Returns:
      the path to the config directory

    • isRunning

      boolean isRunning()
      Check if the proxy is currently running.
      Returns:
      true if the proxy is running

    • shutdown

      void shutdown()
      Shutdown the proxy gracefully.

    • getVersion

      @Nonnull String getVersion()
      Get the proxy version.
      Returns:
      the version string