Hytale Server Manual

This article covers the setup, configuration, and operation of dedicated Hytale servers.

Contents

Server Setup

The Hytale server can run on any device with at least 4GB of memory and Java 25. Both x64 and arm64 architectures are supported.

We recommend monitoring RAM and CPU usage while the server is in use to understand typical consumption for your player count and playstyle - resource usage heavily depends on player behavior.

General guidance:

Note: Without specialized tooling, it can be hard to determine how much allocated RAM a Java process actually needs. Experiment with different values for Java's -Xmx parameter to set explicit limits. A typical symptom of memory pressure is increased CPU usage due to garbage collection.

Installing Java 25

Install Java 25. We recommend Adoptium.

Confirm Installation

Verify the installation by 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)

Server Files

Three options to obtain server files:

1. Manually copy from your Launcher installation
2. Use the Hytale Downloader CLI
3. Bootstrap from HytaleServer.jar

Manually Copy from Launcher

Best for: Quick testing. Annoying to keep updated.

Find the files in your launcher installation folder:

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

List the content of the directory:

ls

Expected output:

    Directory: C:\Users\...\Hytale\install\release\package\game\latest

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        12/25/2025   9:25 PM                Client
d-----        12/25/2025   9:25 PM                Server
-a----        12/25/2025   9:04 PM     3298097359 Assets.zip

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

Hytale Downloader CLI

Best for: Production servers. Easy to keep updated.

A command-line tool to download Hytale server and asset files with OAuth2 authentication. See QUICKSTART.md inside the archive.

Download: hytale-downloader.zip (Linux & Windows)

Bootstrap from HytaleServer.jar

Best for: Installing from just HytaleServer.jar with no separate downloader.

--bootstrap starts the server in a minimal mode that loads only the plugins needed to authenticate and download the rest of the server payload (JAR, Assets.zip, launcher scripts). The server extracts everything into the current directory and shuts down so the real launcher scripts can take over.

1. Place HytaleServer.jar in an empty directory and start it in bootstrap mode:

   java -jar HytaleServer.jar --bootstrap

2. Authenticate the server (see Authentication below):

   /auth login device

3. Run /update setup (or /update download).

4. The install extracts the payload into the cwd, sets +x on start.sh (on Unix), migrates auth.enc, auth.key, and config.json into Server/, deletes the installer JAR (on Unix), and shuts the server down. The resulting layout:

   game/
   ├── Assets.zip
   ├── start.sh
   ├── start.bat
   └── Server/
       ├── HytaleServer.jar
       ├── auth.enc
       ├── auth.key
       └── config.json

5. Start the real server with the launcher script:

   ./start.sh
   # or on Windows:
   start.bat

   The credentials from step 2 are carried over, so the server is authenticated on first boot.

Note: On Windows the installer JAR cannot delete itself while it is running; remove it manually after the bootstrap server shuts down.

Running a Hytale Server

Start the server with:

java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip

Authentication

After first launch, authenticate your server.

> /auth login device
===================================================================
DEVICE AUTHORIZATION
===================================================================
Visit: https://accounts.hytale.com/device
Enter code: ABCD-1234
Or visit: https://accounts.hytale.com/device?user_code=ABCD-1234
===================================================================
Waiting for authorization (expires in 900 seconds)...

[User completes authorization in browser]

> Authentication successful! Mode: OAUTH_DEVICE

Once authenticated, your server can accept player connections.

Additional Authentication Information

Hytale Servers require authentication to enable communication with our service APIs and to counter abuse.

Note: There is a limit of 500 servers per Hytale game license to prevent early abuse. If you require additional capacity, please reach out to our support team here.

If you need to authenticate a large amount of servers or dynamically authenticate servers automatically, please read the Server Provider Authentication Guide for detailed information.

Help

Review all available arguments:

java -jar HytaleServer.jar --help

Expected output:

Option                                   Description
------                                   -----------
--accept-early-plugins                   Acknowledge that loading early plugins
                                           is unsupported and may cause stability issues
--allow-op
--assets <Path>                          Asset directory (default: ..\HytaleAssets)
--auth-mode <authenticated|offline>      Authentication mode (default: AUTHENTICATED)
-b, --bind <InetSocketAddress>           Address to listen on (default: 0.0.0.0:5520)
--backup                                 Enable automatic backups
--backup-dir <Path>                      Backup directory
--backup-frequency <Integer>             Backup interval in minutes (default: 30)
[...]

Port

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

java -jar HytaleServer.jar --assets Assets.zip --bind 3500

Firewall & Network Configuration

Hytale uses the QUIC protocol over UDP (not TCP). Configure your firewall and port forwarding accordingly.

Port Forwarding

If hosting behind a router, forward UDP port 5520 (or your custom port) to your server machine. TCP forwarding is not required.

Firewall Rules

Windows Defender Firewall:

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

Linux (iptables):

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

Linux (ufw):

sudo ufw allow 5520/udp

NAT Considerations

QUIC handles NAT traversal well in most cases. If players have trouble connecting:

• Ensure the port forward is specifically for UDP, not TCP
• Symmetric NAT configurations may cause issues - consider a VPS or dedicated server
• Players behind carrier-grade NAT (common on mobile networks) should connect fine as clients

File Structure

Universe Structure

The universe/worlds/ directory contains all playable worlds. Each world has its own config.json:

{
  "Version": 4,
  "UUID": {
    "$binary": "j2x/idwTQpen24CDfH1+OQ==",
    "$type": "04"
  },
  "Seed": 1767292261384,
  "WorldGen": {
    "Type": "Hytale",
    "Name": "Default"
  },
  "WorldMap": {
    "Type": "WorldGen"
  },
  "ChunkStorage": {
    "Type": "Hytale"
  },
  "ChunkConfig": {},
  "IsTicking": true,
  "IsBlockTicking": true,
  "IsPvpEnabled": false,
  "IsFallDamageEnabled": true,
  "IsGameTimePaused": false,
  "GameTime": "0001-01-01T08:26:59.761606129Z",
  "RequiredPlugins": {},
  "IsSpawningNPC": true,
  "IsSpawnMarkersEnabled": true,
  "IsAllNPCFrozen": false,
  "GameplayConfig": "Default",
  "IsCompassUpdating": true,
  "IsSavingPlayers": true,
  "IsSavingChunks": true,
  "IsUnloadingChunks": true,
  "IsObjectiveMarkersEnabled": true,
  "DeleteOnUniverseStart": false,
  "DeleteOnRemove": false,
  "ResourceStorage": {
    "Type": "Hytale"
  },
  "Plugin": {}
}

Each world runs on its own main thread and off-loads parallel work into a shared thread pool.

Tips & Tricks

Installing Mods

Download mods (.zip or .jar) from sources like CurseForge and drop them into the mods/ folder.

Disable Sentry Crash Reporting

Important: Disable Sentry during active plugin development.

We use Sentry to track crashes. Disable it with --disable-sentry to avoid submitting your development errors:

java -jar HytaleServer.jar --assets Assets.zip --disable-sentry

Leverage Ahead-Of-Time Cache

The server ships with a pre-trained AOT cache (HytaleServer.aot) that improves boot times by skipping JIT warmup. See JEP-514.

java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip

Recommended Plugins

Our development partners at Nitrado and Apex Hosting maintain plugins for common server hosting needs:

View Distance

View distance is the main driver for RAM usage. We recommend limiting maximum view distance to 12 chunks (384 blocks) for both performance and gameplay.

For comparison: Minecraft servers default to 10 chunks (160 blocks). Hytale's default of 384 blocks is roughly equivalent to 24 Minecraft chunks. Expect higher RAM usage with default settings - tune this value based on your expected player count.

Multiserver Architecture

Hytale supports native mechanisms for routing players between servers. No reverse proxy like BungeeCord is required.

Player Referral

Transfers a connected player to another server. The server sends a referral packet containing the target host, port, and an optional 4KB payload. The client opens a new connection to the target and presents the payload during handshake.

PlayerRef.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data)

⚠️ Security Warning: The payload is transmitted through the client and can be tampered with. Sign payloads cryptographically (e.g., HMAC with a shared secret) so the receiving server can verify authenticity.

Use cases: Transferring players between game servers, passing session context, gating access behind matchmaking.

Coming Soon: Array of targets tried in sequence for fallback connections.

Connection Redirect

During connection handshake, a server can reject the player and redirect them to a different server. The client automatically connects to the redirected address.

PlayerSetupConnectEvent.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data)

Use cases: Load balancing, regional server routing, enforcing lobby-first connections.

Disconnect Fallback

When a player is unexpectedly disconnected (server crash, network interruption), the client automatically reconnects to a pre-configured fallback server instead of returning to the main menu.

Use cases: Returning players to a lobby after game server crash, maintaining engagement during restarts.

Coming Soon: Fallback packet implementation expected within weeks after Early Access launch.

Building a Proxy

Build custom proxy servers using Netty QUIC. Hytale uses QUIC exclusively for client-server communication.

Packet definitions and protocol structure are available in HytaleServer.jar:

com.hypixel.hytale.protocol.packets

Use these to decode, inspect, modify, or forward traffic between clients and backend servers.

Auto-Updating

The server has a built-in update system that can check for, download, and apply updates automatically.

How It Works

1. The server periodically checks for new versions (default: every hour)
2. When a new version is found, it downloads the update to a staging directory (updater/staging/)
3. When the update is ready to apply, the server shuts down with exit code 8
4. The wrapper script detects exit code 8, loops back to the start, applies the staged files (selectively replacing only server binaries and assets while preserving config, saves, and mods), and starts the new version

The update system requires a specific folder layout:

game/
├── Assets.zip
├── start.sh          (or start.bat on Windows)
├── jvm.options       (optional, custom JVM arguments)
└── Server/
    ├── HytaleServer.jar
    ├── HytaleServer.aot
    ├── config.json
    └── ...

The server must be started from the Server/ directory, and the parent directory must contain Assets.zip and the launcher script. If this layout is not detected, the update checker is disabled.

The easiest way to produce this layout is to install via Bootstrap from HytaleServer.jar - the bootstrap install writes everything into the correct layout on first run. The Hytale Downloader CLI also sets up this layout automatically.

If you copied files manually and don't have the wrapper scripts, you can generate them from a running server:

• /update setup extracts the embedded wrapper scripts (start.sh and start.bat) to the parent directory. No download required
• /update download --force re-downloads the current version to staging, including wrapper scripts and assets. Use this when you also want fresh copies of all server files.

Update Commands

Updates can be disabled entirely with the HYTALE_DISABLE_UPDATES environment variable.

Update Configuration

Update settings are in config.json under Update:

{
  "Update": {
    "Enabled": true,
    "CheckIntervalSeconds": 3600,
    "NotifyPlayersOnAvailable": true,
    "Patchline": null,
    "RunBackupBeforeUpdate": true,
    "BackupConfigBeforeUpdate": true,
    "AutoApplyMode": "Disabled",
    "AutoApplyDelayMinutes": 30
  }
}

AutoApplyMode options:

Wrapper Scripts

• Staged update application at the start of each launch cycle (selective file replacement that preserves config, saves, and mods)
• Custom JVM arguments via a jvm.options file (one argument per line, supports comments with #)
• Default backup settings (--backup --backup-dir backups --backup-frequency 30)
• Post-update crash detection with rollback instructions if the server crashes shortly after an update

Linux (start.sh):

#!/bin/bash
# Hytale Server Launcher
# This script handles staged updates and starts the server with default arguments.
#
# CUSTOM JVM ARGUMENTS
# --------------------
# To customize JVM arguments (e.g., memory settings), create a file named
# "jvm.options" in the same directory as this script. One argument per line.
# Lines starting with # are comments.
#
# Example jvm.options:
#   -Xms2G
#   -Xmx4G
#   -XX:+UseG1GC

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
cd "$SCRIPT_DIR"

while true; do
    APPLIED_UPDATE=false

    # Apply staged update if present
    if [ -f "updater/staging/Server/HytaleServer.jar" ]; then
        echo "[Launcher] Applying staged update..."
        # Only replace update files, preserve config/saves/mods
        cp -f updater/staging/Server/HytaleServer.jar Server/
        [ -d "updater/staging/Server/Licenses" ] && rm -rf Server/Licenses && cp -r updater/staging/Server/Licenses Server/
        [ -f "updater/staging/Assets.zip" ] && cp -f updater/staging/Assets.zip ./
        [ -f "updater/staging/start.sh" ] && cp -f updater/staging/start.sh ./
        [ -f "updater/staging/start.bat" ] && cp -f updater/staging/start.bat ./
        rm -rf updater/staging
        APPLIED_UPDATE=true
    fi

    # Run server from inside Server/ folder so config/backups/etc. are generated there
    cd Server

    # Load custom JVM arguments from jvm.options if it exists (uses JVM's @-file syntax)
    JVM_OPTS=""
    [ -f "../jvm.options" ] && JVM_OPTS="@../jvm.options"

    # Default server arguments
    # --assets: Assets.zip is in parent directory
    # --backup: Enable periodic backups like singleplayer
    DEFAULT_ARGS="--assets ../Assets.zip --backup --backup-dir backups --backup-frequency 30"

    # Start server and track time
    START_TIME=$(date +%s)
    java $JVM_OPTS -jar HytaleServer.jar $DEFAULT_ARGS "$@"
    EXIT_CODE=$?
    ELAPSED=$(( $(date +%s) - START_TIME ))

    # Return to script dir for next iteration
    cd "$SCRIPT_DIR"

    # Exit code 8 = restart for update
    if [ $EXIT_CODE -eq 8 ]; then
        echo "[Launcher] Restarting to apply update..."
        continue
    fi

    # Warn on crash shortly after update
    if [ $EXIT_CODE -ne 0 ] && [ "$APPLIED_UPDATE" = true ] && [ $ELAPSED -lt 30 ]; then
        echo ""
        echo "[Launcher] ERROR: Server exited with code $EXIT_CODE within ${ELAPSED}s of starting."
        echo "[Launcher] This may indicate the update failed to start correctly."
        echo "[Launcher]"
        echo "[Launcher] Your previous files are in the updater/backup/ folder."
        echo "[Launcher] To rollback: delete Server/ and Assets.zip, then move from updater/backup/"
        echo ""
        # Only prompt if running interactively (has terminal)
        if [ -t 0 ]; then
            read -p "Press Enter to exit..."
        fi
    fi

    exit $EXIT_CODE
done

Windows (start.bat):

@echo off
rem Hytale Server Launcher
rem This script handles staged updates and starts the server with default arguments.
rem
rem CUSTOM JVM ARGUMENTS
rem --------------------
rem To customize JVM arguments (e.g., memory settings), create a file named
rem "jvm.options" in the same directory as this script. One argument per line.
rem Lines starting with # are comments.
rem
rem Example jvm.options:
rem   -Xms2G
rem   -Xmx4G
rem   -XX:+UseG1GC

set SCRIPT_DIR=%~dp0
cd /d "%SCRIPT_DIR%"

:start
set APPLIED_UPDATE=0

rem Apply staged update if present (from script dir)
cd /d "%SCRIPT_DIR%"
if exist updater\staging\Server\HytaleServer.jar (
    echo [Launcher] Applying staged update...
    rem Only replace update files, preserve config/saves/mods
    copy /y updater\staging\Server\HytaleServer.jar Server\ >nul
    if exist updater\staging\Server\Licenses rmdir /s /q Server\Licenses 2>nul & xcopy /s /e /i /y updater\staging\Server\Licenses Server\Licenses >nul
    if exist updater\staging\Assets.zip copy /y updater\staging\Assets.zip .\ >nul
    if exist updater\staging\start.bat copy /y updater\staging\start.bat .\ >nul
    if exist updater\staging\start.sh copy /y updater\staging\start.sh .\ >nul
    rmdir /s /q updater\staging 2>nul
    set APPLIED_UPDATE=1
)

rem Run server from inside Server/ folder so config/backups/etc. are generated there
cd Server

rem Load custom JVM arguments from jvm.options if it exists (uses JVM's @-file syntax)
set JVM_OPTS=
if exist ..\jvm.options set JVM_OPTS=@..\jvm.options

rem Default server arguments
rem --assets: Assets.zip is in parent directory
rem --backup: Enable periodic backups like singleplayer
set DEFAULT_ARGS=--assets ../Assets.zip --backup --backup-dir backups --backup-frequency 30

rem Start server
java %JVM_OPTS% -jar HytaleServer.jar %DEFAULT_ARGS% %*
set EXIT_CODE=%ERRORLEVEL%

rem Return to script dir
cd /d "%SCRIPT_DIR%"

rem Handle exit code 8 (restart for update)
if %EXIT_CODE%==8 goto :start

rem Warn on crash after update (batch timing is limited, so warn on any post-update crash)
if %EXIT_CODE% NEQ 0 if %APPLIED_UPDATE%==1 (
    echo.
    echo [Launcher] ERROR: Server exited with code %EXIT_CODE% after update.
    echo [Launcher] This may indicate the update failed to start correctly.
    echo [Launcher]
    echo [Launcher] Your previous files are in the updater/backup/ folder.
    echo [Launcher] To rollback: delete Server/ and Assets.zip, then move from updater/backup/
    echo.
    pause
)

exit /b %EXIT_CODE%

The scripts only restart on exit code 8 (update). Any other exit code (normal shutdown, crash, etc.) stops the loop. If the server crashes shortly after an update was applied, the script warns you and points to the backup directory for rollback.

Misc Details

Java Command-Line Arguments

See Guide to the Most Important JVM Parameters for topics like -Xms and -Xmx to control heap size.

Protocol Updates

The Hytale protocol uses a hash to verify client-server compatibility. If hashes don't match exactly, the connection is rejected.

Current Limitation: Client and server must be on the exact same protocol version. When we release an update, servers must update immediately or players on the new version cannot connect.

Coming Soon: Protocol tolerance allowing ±2 version difference between client and server. Server operators will have a window to update without losing player connectivity.

Configuration Files

Configuration files (config.json, permissions.json, etc.) are read on server startup and written to when in-game actions occur (e.g., assigning permissions via commands). Manual changes while the server is running are likely to be overwritten.

Maven Artifact

The HytaleServer jar will be published to a maven repository for use as a dependency in modding projects.

Add the repository to your pom.xml:

<repositories>
    <!-- Hytale release repository -->
    <repository>
        <id>hytale-release</id>
        <url>https://maven.hytale.com/release</url>
    </repository>
    <!-- Hytale pre-release repository -->
    <repository>
        <id>hytale-pre-release</id>
        <url>https://maven.hytale.com/pre-release</url>
    </repository>
</repositories>

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.hypixel.hytale</groupId>
    <artifactId>Server</artifactId>
    <!-- Replace with latest version, we provide jars for the last five releases -->
    <version>2026.01.22-6f8bdbdc4</version>
</dependency>

The latest version can be found on: 

• Release: https://maven.hytale.com/release/com/hypixel/hytale/Server/maven-metadata.xml
• Pre-Release: https://maven.hytale.com/pre-release/com/hypixel/hytale/Server/maven-metadata.xml

Future Additions

Server & Minigame Discovery

A discovery catalogue accessible from the main menu where players can browse and find servers and minigames. Server operators can opt into the catalogue to promote their content directly to players.

Requirements for listing:

Player Count Verification:

Player counts displayed in server discovery are gathered from client telemetry rather than server-reported data. This prevents count spoofing and ensures players can trust the numbers they see when browsing servers. Servers will still be able to report an unverified player count to users, who added the server outside of server discovery.

Parties

A party system enabling players to group up and stay together across server transfers and minigame queues.

Integration with server discovery:

Players can browse servers with their party and join together. Party size requirements and restrictions are visible before joining, so groups know upfront if they can play together.

This system provides the foundation for a seamless social experience where friends can move through the Hytale ecosystem as a group without manual coordination.

Integrated Payment System

A payment gateway built into the client that servers can use to accept payments from players. Optional but encouraged.

Benefits for server operators:

• Accept payments without handling payment details or building infrastructure
• Transactions processed through a trusted, secure system

Benefits for players:

• No need to visit external websites
• All transactions are secure and traceable
• Payment information stays within the Hytale ecosystem

SRV Record Support

SRV records allow players to connect using a domain name (e.g., play.example.com) without specifying a port, with DNS handling the lookup to resolve the actual server address and port.

Current Status: Unsupported. Under evaluation.

Why it's not available yet:

There is no battle-tested C# library for SRV record resolution. Existing options either require pulling in a full DNS client implementation, which introduces unnecessary complexity and potential stability risks, or lack the production readiness we require for a core networking feature.

We are evaluating alternatives and will revisit this when a suitable solution exists.

First-Party API Endpoints

Authenticated servers will have access to official API endpoints for player data, versioning, and server operations. These endpoints reduce the need for third-party services and provide authoritative data directly from Hytale.

Planned Endpoints:

Under Consideration:

Design Goals:

• Generous rate limits: Bulk endpoints and caching-friendly responses to support large networks
• Authenticated access: All endpoints require server authentication to prevent abuse
• Versioned API: Stable contracts with deprecation windows for breaking changes