Numdrassl

Numdrassl - Hytale Proxy Server

A high-performance, extensible Hytale proxy server written in Java that enables multi-server networks, player transfers, plugin support, and a flexible permission system.

What is Numdrassl?

Numdrassl is a BungeeCord/Velocity-style proxy for Hytale. It sits between players and your backend servers, allowing you to:

Connect multiple Hytale servers into a single network

Transfer players seamlessly between servers

Intercept and modify packets

Create plugins with custom commands and events

Manage permissions with groups and wildcards

Features

Multi-Server Network - Connect multiple backend Hytale servers (lobby, minigames, etc.)

Player Transfers - Seamlessly move players between servers with /server <name>

Plugin System - Extend functionality with custom plugins

Permission System - Built-in YAML-based permissions with groups, wildcards, and external provider support

Event System - Hook into player connections, chat, commands, and more

QUIC Protocol - Native support for Hytale's QUIC transport with BBR congestion control

Secure Authentication - HMAC-signed referrals between proxy and backends

Requirements

Java 25 or higher

Hytale Server(s) to use as backends

Installation

Step 1: Download

Download the latest release:

proxy-*.jar - The proxy server

bridge-*.jar - Plugin for your backend servers

Step 2: Run the Proxy

java -jar proxy-1.0-SNAPSHOT.jar On first run, the proxy will:

Generate TLS certificates in certs/

Create config/proxy.yml configuration file

Prompt you to authenticate with Hytale

Step 3: Authenticate with Hytale

In the proxy console, run:

auth login Visit the URL shown and enter the device code to link your Hytale account.

Proxy Configuration

Edit config/proxy.yml:

# Network Settings bindAddress: "0.0.0.0" bindPort: 45585

# Public address (for server transfers) publicAddress: "play.yourserver.com" publicPort: 45585

# Shared secret - MUST match your Bridge plugin config! proxySecret: "change-this-to-a-secure-secret"

# Backend Servers backends: - name: "lobby" host: "127.0.0.1" port: 5520 defaultServer: true # Players join here first

- name: "survival" host: "127.0.0.1" port: 5521 defaultServer: false

- name: "minigames" host: "192.168.1.100" port: 5520 defaultServer: false Configuration Options

Option Description

bindAddress IP to listen on (0.0.0.0 for all interfaces)

bindPort Port to listen on (default: 45585)

publicAddress Public hostname/IP for server transfers

publicPort Public port for server transfers

proxySecret Shared secret for backend authentication

backends List of backend servers

debugMode Enable verbose logging (default: false)

Backend Server Setup

Each backend server needs the Bridge plugin to authenticate connections from the proxy.

Step 1: Install Bridge Plugin

Copy bridge-1.0-SNAPSHOT.jar to your Hytale server's plugins/ folder.

Step 2: Start Server in Insecure Mode

java -jar HytaleServer.jar --auth-mode insecure --transport QUIC

Important: The --auth-mode insecure flag is required because the proxy handles Hytale authentication, not the backend.

Step 3: Configure Bridge

On first run, the Bridge creates plugins/Bridge/config.json:

{ "proxySecret": "change-this-to-a-secure-secret", "serverName": "lobby" }

Option Description

proxySecret Must match the proxySecret in your proxy config!

serverName Name of this server (for logging/identification)

Step 4: Secure Your Backend (Important!)

Block direct connections to your backend servers. Only allow the proxy's IP:

# Example: Only allow proxy (192.168.1.50) to connect on port 5520 iptables -A INPUT -p udp --dport 5520 -s 192.168.1.50 -j ACCEPT iptables -A INPUT -p udp --dport 5520 -j DROP Without this, players could bypass the proxy and connect directly!

Player Commands

Command Aliases Description

/server /srv List available servers

/server <name> /srv <name> Transfer to a server

/numdrassl /nd, /proxy Proxy management commands

/numdrassl version

Show proxy version

/numdrassl perm ...

Permission management

Permission System

Permissions are stored in YAML files under data/permissions/:

data/permissions/ ├── players/ │ └── {uuid}.yml # Per-player permissions ├── groups/ │ ├── default.yml # Default group (all players) │ └── admin.yml # Custom groups └── player-groups.yml # Player-to-group assignments Player Permissions (players/{uuid}.yml)

permissions: - numdrassl.command.server - numdrassl.command.help - -numdrassl.command.stop # Denied (prefix with -) Group Permissions (groups/admin.yml)

name: admin default: false permissions: - numdrassl.command.* # Wildcard - numdrassl.admin Permission Commands

Command Description

/numdrassl perm user <player> info Show player's groups/permissions

/numdrassl perm user <player> add <perm> Grant a permission

/numdrassl perm user <player> remove <perm> Remove a permission

/numdrassl perm user <player> addgroup <group> Add player to group

/numdrassl perm user <player> removegroup <group> Remove from group

/numdrassl perm group <group> add <perm> Add permission to group

/numdrassl perm group <group> remove <perm> Remove from group

/numdrassl perm reload Reload permissions from disk

Console Commands

Command Description

auth login Authenticate with Hytale

auth status Show authentication status

auth logout Clear stored credentials

sessions List connected players

stop Shut down the proxy

help Show available commands

Plugin Development

Create plugins to extend the proxy! Plugins can:

Listen to events (player join, chat, commands, etc.)

Register custom commands

Modify packets

Interact with players and servers

API Dependency:

dependencies { compileOnly("me.internalizable.numdrassl:api:1.0-SNAPSHOT") } Example Plugin:

@Plugin(id = "my-plugin", name = "My Plugin", version = "1.0.0") public class MyPlugin {

@Subscribe public void onPlayerChat(PlayerChatEvent event) { if (event.getMessage().contains("hello")) { event.getPlayer().sendMessage("Hello to you too!"); } } } See the full Plugin Development Guide for more details.

Troubleshooting

"Proxy not authenticated"

Run auth login in the proxy console and complete the device code flow.

"Invalid player info message (is your proxy secret valid?)"

The proxySecret in your proxy config doesn't match the Bridge plugin's proxySecret.

"Connection timed out" to backend

Check the backend server is running

Verify firewall allows the proxy IP

Confirm the address/port in config is correct

"Cannot direct join numdrassl backend"

Players are trying to connect directly to the backend. Set up firewall rules to block direct connections.

Client shows "unexpected packet"

The backend server may not have the Bridge plugin installed, or isn't running with --auth-mode insecure.

Redis connection failed (Cluster Mode)

Verify Redis server is running and accessible

Check redis.host and redis.port in your config

If using authentication, ensure redis.password is correct

Verify firewall allows connections to Redis port

Players not synced across proxies (Cluster Mode)

Ensure all proxies have cluster.enabled: true

Verify all proxies connect to the same Redis instance

Check that cluster.proxyId is unique for each proxy

Architecture Overview

Single Proxy Mode

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Player │ ──── QUIC/TLS ──── │ Proxy │ ──── QUIC/TLS ──── │ Backend │ │ Client │ │ Numdrassl │ │ Server │ └─────────────┘ └─────────────┘ └─────────────┘ │ ├── lobby (default) ├── survival └── minigames Cluster Mode (Multi-Proxy)

┌──────────────────────────────────┐ │ Redis │ │ ┌────────────────────────┐ │ │ │ Pub/Sub Channels │ │ │ │ • numdrassl:heartbeat │ │ │ │ • numdrassl:chat │ │ │ │ • numdrassl:transfer │ │ │ │ • numdrassl:broadcast │ │ │ └────────────────────────┘ │ │ ┌────────────────────────┐ │ │ │ Shared State │ │ │ │ • Player locations │ │ │ │ • Proxy registry │ │ │ │ • Player counts │ │ │ └────────────────────────┘ │ └──────────────┬───────────────────┘ │ ┌─────────────────────────────────┼─────────────────────────────────┐ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ Proxy (EU) │ │ Proxy (US) │ │ Proxy (Asia)│ │ proxy-eu-1 │◄─── Transfer ────►│ proxy-us-1 │◄─── Transfer ────►│ proxy-as-1 │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ Backends │ │ Backends │ │ Backends │ │ • lobby │ │ • lobby │ │ • lobby │ │ • games │ │ • games │ │ • games │ └─────────────┘ └─────────────┘ └─────────────┘ Authentication Flow

┌────────┐ ┌───────────┐ ┌─────────────┐ ┌─────────┐ │ Player │ │ Proxy │ │ Hytale │ │ Backend │ └───┬────┘ └─────┬─────┘ │ Sessions │ └────┬────┘ │ │ └──────┬──────┘ │ │ 1. Connect │ │ │ │ (identity_token) │ │ │ │────────────────────►│ │ │ │ │ 2. Request auth │ │ │ │ grant │ │ │ │──────────────────────►│ │ │ │ │ │ │ │ 3. auth_grant │ │ │ │◄──────────────────────│ │ │ 4. AuthGrant │ │ │ │◄────────────────────│ │ │ │ │ │ │ │ 5. AuthToken │ │ │ │────────────────────►│ 6. Exchange token │ │ │ │──────────────────────►│ │ │ │◄──────────────────────│ │ │ 7. ServerAuthToken │ │ │ │◄────────────────────│ │ │ │ │ │ │ │ │ 8. Connect + HMAC-signed referral │ │ │─────────────────────────────────────────────►│ │ │ │ │ │ │ 9. ConnectAccept (secret validated) │ │ │◄─────────────────────────────────────────────│ │ │ │ │ Cross-Proxy Transfer Flow

┌────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ Player │ │ Proxy A │ │ Proxy B │ │ Backend │ │ │ │ (source) │ Redis │ (target) │ │ Server │ └───┬────┘ └────┬─────┘ │ └────┬─────┘ └────┬────┘ │ │ │ │ │ │ /server hub │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ 1. Publish │ │ │ │ │ TransferMsg │ │ │ │ │─────────────►│ │ │ │ │ │ │ │ │ │ │ 2. Subscribe │ │ │ │ │ receives msg │ │ │ │ │───────────────►│ │ │ │ │ │ │ │ 3. ClientReferral │ │ │ │ (reconnect to Proxy B) │ │ │ │◄──────────────│ │ │ │ │ │ │ │ │ │ 4. New connection │ │ │ │─────────────────────────────────────────────►│ │ │ │ │ │ │ │ │ │ │ 5. Forward │ │ │ │ │ to backend │ │ │ │ │───────────────►│

Player connects to the proxy with their Hytale credentials

Proxy authenticates the player with Hytale session service

Proxy forwards the connection to the default backend with signed referral

Backend validates the referral using the shared secret

Packets flow bidirectionally through the proxy

In cluster mode, player state and messages sync via Redis pub/sub

Cluster Mode (Multi-Proxy Networks)

For large networks, you can run multiple Numdrassl proxies across different regions with shared state using Redis.

Overview

┌─────────────────┐ │ Redis │ │ (Pub/Sub Hub) │ └────────┬────────┘ ┌───────────────────────┼───────────────────────┐ │ │ │ ┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐ │ Proxy (EU) │ │ Proxy (US) │ │ Proxy (Asia) │ │ Region: eu │ │ Region: us │ │ Region: asia │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ ┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐ │ Backends │ │ Backends │ │ Backends │ └───────────────┘ └───────────────┘ └───────────────┘ Cluster Features

Cross-Proxy Player Tracking - Know which players are online across all proxies

Cross-Proxy Messaging - Send messages to players on other proxies

Cross-Proxy Transfers - Transfer players between servers on different proxies

Load Balancing - Route players to the least loaded proxy in their region

Health Monitoring - Automatic heartbeat and stale proxy detection

Redis Configuration

Add to your config/proxy.yml:

# Cluster Settings cluster: enabled: true

# Unique ID for this proxy instance (auto-generated if not set) proxyId: "proxy-eu-1"

# Region identifier for geographic load balancing region: "eu"

# Redis connection settings redis: host: "redis.yourserver.com" port: 6379 password: "your-redis-password" # Optional database: 0

# Connection pool settings poolSize: 10 timeout: 5000 # milliseconds Cluster Configuration Options

Option Description

cluster.enabled Enable cluster mode (true/false)

cluster.proxyId Unique identifier for this proxy instance

cluster.region Geographic region (e.g., eu, us, asia)

redis.host Redis server hostname

redis.port Redis server port (default: 6379)

redis.password Redis authentication password (optional)

redis.database Redis database number (default: 0)

redis.poolSize Connection pool size (default: 10)

redis.timeout Connection timeout in ms (default: 5000)

Cross-Proxy Commands

When cluster mode is enabled:

Command Description

/server <name> Transfer to a server (works across proxies)

/numdrassl cluster info Show cluster status and connected proxies

/numdrassl cluster players List players across all proxies

Plugin Messaging API

Plugins can send messages across the cluster:

@Plugin(id = "my-plugin", name = "My Plugin", version = "1.0.0") public class MyPlugin {

@Inject private MessagingService messaging;

// Subscribe to custom messages @Subscribe(channel = "my-channel") public void onCustomMessage(MyCustomData data) { // Handle message from any proxy }

// Publish messages to all proxies public void broadcastToCluster(String message) { messaging.publish("my-channel", new MyCustomData(message)); } } System Channels

The cluster uses these internal channels (plugins can subscribe):

Channel Purpose

numdrassl:heartbeat Proxy health monitoring

numdrassl:player_count Player count synchronization

numdrassl:chat Cross-proxy chat messages

numdrassl:transfer Cross-proxy player transfers

numdrassl:broadcast Server-wide announcements

Community

Join the Discord

Links

GitHub Repository

API Documentation

Plugin Development Guide

Releases

Discord 💬

License

Proprietary - All rights reserved.