Hytale Advanced Server Configuration: Difference between revisions

From Survival Servers
Jump to navigation Jump to search
(Created page with "This guide covers advanced Hytale server configuration for experienced administrators. Topics include world pre-generation, server mesh architecture, and detailed JSON configuration options. == Before You Start == This guide assumes you're familiar with: * Basic Hytale server setup (see How to Create a Hytale Server Guide) * Editing JSON files * Using FTP or file management tools '''Important:''' Always back up your server files before making configuration changes...")
 
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
This guide covers advanced Hytale server configuration for experienced administrators. Topics include world pre-generation, server mesh architecture, and detailed JSON configuration options.
This guide covers advanced Hytale server configuration including world settings, command-line arguments, and server mesh architecture.
 
== Before You Start ==
 
This guide assumes you're familiar with:
* Basic Hytale server setup (see [[How to Create a Hytale Server Guide]])
* Editing JSON files
* Using FTP or file management tools


'''Important:''' Always back up your server files before making configuration changes. Stop your server before editing any configuration files.
'''Important:''' Always back up your server files before making configuration changes. Stop your server before editing any configuration files.


== Server Configuration Files ==
== Configuration File Locations ==
 
Your Hytale server uses several JSON files to control its behavior:


{| class="wikitable"
{| class="wikitable"
|-
|-
! File !! Purpose
! File !! Location !! Purpose
|-
|-
| <code>config.json</code> || Main server settings (name, max players, network settings)
| <code>config.json</code> || Server root folder || Main server settings
|-
|-
| <code>permissions.json</code> || Player roles, permissions, and admin access
| <code>permissions.json</code> || Server root folder || Player roles and permissions
|-
|-
| <code>bans.json</code> || Banned player list
| <code>bans.json</code> || Server root folder || Banned player list
|-
|-
| <code>whitelist.json</code> || Allowed players (when whitelist is enabled)
| <code>whitelist.json</code> || Server root folder || Allowed players list
|-
|-
| <code>universe/worlds/[WorldName]/config.json</code> || Per-world settings
| <code>config.json</code> || <code>universe/worlds/[WorldName]/</code> || Per-world settings
|}
|}


== Main Server Configuration (config.json) ==
== Server Configuration (config.json) ==
 
The main <code>config.json</code> file controls your server's core settings.
 
=== For Survival Servers Customers ===


# Log into your [https://www.survivalservers.com/sspanel/ control panel]
The main <code>config.json</code> in your server root controls server-wide settings:
# Click '''Configuration Files''' or '''Config Editor'''
# Select <code>config.json</code>
# Make your changes and click '''Save'''
# Restart your server
 
=== For Self-Hosted Servers ===
 
# Stop your server
# Open <code>config.json</code> in a text editor
# Make your changes and save
# Start your server
 
=== Common Server Settings ===


<pre>
<pre>
{
{
   "ServerName": "My Hytale Server",
  "Version": 3,
   "MaxPlayers": 20,
   "ServerName": "Hytale Server",
   "MOTD": "Welcome to my server!",
  "MOTD": "",
   "ViewDistance": 12,
  "Password": "",
   "SimulationDistance": 10,
   "MaxPlayers": 100,
   "WhitelistEnabled": false,
  "MaxViewRadius": 32,
   "Difficulty": "Normal"
  "LocalCompressionEnabled": false,
   "Defaults": {
    "World": "default",
    "GameMode": "Adventure"
  },
  "ConnectionTimeouts": {
    "JoinTimeouts": {}
  },
  "RateLimit": {},
  "Modules": {},
   "LogLevels": {},
   "Mods": {},
   "DisplayTmpTagsInStrings": false,
   "PlayerStorage": {
    "Type": "Hytale"
  }
}
}
</pre>
</pre>
Line 64: Line 53:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Setting !! Description !! Recommended Value
! Setting !! Description !! Recommended
|-
| <code>ServerName</code> || Display name shown to players || Your server name
|-
| <code>MOTD</code> || Message of the day || Short welcome message
|-
|-
| <code>ServerName</code> || Name shown to players || Your server name
| <code>Password</code> || Server password (empty = no password) || Leave empty for public
|-
|-
| <code>MaxPlayers</code> || Maximum concurrent players || Based on your RAM (10-20 for 4GB, 20-40 for 8GB)
| <code>MaxPlayers</code> || Maximum concurrent players || Based on RAM (20-50 typical)
|-
|-
| <code>ViewDistance</code> || How far players can see (in chunks) || 12 (default is higher but uses more RAM)
| <code>MaxViewRadius</code> || How far players can see (in chunks) || '''12''' for performance
|-
|-
| <code>SimulationDistance</code> || How far entities are active || 8-10 for better performance
| <code>LocalCompressionEnabled</code> || Enable local network compression || false
|-
|-
| <code>WhitelistEnabled</code> || Restrict to approved players only || false (public) or true (private)
| <code>Defaults.World</code> || Default world name players spawn in || "default"
|-
| <code>Defaults.GameMode</code> || Default game mode for new players || "Adventure" or "Creative"
|}
|}


'''Performance Tip:''' Lowering <code>ViewDistance</code> from the default significantly reduces RAM usage. The default of 384 blocks equals roughly 24 Minecraft chunks. A value of 12 chunks (384 blocks) is recommended for both performance and gameplay.
'''Performance Tip:''' The official Hytale manual recommends limiting <code>MaxViewRadius</code> to '''12 chunks (384 blocks)''' for both performance and gameplay. The default of 32 is equivalent to roughly 64 Minecraft chunks and will significantly increase RAM usage.
 
== Editing Configuration Files ==
 
=== For Survival Servers Customers ===
 
# Log into your [https://www.survivalservers.com/sspanel/ control panel]
# Click '''Stop''' to shut down your server
# Click '''Configuration Files''' or use '''FTP Access'''
# Edit the desired file and save
# Click '''Start''' to restart your server


== World Configuration ==
=== For Self-Hosted Servers ===


Each world has its own configuration file located at <code>universe/worlds/[WorldName]/config.json</code>.
# Stop your server (type <code>stop</code> or press <code>Ctrl+C</code>)
# Open the config file in a text editor
# Make your changes and save
# Start your server


=== World Config Options ===
== World Configuration (universe/worlds/[WorldName]/config.json) ==
 
Each world has its own configuration file. Below is the documented world config structure:


<pre>
<pre>
{
{
   "Version": 4,
   "Version": 4,
  "UUID": {
    "$binary": "j2x/idwTQpen24CDfH1+OQ==",
    "$type": "04"
  },
   "Seed": 1767292261384,
   "Seed": 1767292261384,
   "WorldGen": {
   "WorldGen": {
Line 93: Line 107:
     "Name": "Default"
     "Name": "Default"
   },
   },
  "WorldMap": {
    "Type": "WorldGen"
  },
  "ChunkStorage": {
    "Type": "Hytale"
  },
  "ChunkConfig": {},
   "IsTicking": true,
   "IsTicking": true,
   "IsBlockTicking": true,
   "IsBlockTicking": true,
Line 98: Line 119:
   "IsFallDamageEnabled": true,
   "IsFallDamageEnabled": true,
   "IsGameTimePaused": false,
   "IsGameTimePaused": false,
  "GameTime": "0001-01-01T08:26:59.761606129Z",
  "ClientEffects": {
    "SunHeightPercent": 100.0,
    "SunAngleDegrees": 0.0,
    "BloomIntensity": 0.30000001192092896,
    "BloomPower": 8.0,
    "SunIntensity": 0.25,
    "SunshaftIntensity": 0.30000001192092896,
    "SunshaftScaleFactor": 4.0
  },
  "RequiredPlugins": {},
   "IsSpawningNPC": true,
   "IsSpawningNPC": true,
   "IsSpawnMarkersEnabled": true,
   "IsSpawnMarkersEnabled": true,
   "IsAllNPCFrozen": false,
   "IsAllNPCFrozen": false,
   "GameplayConfig": "Default",
   "GameplayConfig": "Default",
  "IsCompassUpdating": true,
   "IsSavingPlayers": true,
   "IsSavingPlayers": true,
   "IsSavingChunks": true,
   "IsSavingChunks": true,
   "IsUnloadingChunks": true
  "SaveNewChunks": true,
   "IsUnloadingChunks": true,
  "IsObjectiveMarkersEnabled": true,
  "DeleteOnUniverseStart": false,
  "DeleteOnRemove": false,
  "ResourceStorage": {
    "Type": "Hytale"
  },
  "Plugin": {}
}
}
</pre>
</pre>
Line 110: Line 151:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Setting !! What It Does
! Setting !! Description
|-
| <code>Seed</code> || World generation seed
|-
| <code>IsPvpEnabled</code> || Allow player vs player combat
|-
| <code>IsFallDamageEnabled</code> || Players take fall damage
|-
|-
| <code>Seed</code> || World generation seed (determines terrain layout)
| <code>IsGameTimePaused</code> || Freeze day/night cycle
|-
|-
| <code>IsPvpEnabled</code> || Allow players to damage each other
| <code>IsSpawningNPC</code> || Enable mob spawning
|-
|-
| <code>IsFallDamageEnabled</code> || Players take damage from falling
| <code>IsAllNPCFrozen</code> || Freeze all NPCs in place
|-
|-
| <code>IsSpawningNPC</code> || Enable/disable mob spawning
| <code>IsTicking</code> || World simulation runs
|-
|-
| <code>IsAllNPCFrozen</code> || Freeze all NPCs (useful for building)
| <code>IsBlockTicking</code> || Block updates (crops, liquids)
|-
|-
| <code>IsGameTimePaused</code> || Stop day/night cycle
| <code>IsSavingPlayers</code> || Save player data
|-
|-
| <code>IsSavingChunks</code> || Save world changes (disable for temporary worlds)
| <code>IsSavingChunks</code> || Save world changes
|-
|-
| <code>IsUnloadingChunks</code> || Unload chunks when players leave (saves RAM)
| <code>SaveNewChunks</code> || Save newly generated chunks to disk
|-
| <code>IsUnloadingChunks</code> || Unload empty chunks
|-
| <code>ClientEffects</code> || Visual effects settings (sun, bloom, sunshafts)
|-
| <code>DeleteOnUniverseStart</code> || Delete world on server start
|-
| <code>DeleteOnRemove</code> || Delete world files when removed
|}
|}


== World Pre-Generation ==
== World Pre-Generation ==


Pre-generating your world creates terrain ahead of time, reducing lag when players explore new areas.
Pre-generating creates terrain ahead of time, reducing lag when players explore.
 
=== Why Pre-Generate? ===
 
* '''Reduces lag spikes''' - New chunks are already generated
* '''Smoother gameplay''' - No stuttering when exploring
* '''Better for events''' - Prepare large areas in advance
* '''Consistent performance''' - Server load is predictable
 
=== Pre-Generation Methods ===


'''Method 1: In-Game Exploration'''
'''Method 1: In-Game Exploration'''
 
# Start your server and log in as admin
The simplest method is to explore the world before opening to players:
# Start your server
# Log in as admin
# Fly around the map to generate chunks
# Fly around the map to generate chunks
# The server saves chunks as you explore
# The server saves chunks as you explore


'''Method 2: Using World Generation Tools'''
'''Method 2: Pre-Generation Mods'''
 
# Add a pre-gen mod to your <code>mods/</code> folder
When available, dedicated pre-generation tools or mods can generate large areas automatically:
# Install a pre-generation mod/plugin
# Configure the area size and center point
# Configure the area size and center point
# Run the pre-generation command
# Run the pre-generation command
# Wait for completion (can take hours for large areas)


'''Method 3: Command-Line Pre-Generation'''
'''Method 3: Command-Line'''
 
<pre>
Check <code>java -jar HytaleServer.jar --help</code> for pre-generation options. These may include flags to generate chunks without running the full server.
java -jar HytaleServer.jar --help
 
</pre>
=== Pre-Generation Tips ===
Check for built-in pre-generation options.
 
* '''Start small''' - Generate a 5000x5000 block area first
* '''Monitor resources''' - Pre-generation is CPU and storage intensive
* '''Schedule during off-hours''' - Run overnight when no players are online
* '''Backup first''' - Always backup before major generation tasks


== Server Mesh Architecture (Multi-Server Networks) ==
== Server Mesh Architecture (Multi-Server Networks) ==
Line 173: Line 208:
Hytale has built-in support for connecting multiple servers together without third-party proxies like BungeeCord.
Hytale has built-in support for connecting multiple servers together without third-party proxies like BungeeCord.


=== Use Cases for Server Meshes ===
These features are implemented via the server's Java API:


* '''Hub/Lobby servers''' - Central spawn with portals to game servers
{| class="wikitable"
* '''Minigame networks''' - Different servers for different game modes
|-
* '''Load distribution''' - Spread players across multiple servers
! Feature !! API Method !! Description
* '''Regional routing''' - Direct players to nearest server
|-
| '''Player Referral''' || <code>PlayerRef.referToServer(host, port, payload)</code> || Transfer players between servers with optional 4KB payload
|-
| '''Connection Redirect''' || <code>PlayerSetupConnectEvent.referToServer(host, port)</code> || Redirect during handshake before full connection
|-
| '''Disconnect Fallback''' || Coming soon || Auto-reconnect to fallback if server crashes
|}


=== Player Referral (Server Transfers) ===
'''Security:''' Referral payloads pass through the client and can be tampered with. Sign payloads cryptographically (e.g., HMAC with a shared secret) so receiving servers can verify authenticity.


Transfer connected players from one server to another seamlessly.
'''Custom Proxies:''' Build proxy servers using Netty QUIC. Packet definitions available in <code>HytaleServer.jar</code> at <code>com.hypixel.hytale.protocol.packets</code>.


'''How it works:'''
== Command-Line Arguments ==
# Player is on Server A
# Server A sends a referral packet with target server info
# Client disconnects from Server A
# Client automatically connects to Server B
# Optional: Server A can send a 4KB payload to Server B


'''Configuration example:'''
<pre>
<pre>
{
java [JVM options] -jar HytaleServer.jar [server options]
  "Referrals": {
    "Enabled": true,
    "Targets": {
      "minigames": {
        "Host": "minigames.myserver.com",
        "Port": 5520
      },
      "survival": {
        "Host": "survival.myserver.com",
        "Port": 5521
      }
    }
  }
}
</pre>
</pre>


'''Security Note:''' Referral payloads pass through the client and can be tampered with. Use cryptographic signing (HMAC with shared secret) to verify payload authenticity on the receiving server.
=== JVM Options ===


=== Connection Redirect (Load Balancing) ===
{| class="wikitable"
 
|-
Redirect players during connection handshake before they fully join.
! Option !! Description !! Example
|-
| <code>-Xms</code> || Initial memory allocation || <code>-Xms4G</code>
|-
| <code>-Xmx</code> || Maximum memory allocation || <code>-Xmx4G</code>
|-
| <code>-XX:+UseG1GC</code> || Use G1 garbage collector || Recommended for 8GB+
|-
| <code>-XX:AOTCache</code> || Use AOT cache for faster startup || <code>-XX:AOTCache=HytaleServer.aot</code>
|}


'''Use cases:'''
=== Server Options ===
* Load balancing across multiple servers
* Regional routing based on player location
* Enforcing lobby-first connections
* Maintenance mode redirects
 
'''How it works:'''
# Player connects to Server A
# During handshake, Server A checks conditions
# If needed, Server A rejects with redirect address
# Client automatically connects to the redirect target
 
=== Disconnect Fallback ===
 
Automatically reconnect players to a fallback server if their current server crashes.
 
'''Use cases:'''
* Return players to lobby after game server crash
* Maintain player engagement during restarts
* Graceful handling of server issues
 
'''Configuration:'''
<pre>
{
  "Fallback": {
    "Enabled": true,
    "Server": {
      "Host": "lobby.myserver.com",
      "Port": 5520
    }
  }
}
</pre>
 
=== Building a Custom Proxy ===
 
For advanced networks, you can build custom proxy servers using Netty QUIC.
 
'''Key information:'''
* Hytale uses '''QUIC protocol exclusively''' for client-server communication
* Packet definitions are available in <code>HytaleServer.jar</code> at <code>com.hypixel.hytale.protocol.packets</code>
* Use these to decode, inspect, modify, or forward traffic
 
'''Note:''' Building proxies requires Java development experience and understanding of the QUIC protocol.
 
== Command-Line Arguments ==
 
Advanced launch options for fine-tuning your server:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Argument !! Description
! Option !! Description !! Default
|-
|-
| <code>--assets <path></code> || Path to Assets.zip (required)
| <code>--assets <path></code> || Path to Assets.zip (required) || None
|-
|-
| <code>--bind <ip:port></code> || Address and port to listen on (default: 0.0.0.0:5520)
| <code>--bind <ip:port></code> || Address and port to listen on || 0.0.0.0:5520
|-
|-
| <code>--auth-mode <mode></code> || Authentication mode: <code>authenticated</code> or <code>offline</code>
| <code>--auth-mode <mode></code> || <code>authenticated</code> or <code>offline</code> || authenticated
|-
|-
| <code>--backup</code> || Enable automatic backups
| <code>--backup</code> || Enable automatic backups || Disabled
|-
|-
| <code>--backup-dir <path></code> || Where to store backups
| <code>--backup-dir <path></code> || Backup storage location || ./backups
|-
|-
| <code>--backup-frequency <mins></code> || Backup interval in minutes
| <code>--backup-frequency <mins></code> || Backup interval in minutes || 60
|-
|-
| <code>--disable-sentry</code> || Disable crash reporting (for development)
| <code>--disable-sentry</code> || Disable crash reporting || Enabled
|-
|-
| <code>--allow-op</code> || Allow operator commands
| <code>--allow-op</code> || Allow operator commands || Disabled
|-
|-
| <code>--accept-early-plugins</code> || Load experimental plugins (unsupported)
| <code>--accept-early-plugins</code> || Load experimental plugins (unsupported) || Disabled
|}
|}


=== Example Launch Commands ===
=== Example Launch Scripts ===


'''Production server with backups:'''
'''Production server (Windows - start.bat):'''
<pre>
<pre>
java -Xms6G -Xmx6G -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60 --backup-dir ./backups
@echo off
java -Xms6G -Xmx6G -XX:+UseG1GC -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60
pause
</pre>
</pre>


'''Development server (offline mode, no crash reporting):'''
'''Production server (Linux - start.sh):'''
<pre>
<pre>
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --auth-mode offline --disable-sentry
#!/bin/bash
java -Xms6G -Xmx6G -XX:+UseG1GC -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60
</pre>
</pre>


'''Custom port binding:'''
'''Development server:'''
<pre>
<pre>
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --bind 0.0.0.0:25565
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --auth-mode offline --disable-sentry
</pre>
</pre>


== Performance Optimization ==
== Firewall Configuration ==
 
=== JVM Tuning ===
 
Beyond basic <code>-Xms</code> and <code>-Xmx</code> flags, consider these optimizations:


'''Using the AOT Cache (Faster Startup):'''
Hytale uses QUIC protocol over UDP (not TCP).


Hytale includes a pre-trained AOT (Ahead-of-Time) cache that speeds up server boot time:
'''Windows PowerShell:'''
<pre>
<pre>
java -XX:AOTCache=HytaleServer.aot -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip
New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow
</pre>
</pre>


'''Garbage Collection Tuning:'''
'''Linux (iptables):'''
 
For servers with 8GB+ RAM, consider G1GC tuning:
<pre>
<pre>
java -Xms8G -Xmx8G -XX:+UseG1GC -XX:MaxGCPauseMillis=50 -jar HytaleServer.jar --assets Assets.zip
sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT
</pre>
</pre>


=== Resource Usage Guidelines ===
'''Linux (ufw):'''
 
{| class="wikitable"
|-
! Resource !! What Increases Usage !! How to Reduce
|-
| '''CPU''' || High player count, many entities (NPCs, mobs) || Reduce mob spawning, limit entity counts
|-
| '''RAM''' || Large view distance, players spread out || Lower view distance, enable chunk unloading
|-
| '''Storage''' || Large worlds, frequent backups || Pre-generation limits, backup rotation
|-
| '''Network''' || High player count, high tick rate || Optimize player cap, use compression
|}
 
== Permissions Configuration ==
 
The <code>permissions.json</code> file controls who can do what on your server.
 
=== Basic Structure ===
 
<pre>
<pre>
{
sudo ufw allow 5520/udp
  "Groups": {
    "default": {
      "Permissions": ["hytale.chat", "hytale.build"],
      "Inheritance": []
    },
    "moderator": {
      "Permissions": ["hytale.kick", "hytale.mute"],
      "Inheritance": ["default"]
    },
    "admin": {
      "Permissions": ["*"],
      "Inheritance": ["moderator"]
    }
  },
  "Players": {
    "player-uuid-here": {
      "Group": "admin"
    }
  }
}
</pre>
</pre>
=== Permission Tips ===
* Use <code>*</code> for all permissions (admin only)
* Inheritance lets groups build on each other
* Player-specific permissions override group permissions
* Changes require server restart to take effect
== Troubleshooting Advanced Configurations ==
=== Config Changes Not Applying ===
* Make sure server is '''stopped''' before editing
* Check for JSON syntax errors (missing commas, brackets)
* Verify file encoding is UTF-8
* Check server logs for config parsing errors
=== Multi-Server Connection Issues ===
* Ensure all servers are on the '''same Hytale version'''
* Verify firewall rules allow traffic between servers
* Check that referral hostnames resolve correctly
* Test with direct IP addresses first
=== Performance Problems ===
* Monitor RAM usage - increase <code>-Xmx</code> if consistently high
* Check view distance settings
* Review entity counts in logs
* Consider pre-generating heavily explored areas


== See Also ==
== See Also ==

Latest revision as of 20:52, 13 January 2026

This guide covers advanced Hytale server configuration including world settings, command-line arguments, and server mesh architecture.

Important: Always back up your server files before making configuration changes. Stop your server before editing any configuration files.

Configuration File Locations

File Location Purpose
config.json Server root folder Main server settings
permissions.json Server root folder Player roles and permissions
bans.json Server root folder Banned player list
whitelist.json Server root folder Allowed players list
config.json universe/worlds/[WorldName]/ Per-world settings

Server Configuration (config.json)

The main config.json in your server root controls server-wide settings: 

{
  "Version": 3,
  "ServerName": "Hytale Server",
  "MOTD": "",
  "Password": "",
  "MaxPlayers": 100,
  "MaxViewRadius": 32,
  "LocalCompressionEnabled": false,
  "Defaults": {
    "World": "default",
    "GameMode": "Adventure"
  },
  "ConnectionTimeouts": {
    "JoinTimeouts": {}
  },
  "RateLimit": {},
  "Modules": {},
  "LogLevels": {},
  "Mods": {},
  "DisplayTmpTagsInStrings": false,
  "PlayerStorage": {
    "Type": "Hytale"
  }
}
Setting Description Recommended
ServerName Display name shown to players Your server name
MOTD Message of the day Short welcome message
Password Server password (empty = no password) Leave empty for public
MaxPlayers Maximum concurrent players Based on RAM (20-50 typical)
MaxViewRadius How far players can see (in chunks) 12 for performance
LocalCompressionEnabled Enable local network compression false
Defaults.World Default world name players spawn in "default"
Defaults.GameMode Default game mode for new players "Adventure" or "Creative"

Performance Tip: The official Hytale manual recommends limiting MaxViewRadius to 12 chunks (384 blocks) for both performance and gameplay. The default of 32 is equivalent to roughly 64 Minecraft chunks and will significantly increase RAM usage.

Editing Configuration Files

For Survival Servers Customers

  1. Log into your control panel
  2. Click Stop to shut down your server
  3. Click Configuration Files or use FTP Access
  4. Edit the desired file and save
  5. Click Start to restart your server

For Self-Hosted Servers

  1. Stop your server (type stop or press Ctrl+C)
  2. Open the config file in a text editor
  3. Make your changes and save
  4. Start your server

World Configuration (universe/worlds/[WorldName]/config.json)

Each world has its own configuration file. Below is the documented world config structure: 

{
  "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",
  "ClientEffects": {
    "SunHeightPercent": 100.0,
    "SunAngleDegrees": 0.0,
    "BloomIntensity": 0.30000001192092896,
    "BloomPower": 8.0,
    "SunIntensity": 0.25,
    "SunshaftIntensity": 0.30000001192092896,
    "SunshaftScaleFactor": 4.0
  },
  "RequiredPlugins": {},
  "IsSpawningNPC": true,
  "IsSpawnMarkersEnabled": true,
  "IsAllNPCFrozen": false,
  "GameplayConfig": "Default",
  "IsCompassUpdating": true,
  "IsSavingPlayers": true,
  "IsSavingChunks": true,
  "SaveNewChunks": true,
  "IsUnloadingChunks": true,
  "IsObjectiveMarkersEnabled": true,
  "DeleteOnUniverseStart": false,
  "DeleteOnRemove": false,
  "ResourceStorage": {
    "Type": "Hytale"
  },
  "Plugin": {}
}
Setting Description
Seed World generation seed
IsPvpEnabled Allow player vs player combat
IsFallDamageEnabled Players take fall damage
IsGameTimePaused Freeze day/night cycle
IsSpawningNPC Enable mob spawning
IsAllNPCFrozen Freeze all NPCs in place
IsTicking World simulation runs
IsBlockTicking Block updates (crops, liquids)
IsSavingPlayers Save player data
IsSavingChunks Save world changes
SaveNewChunks Save newly generated chunks to disk
IsUnloadingChunks Unload empty chunks
ClientEffects Visual effects settings (sun, bloom, sunshafts)
DeleteOnUniverseStart Delete world on server start
DeleteOnRemove Delete world files when removed

World Pre-Generation

Pre-generating creates terrain ahead of time, reducing lag when players explore.

Method 1: In-Game Exploration

  1. Start your server and log in as admin
  2. Fly around the map to generate chunks
  3. The server saves chunks as you explore

Method 2: Pre-Generation Mods

  1. Add a pre-gen mod to your mods/ folder
  2. Configure the area size and center point
  3. Run the pre-generation command

Method 3: Command-Line 

java -jar HytaleServer.jar --help

Check for built-in pre-generation options.

Server Mesh Architecture (Multi-Server Networks)

Hytale has built-in support for connecting multiple servers together without third-party proxies like BungeeCord.

These features are implemented via the server's Java API:

Feature API Method Description
Player Referral PlayerRef.referToServer(host, port, payload) Transfer players between servers with optional 4KB payload
Connection Redirect PlayerSetupConnectEvent.referToServer(host, port) Redirect during handshake before full connection
Disconnect Fallback Coming soon Auto-reconnect to fallback if server crashes

Security: Referral payloads pass through the client and can be tampered with. Sign payloads cryptographically (e.g., HMAC with a shared secret) so receiving servers can verify authenticity.

Custom Proxies: Build proxy servers using Netty QUIC. Packet definitions available in HytaleServer.jar at com.hypixel.hytale.protocol.packets.

Command-Line Arguments

java [JVM options] -jar HytaleServer.jar [server options]

JVM Options

Option Description Example
-Xms Initial memory allocation -Xms4G
-Xmx Maximum memory allocation -Xmx4G
-XX:+UseG1GC Use G1 garbage collector Recommended for 8GB+
-XX:AOTCache Use AOT cache for faster startup -XX:AOTCache=HytaleServer.aot

Server Options

Option Description Default
--assets <path> Path to Assets.zip (required) None
--bind <ip:port> Address and port to listen on 0.0.0.0:5520
--auth-mode <mode> authenticated or offline authenticated
--backup Enable automatic backups Disabled
--backup-dir <path> Backup storage location ./backups
--backup-frequency <mins> Backup interval in minutes 60
--disable-sentry Disable crash reporting Enabled
--allow-op Allow operator commands Disabled
--accept-early-plugins Load experimental plugins (unsupported) Disabled

Example Launch Scripts

Production server (Windows - start.bat): 

@echo off
java -Xms6G -Xmx6G -XX:+UseG1GC -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60
pause

Production server (Linux - start.sh): 

#!/bin/bash
java -Xms6G -Xmx6G -XX:+UseG1GC -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60

Development server: 

java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --auth-mode offline --disable-sentry

Firewall Configuration

Hytale uses QUIC protocol over UDP (not TCP).

Windows PowerShell: 

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

See Also


Retrieved from "https://www.survivalservers.com/wiki/index.php?title=Hytale_Advanced_Server_Configuration&oldid=3277"