Hytale Server Manual

Hytale Server Requirements

Before you begin, make sure your system meets the minimum requirements for hosting a Hytale dedicated server. The server can run on any device with sufficient memory and processing power, supporting both x64 and arm64 architectures.

System Requirements

Resource usage depends heavily on player count, world size, view distance, and player activity. Monitor your server's RAM and CPU usage during gameplay to understand your specific needs.

How to Install Java 25 for Hytale Server

Hytale servers require Java 25 to run. We strongly recommend using Adoptium (Eclipse Temurin) for the best compatibility and performance.

Windows Installation

1. Visit Adoptium Downloads
2. Download the JDK 25 installer for Windows
3. Run the installer and follow the setup wizard
4. Verify installation by opening Command Prompt and running:

java --version

Expected output:

openjdk 25.0.1 2025-10-21 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode, sharing)

Linux Installation

Ubuntu/Debian:

wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -
sudo add-apt-repository --yes https://packages.adoptium.net/artifactory/deb/
sudo apt-get update
sudo apt-get install temurin-25-jdk

CentOS/RHEL:

sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo dnf install java-25-openjdk java-25-openjdk-devel

Getting Hytale Server Files

There are two ways to obtain the server files: manually copying from your Hytale Launcher installation, or using the Hytale Downloader CLI for automated updates.

Method 1: Copy from Launcher (Quick Start)

Best for testing or one-time setups. Navigate to your launcher installation directory:

• Windows: %appdata%\Hytale\install\release\package\game\latest
• Linux: $XDG_DATA_HOME/Hytale/install/release/package/game/latest
• MacOS: ~/Application Support/Hytale/install/release/package/game/latest

Copy the Server folder and Assets.zip to your server directory.

Method 2: Hytale Downloader CLI (Recommended)

Best for production servers. Automatically downloads and updates server files with OAuth2 authentication.

./hytale-downloader
./hytale-downloader -print-version
./hytale-downloader -check-update

The CLI handles authentication and downloads the latest server files, making it perfect for automated deployments and update scripts.

How to Start a Hytale Server

Once you have Java 25 installed and server files downloaded, starting your server is straightforward:

Basic Launch Command

java -jar HytaleServer.jar --assets PathToAssets.zip

Custom Port Configuration

Default port is 5520. Change it with the --bind argument:

java -jar HytaleServer.jar --assets PathToAssets.zip --bind 0.0.0.0:25565

Recommended Launch Parameters

For optimal performance, use these Java parameters:

java -Xms4G -Xmx8G -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets PathToAssets.zip

• -Xms4G - Initial heap size (4GB)
• -Xmx8G - Maximum heap size (8GB)
• -XX:AOTCache - Use ahead-of-time cache for faster startup

Hytale Server Authentication

After first launch, you must authenticate your server to enable player connections and API access. Each Hytale license supports up to 100 concurrent servers.

Device Code Authentication

In your server console, run:

> /auth login device

The server will display:

===================================================================
DEVICE AUTHORIZATION
===================================================================
Visit: https://accounts.hytale.com/device
Enter code: ABCD-1234
===================================================================
Waiting for authorization (expires in 900 seconds)...

Visit the URL in a browser, enter the code, and authorize. Once complete, your server is authenticated and ready for players.

Port Forwarding & Firewall Configuration

Important: Hytale uses the QUIC protocol over UDP (not TCP). You must configure your firewall and port forwarding for UDP traffic on port 5520 (or your custom port).

Windows Firewall Rule

New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow

Linux Firewall

Using ufw:

sudo ufw allow 5520/udp

Using iptables:

sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT

Router Port Forwarding

1. Access your router's admin panel (usually 192.168.1.1 or 192.168.0.1)
2. Navigate to Port Forwarding settings
3. Create a new rule:
   • Protocol: UDP
   • External Port: 5520
   • Internal Port: 5520
   • Internal IP: Your server's local IP
4. Save and restart the router if required

Server File Structure & Configuration

Understanding your server's file structure helps with configuration and troubleshooting:

Configuration files are read on startup and written when in-game actions occur (e.g., assigning permissions). Manual edits while the server is running may be overwritten.

Performance Optimization Tips

View Distance

View distance is the primary driver for RAM usage. Hytale's default of 384 blocks (roughly equivalent to 24 Minecraft chunks) can be memory-intensive. We recommend limiting maximum view distance to 12 chunks (384 blocks).

AOT Cache

The server ships with a pre-trained ahead-of-time cache (HytaleServer.aot) that dramatically improves boot times by skipping JIT warmup:

java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar

Memory Allocation

Allocate memory based on your player count and world size:

• 1-5 players: 4GB (-Xmx4G)
• 5-10 players: 6GB (-Xmx6G)
• 10-20 players: 8GB (-Xmx8G)
• 20+ players: 12GB+ (-Xmx12G)

Recommended Plugins

These plugins help with server performance monitoring and optimization:

• Nitrado:PerformanceSaver - Dynamically limits view distance based on resource usage
• ApexHosting:PrometheusExporter - Exposes detailed server and JVM metrics
• Nitrado:Query - Exposes server status via HTTP

Installing Mods and Plugins

Hytale supports server-side mods and plugins to extend functionality. Installing mods is straightforward:

Installation Steps

1. Download mods (.zip or .jar files) from trusted sources like CurseForge
2. Place the mod files in your server's mods/ folder
3. Restart your server
4. Check server logs to confirm the mod loaded successfully

Frequently Asked Questions

Related Server Tools