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:

1. Generate TLS certificates in certs/
2. Create config/proxy.yml configuration file
3. 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

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"
}

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

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

Console 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

1. Check the backend server is running
2. Verify firewall allows the proxy IP
3. 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)

1. Verify Redis server is running and accessible
2. Check redis.host and redis.port in your config
3. If using authentication, ensure redis.password is correct
4. Verify firewall allows connections to Redis port

Players not synced across proxies (Cluster Mode)

1. Ensure all proxies have cluster.enabled: true
2. Verify all proxies connect to the same Redis instance
3. 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    │
    │               │              │                │───────────────►│

1. Player connects to the proxy with their Hytale credentials
2. Proxy authenticates the player with Hytale session service
3. Proxy forwards the connection to the default backend with signed referral
4. Backend validates the referral using the shared secret
5. Packets flow bidirectionally through the proxy
6. 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

Cross-Proxy Commands

When cluster mode is enabled:

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):

Community

Join the Discord

Links

• GitHub Repository
• API Documentation
• Plugin Development Guide
• Releases
• Discord 💬

License

Proprietary - All rights reserved.