{"article":{"id":45326769420827,"url":"https://hypixelstudios.zendesk.com/api/v2/help_center/en-us/articles/45326769420827.json","html_url":"https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual","author_id":44683878502555,"comments_disabled":true,"draft":false,"promoted":false,"position":0,"vote_sum":0,"vote_count":0,"upvote_count":0,"downvote_count":0,"section_id":45383871296539,"created_at":"2026-01-11T17:37:24Z","updated_at":"2026-10-12T19:48:54Z","name":"Hytale Server Manual","title":"Hytale Server Manual","source_locale":"en-us","locale":"en-us","outdated":false,"outdated_locales":[],"edited_at":"2026-10-12T19:48:53Z","user_segment_id":null,"permission_group_id":41690582981403,"content_tag_ids":[],"label_names":[],"body":"

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

\n

\n Intended Audience: Server administrators and players hosting dedicated servers.\n

\n

Contents

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Section

Topics

Server SetupJava installation, server files, system requirements
Running a Hytale ServerLaunch commands, authentication, ports, firewall, file structure
Tips & TricksMods, AOT cache, Sentry, recommended plugins, view distance
Multiserver ArchitecturePlayer referral, redirects, fallbacks, building proxies
Auto UpdatingUpdate commands, configuration, wrapper scripts
Misc DetailsJVM arguments, protocol updates, configuration files
Future AdditionsServer discovery, parties, integrated payments, SRV records, API endpoints

 

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:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Resource

Driver

CPUHigh player or entity counts (NPCs, mobs)
RAMLarge loaded world area (high view distance, players exploring independently)

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\nOpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)\nOpenJDK 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:

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

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\nLinux: $XDG_DATA_HOME/Hytale/install/release/package/game/latest\nMacOS: ~/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\n\nMode                 LastWriteTime         Length Name\n----                 -------------         ------ ----\nd-----        12/25/2025   9:25 PM                Client\nd-----        12/25/2025   9:25 PM                Server\n-a----        12/25/2025   9:04 PM     3298097359 Assets.zip\n

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)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Command

Description

./hytale-downloaderDownload latest release
./hytale-downloader -print-versionShow game version without downloading
./hytale-downloader -versionShow hytale-downloader version
./hytale-downloader -check-updateCheck for hytale-downloader updates
./hytale-downloader -download-path game.zipDownload to specific file
./hytale-downloader -patchline pre-releaseDownload from pre-release channel
./hytale-downloader -skip-update-checkSkip automatic update check

 

Bootstrap from HytaleServer.jar\n

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.

    \n
  1. \n

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

    \n
    java -jar HytaleServer.jar --bootstrap
    \n
    2. \n
  2. \n

    Authenticate the server (see Authentication below):

    \n
    /auth login device
    \n
    3. \n
  3. Run /update setup (or /update download).
    4. \n
  4. \n

    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:

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

    Start the real server with the launcher script:

    \n
    ./start.sh\n# or on Windows:\nstart.bat
    \n

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

    \n
    6. \n

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\n===================================================================\nDEVICE AUTHORIZATION\n===================================================================\nVisit: https://accounts.hytale.com/device\nEnter code: ABCD-1234\nOr visit: https://accounts.hytale.com/device?user_code=ABCD-1234\n===================================================================\nWaiting for authorization (expires in 900 seconds)...\n\n[User completes authorization in browser]\n\n> 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, you can purchase another Hytale game license 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\n------                                   -----------\n--accept-early-plugins                   Acknowledge that loading early plugins\n                                           is unsupported and may cause stability issues\n--allow-op\n--assets <Path>                          Asset directory (default: ..\\HytaleAssets)\n--auth-mode <authenticated|offline>      Authentication mode (default: AUTHENTICATED)\n-b, --bind <InetSocketAddress>           Address to listen on (default: 0.0.0.0:5520)\n--backup                                 Enable automatic backups\n--backup-dir <Path>                      Backup directory\n--backup-frequency <Integer>             Backup interval in minutes (default: 30)\n[...]

Port

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

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

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:

File Structure

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Path

Description

.cache/Cache for optimized files
logs/Server log files
mods/Installed mods
universe/World and player save data
bans.jsonBanned players
config.jsonServer configuration
permissions.jsonPermission configuration
whitelist.jsonWhitelisted players

Universe Structure

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

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

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:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Plugin

Description

Nitrado:WebServerBase plugin for web applications and APIs
Nitrado:QueryExposes server status (player counts, etc.) via HTTP
Nitrado:PerformanceSaverDynamically limits view distance based on resource usage
ApexHosting:PrometheusExporterExposes detailed server and JVM metrics

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

    \n
  1. The server periodically checks for new versions (default: every hour)
    2. \n
  2. When a new version is found, it downloads the update to a staging directory (updater/staging/)
    3. \n
  3. When the update is ready to apply, the server shuts down with exit code 8\n
    4. \n
  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
    5. \n

The update system requires a specific folder layout:

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

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 Commands

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Command

Description

/update checkCheck for available updates
/update downloadDownload available update to staging
/update download --forceDownload even if already on the latest version (useful for bootstrapping the update layout)
/update apply --confirmApply staged update (backs up files, then shuts down with exit code 8)
/update cancelCancel and delete staged update
/update statusShow current version and update status
/update patchline [name]Show or set the update patchline
/update setup\nWrite the wrapper scripts (start.sh/start.bat) to the parent directory. Requires the server to be running from a Server/ directory (use --force to override)\n

Updates can be disabled entirely with the HYTALE_DISABLE_UPDATES environment variable.

 

Update Configuration

Update settings are in config.json under Update:

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

Command

Default

Description
EnabledtrueEnable automatic update checks
CheckIntervalSeconds3600Seconds between update checks
NotifyPlayersOnAvailabletrueNotify players with permission when an update is available
PatchlinenullOverride the update patchline (defaults to the build's patchline, usually release)
RunBackupBeforeUpdatetrueRun a full server backup before applying an update (requires backup directory to be configured)
BackupConfigBeforeUpdatetrue\nBackup config files (config.json, permissions.json, bans.json, whitelist.json) before applying\n
AutoApplyModeDisabledHow to auto-apply staged updates. See below
AutoApplyDelayMinutes30\nMinutes to wait before applying in Scheduled mode\n

 

AutoApplyMode options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Mode

Behavior

Disabled\nNever auto-apply. Requires manual /update apply --confirm\n
WhenEmptyApply automatically when no players are online
ScheduledApply after AutoApplyDelayMinutes even with players online, warning them periodically

 

Wrapper Scripts

The server does not restart itself. When an update is applied, the server shuts down with exit code 8. The wrapper scripts included with the server detect this exit code and apply the staged files before restarting.
\n
 
\n
The wrapper scripts are included in the server download and are also updated during self-updates. They provide:
\n

Linux (start.sh):

#!/bin/bash\n# Hytale Server Launcher\n# This script handles staged updates and starts the server with default arguments.\n#\n# CUSTOM JVM ARGUMENTS\n# --------------------\n# To customize JVM arguments (e.g., memory settings), create a file named\n# \"jvm.options\" in the same directory as this script. One argument per line.\n# Lines starting with # are comments.\n#\n# Example jvm.options:\n#   -Xms2G\n#   -Xmx4G\n#   -XX:+UseG1GC\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\ncd \"$SCRIPT_DIR\"\n\nwhile true; do\n    APPLIED_UPDATE=false\n\n    # Apply staged update if present\n    if [ -f \"updater/staging/Server/HytaleServer.jar\" ]; then\n        echo \"[Launcher] Applying staged update...\"\n        # Only replace update files, preserve config/saves/mods\n        cp -f updater/staging/Server/HytaleServer.jar Server/\n        [ -d \"updater/staging/Server/Licenses\" ] && rm -rf Server/Licenses && cp -r updater/staging/Server/Licenses Server/\n        [ -f \"updater/staging/Assets.zip\" ] && cp -f updater/staging/Assets.zip ./\n        [ -f \"updater/staging/start.sh\" ] && cp -f updater/staging/start.sh ./\n        [ -f \"updater/staging/start.bat\" ] && cp -f updater/staging/start.bat ./\n        rm -rf updater/staging\n        APPLIED_UPDATE=true\n    fi\n\n    # Run server from inside Server/ folder so config/backups/etc. are generated there\n    cd Server\n\n    # Load custom JVM arguments from jvm.options if it exists (uses JVM's @-file syntax)\n    JVM_OPTS=\"\"\n    [ -f \"../jvm.options\" ] && JVM_OPTS=\"@../jvm.options\"\n\n    # Default server arguments\n    # --assets: Assets.zip is in parent directory\n    # --backup: Enable periodic backups like singleplayer\n    DEFAULT_ARGS=\"--assets ../Assets.zip --backup --backup-dir backups --backup-frequency 30\"\n\n    # Start server and track time\n    START_TIME=$(date +%s)\n    java $JVM_OPTS -jar HytaleServer.jar $DEFAULT_ARGS \"$@\"\n    EXIT_CODE=$?\n    ELAPSED=$(( $(date +%s) - START_TIME ))\n\n    # Return to script dir for next iteration\n    cd \"$SCRIPT_DIR\"\n\n    # Exit code 8 = restart for update\n    if [ $EXIT_CODE -eq 8 ]; then\n        echo \"[Launcher] Restarting to apply update...\"\n        continue\n    fi\n\n    # Warn on crash shortly after update\n    if [ $EXIT_CODE -ne 0 ] && [ \"$APPLIED_UPDATE\" = true ] && [ $ELAPSED -lt 30 ]; then\n        echo \"\"\n        echo \"[Launcher] ERROR: Server exited with code $EXIT_CODE within ${ELAPSED}s of starting.\"\n        echo \"[Launcher] This may indicate the update failed to start correctly.\"\n        echo \"[Launcher]\"\n        echo \"[Launcher] Your previous files are in the updater/backup/ folder.\"\n        echo \"[Launcher] To rollback: delete Server/ and Assets.zip, then move from updater/backup/\"\n        echo \"\"\n        # Only prompt if running interactively (has terminal)\n        if [ -t 0 ]; then\n            read -p \"Press Enter to exit...\"\n        fi\n    fi\n\n    exit $EXIT_CODE\ndone

Windows (start.bat):

@echo off\nrem Hytale Server Launcher\nrem This script handles staged updates and starts the server with default arguments.\nrem\nrem CUSTOM JVM ARGUMENTS\nrem --------------------\nrem To customize JVM arguments (e.g., memory settings), create a file named\nrem \"jvm.options\" in the same directory as this script. One argument per line.\nrem Lines starting with # are comments.\nrem\nrem Example jvm.options:\nrem   -Xms2G\nrem   -Xmx4G\nrem   -XX:+UseG1GC\n\nset SCRIPT_DIR=%~dp0\ncd /d \"%SCRIPT_DIR%\"\n\n:start\nset APPLIED_UPDATE=0\n\nrem Apply staged update if present (from script dir)\ncd /d \"%SCRIPT_DIR%\"\nif exist updater\\staging\\Server\\HytaleServer.jar (\n    echo [Launcher] Applying staged update...\n    rem Only replace update files, preserve config/saves/mods\n    copy /y updater\\staging\\Server\\HytaleServer.jar Server\\ >nul\n    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\n    if exist updater\\staging\\Assets.zip copy /y updater\\staging\\Assets.zip .\\ >nul\n    if exist updater\\staging\\start.bat copy /y updater\\staging\\start.bat .\\ >nul\n    if exist updater\\staging\\start.sh copy /y updater\\staging\\start.sh .\\ >nul\n    rmdir /s /q updater\\staging 2>nul\n    set APPLIED_UPDATE=1\n)\n\nrem Run server from inside Server/ folder so config/backups/etc. are generated there\ncd Server\n\nrem Load custom JVM arguments from jvm.options if it exists (uses JVM's @-file syntax)\nset JVM_OPTS=\nif exist ..\\jvm.options set JVM_OPTS=@..\\jvm.options\n\nrem Default server arguments\nrem --assets: Assets.zip is in parent directory\nrem --backup: Enable periodic backups like singleplayer\nset DEFAULT_ARGS=--assets ../Assets.zip --backup --backup-dir backups --backup-frequency 30\n\nrem Start server\njava %JVM_OPTS% -jar HytaleServer.jar %DEFAULT_ARGS% %*\nset EXIT_CODE=%ERRORLEVEL%\n\nrem Return to script dir\ncd /d \"%SCRIPT_DIR%\"\n\nrem Handle exit code 8 (restart for update)\nif %EXIT_CODE%==8 goto :start\n\nrem Warn on crash after update (batch timing is limited, so warn on any post-update crash)\nif %EXIT_CODE% NEQ 0 if %APPLIED_UPDATE%==1 (\n    echo.\n    echo [Launcher] ERROR: Server exited with code %EXIT_CODE% after update.\n    echo [Launcher] This may indicate the update failed to start correctly.\n    echo [Launcher]\n    echo [Launcher] Your previous files are in the updater/backup/ folder.\n    echo [Launcher] To rollback: delete Server/ and Assets.zip, then move from updater/backup/\n    echo.\n    pause\n)\n\nexit /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.

\n

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.

\n

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

\n

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>\n    <!-- Hytale release repository -->\n    <repository>\n        <id>hytale-release</id>\n        <url>https://maven.hytale.com/release</url>\n    </repository>\n    <!-- Hytale pre-release repository -->\n    <repository>\n        <id>hytale-pre-release</id>\n        <url>https://maven.hytale.com/pre-release</url>\n    </repository>\n</repositories>

Add the dependency to your pom.xml:

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

The latest version can be found on: 

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:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Requirement

Description

Server Operator GuidelinesServers must adhere to operator guidelines and community standards
Self-RatingOperators must accurately rate their server content. Ratings power content filtering and parental controls
EnforcementServers violating their self-rating are subject to enforcement actions per server operator policies

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:

Benefits for players:

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:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Endpoint

Description

UUID ↔ Name LookupResolve player names to UUIDs and vice versa. Supports single and bulk lookups
Game VersionQuery current game version, protocol version, and check for updates
Player ProfileFetch player profile data including cosmetics, avatar renders, and public profile information
Server TelemetryReport server status, player count, and metadata for discovery integration
ReportReport players for ToS violations
PaymentsProcess payments using our built-in payment gate

Under Consideration:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Endpoint

Description

Global SanctionsQuery whether a player has platform-level sanctions (not server-specific bans)
Friends ListRetrieve a player's friends list (with appropriate permissions) for social features
Webhook SubscriptionsSubscribe to push notifications for events like player name changes or sanction updates

Design Goals:

"}}