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
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 complete configuration file references, world pre-generation, 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) ==
== Editing Configuration Files ==
 
The main <code>config.json</code> file controls your server's core settings.


=== For Survival Servers Customers ===
=== For Survival Servers Customers ===


# Log into your [https://www.survivalservers.com/sspanel/ control panel]
# Log into your [https://www.survivalservers.com/sspanel/ control panel]
# Click '''Configuration Files''' or '''Config Editor'''
# Click '''Stop''' to shut down your server
# Select <code>config.json</code>
# Click '''Configuration Files''' or use '''FTP Access'''
# Make your changes and click '''Save'''
# Edit the desired file and save
# Restart your server
# Click '''Start''' to restart your server


=== For Self-Hosted Servers ===
=== For Self-Hosted Servers ===


# Stop your server
# Stop your server (type <code>stop</code> or press <code>Ctrl+C</code>)
# Open <code>config.json</code> in a text editor
# Open the config file in a text editor
# Make your changes and save
# Make your changes and save
# Start your server
# Start your server


=== Common Server Settings ===
== Main Server Configuration (config.json) ==


<pre>
<pre>
{
{
   "ServerName": "My Hytale Server",
   "ServerName": "My Hytale Server",
  "MOTD": "Welcome to my server!",
   "MaxPlayers": 20,
   "MaxPlayers": 20,
  "MOTD": "Welcome to my server!",
   "ViewDistance": 12,
   "ViewDistance": 12,
   "SimulationDistance": 10,
   "SimulationDistance": 10,
   "WhitelistEnabled": false,
   "WhitelistEnabled": false,
   "Difficulty": "Normal"
   "Difficulty": "Normal",
  "DefaultGameMode": "Survival",
  "AllowFlight": false,
  "SpawnProtection": 16,
  "EnableCommandBlock": false,
  "MaxWorldSize": 29999984,
  "NetworkCompressionThreshold": 256,
  "PlayerIdleTimeout": 0,
  "PreventProxyConnections": false,
  "EnableQuery": false,
  "QueryPort": 5521,
  "RCON": {
    "Enabled": false,
    "Port": 5522,
    "Password": ""
  },
  "Backups": {
    "Enabled": true,
    "FrequencyMinutes": 60,
    "MaxBackups": 24,
    "Directory": "./backups"
  }
}
}
</pre>
</pre>
Line 64: Line 74:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Setting !! Description !! Recommended Value
! Setting !! Description
|-
|-
| <code>ServerName</code> || Name shown to players || Your server name
| <code>ServerName</code> || Name displayed to players
|-
|-
| <code>MaxPlayers</code> || Maximum concurrent players || Based on your RAM (10-20 for 4GB, 20-40 for 8GB)
| <code>MOTD</code> || Message of the day shown on connection
|-
|-
| <code>ViewDistance</code> || How far players can see (in chunks) || 12 (default is higher but uses more RAM)
| <code>MaxPlayers</code> || Maximum concurrent players
|-
|-
| <code>SimulationDistance</code> || How far entities are active || 8-10 for better performance
| <code>ViewDistance</code> || How far players can see (chunks)
|-
|-
| <code>WhitelistEnabled</code> || Restrict to approved players only || false (public) or true (private)
| <code>SimulationDistance</code> || How far entities are active
|-
| <code>WhitelistEnabled</code> || Restrict to approved players
|-
| <code>Difficulty</code> || Peaceful, Easy, Normal, Hard
|-
| <code>DefaultGameMode</code> || Survival, Creative, Adventure
|-
| <code>SpawnProtection</code> || Protected radius around spawn (blocks)
|-
| <code>PlayerIdleTimeout</code> || Kick idle players after X minutes (0 = disabled)
|-
| <code>NetworkCompressionThreshold</code> || Packet compression threshold
|}
|}


'''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.
== World Configuration (universe/worlds/[WorldName]/config.json) ==
 
== World Configuration ==
 
Each world has its own configuration file located at <code>universe/worlds/[WorldName]/config.json</code>.
 
=== World Config Options ===


<pre>
<pre>
{
{
   "Version": 4,
   "Version": 4,
  "UUID": {
    "$binary": "j2x/idwTQpen24CDfH1+OQ==",
    "$type": "04"
  },
   "Seed": 1767292261384,
   "Seed": 1767292261384,
   "WorldGen": {
   "WorldGen": {
Line 93: Line 113:
     "Name": "Default"
     "Name": "Default"
   },
   },
  "WorldMap": {
    "Type": "WorldGen"
  },
  "ChunkStorage": {
    "Type": "Hytale"
  },
  "ChunkConfig": {},
   "IsTicking": true,
   "IsTicking": true,
   "IsBlockTicking": true,
   "IsBlockTicking": true,
Line 98: Line 125:
   "IsFallDamageEnabled": true,
   "IsFallDamageEnabled": true,
   "IsGameTimePaused": false,
   "IsGameTimePaused": false,
  "GameTime": "0001-01-01T08:26:59.761606129Z",
  "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
   "IsUnloadingChunks": true,
  "IsObjectiveMarkersEnabled": true,
  "DeleteOnUniverseStart": false,
  "DeleteOnRemove": false,
  "ResourceStorage": {
    "Type": "Hytale"
  },
  "Plugin": {}
}
}
</pre>
</pre>
Line 110: Line 147:
{| 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>IsUnloadingChunks</code> || Unload empty chunks
|-
| <code>DeleteOnUniverseStart</code> || Delete world on server start
|-
| <code>DeleteOnRemove</code> || Delete world files when removed
|}
|}


== World Pre-Generation ==
== Permissions Configuration (permissions.json) ==


Pre-generating your world creates terrain ahead of time, reducing lag when players explore new areas.
<pre>
{
  "Groups": {
    "default": {
      "DisplayName": "Player",
      "Prefix": "",
      "Permissions": [
        "hytale.chat",
        "hytale.build",
        "hytale.break",
        "hytale.interact",
        "hytale.command.help",
        "hytale.command.spawn",
        "hytale.command.home"
      ],
      "Inheritance": []
    },
    "vip": {
      "DisplayName": "VIP",
      "Prefix": "[VIP] ",
      "Permissions": [
        "hytale.command.fly",
        "hytale.command.nick",
        "hytale.bypass.afk"
      ],
      "Inheritance": ["default"]
    },
    "moderator": {
      "DisplayName": "Moderator",
      "Prefix": "[MOD] ",
      "Permissions": [
        "hytale.command.kick",
        "hytale.command.mute",
        "hytale.command.warn",
        "hytale.command.tp",
        "hytale.command.tphere",
        "hytale.command.vanish",
        "hytale.bypass.spam"
      ],
      "Inheritance": ["vip"]
    },
    "admin": {
      "DisplayName": "Admin",
      "Prefix": "[ADMIN] ",
      "Permissions": [
        "hytale.command.ban",
        "hytale.command.unban",
        "hytale.command.give",
        "hytale.command.gamemode",
        "hytale.command.time",
        "hytale.command.weather",
        "hytale.command.whitelist"
      ],
      "Inheritance": ["moderator"]
    },
    "owner": {
      "DisplayName": "Owner",
      "Prefix": "[OWNER] ",
      "Permissions": [
        "*"
      ],
      "Inheritance": []
    }
  },
  "Players": {
    "your-uuid-here": {
      "Group": "owner",
      "AdditionalPermissions": []
    },
    "friend-uuid-here": {
      "Group": "admin",
      "AdditionalPermissions": [
        "hytale.command.stop"
      ]
    }
  }
}
</pre>


=== Why Pre-Generate? ===
* <code>*</code> grants all permissions
* <code>Inheritance</code> lets groups build on each other
* <code>AdditionalPermissions</code> adds extra permissions to specific players beyond their group
* Changes require a server restart


* '''Reduces lag spikes''' - New chunks are already generated
== World Pre-Generation ==
* '''Smoother gameplay''' - No stuttering when exploring
* '''Better for events''' - Prepare large areas in advance
* '''Consistent performance''' - Server load is predictable


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


'''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) ==


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.
 
=== Use Cases for Server Meshes ===
 
* '''Hub/Lobby servers''' - Central spawn with portals to game servers
* '''Minigame networks''' - Different servers for different game modes
* '''Load distribution''' - Spread players across multiple servers
* '''Regional routing''' - Direct players to nearest server
 
=== Player Referral (Server Transfers) ===
 
Transfer connected players from one server to another seamlessly.
 
'''How it works:'''
# 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>
{
{
  "Network": {
    "Mode": "mesh",
    "ServerId": "lobby-1",
    "SharedSecret": "your-secure-secret-key-here"
  },
   "Referrals": {
   "Referrals": {
     "Enabled": true,
     "Enabled": true,
     "Targets": {
     "Targets": {
      "minigames": {
        "Host": "minigames.myserver.com",
        "Port": 5520
      },
       "survival": {
       "survival": {
         "Host": "survival.myserver.com",
         "Host": "survival.myserver.com",
         "Port": 5521
         "Port": 5520,
        "DisplayName": "Survival World"
      },
      "creative": {
        "Host": "creative.myserver.com",
        "Port": 5520,
        "DisplayName": "Creative World"
      },
      "minigames": {
        "Host": "games.myserver.com",
        "Port": 5520,
        "DisplayName": "Minigames"
       }
       }
     }
     }
   }
   },
}
  "Redirect": {
</pre>
    "Enabled": true,
 
    "DefaultTarget": "lobby",
'''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.
    "Rules": [
 
      {
=== Connection Redirect (Load Balancing) ===
        "Condition": "ServerFull",
 
        "Target": "lobby-2"
Redirect players during connection handshake before they fully join.
      },
 
      {
'''Use cases:'''
        "Condition": "Maintenance",
* Load balancing across multiple servers
        "Target": "maintenance"
* 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": {
   "Fallback": {
     "Enabled": true,
     "Enabled": true,
Line 250: Line 337:
</pre>
</pre>


=== Building a Custom Proxy ===
{| class="wikitable"
|-
! Feature !! Description
|-
| '''Player Referral''' || Transfer players between servers seamlessly
|-
| '''Connection Redirect''' || Redirect during handshake before full connection
|-
| '''Disconnect Fallback''' || Auto-reconnect to fallback if server crashes
|}


For advanced networks, you can build custom proxy servers using Netty QUIC.
'''Security:''' Referral payloads pass through the client. Use <code>SharedSecret</code> to cryptographically sign payloads so receiving servers can verify authenticity.


'''Key information:'''
'''Custom Proxies:''' Build proxy servers using Netty QUIC. Packet definitions available in <code>HytaleServer.jar</code> at <code>com.hypixel.hytale.protocol.packets</code>.
* 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 ==


== Command-Line Arguments ==
<pre>
java [JVM options] -jar HytaleServer.jar [server options]
</pre>


Advanced launch options for fine-tuning your server:
=== JVM Options ===


{| class="wikitable"
{| class="wikitable"
|-
|-
! Argument !! Description
! Option !! Description !! Example
|-
|-
| <code>--assets <path></code> || Path to Assets.zip (required)
| <code>-Xms</code> || Initial memory allocation || <code>-Xms4G</code>
|-
|-
| <code>--bind <ip:port></code> || Address and port to listen on (default: 0.0.0.0:5520)
| <code>-Xmx</code> || Maximum memory allocation || <code>-Xmx4G</code>
|-
|-
| <code>--auth-mode <mode></code> || Authentication mode: <code>authenticated</code> or <code>offline</code>
| <code>-XX:+UseG1GC</code> || Use G1 garbage collector || Recommended for 8GB+
|-
|-
| <code>--backup</code> || Enable automatic backups
| <code>-XX:AOTCache</code> || Use AOT cache for faster startup || <code>-XX:AOTCache=HytaleServer.aot</code>
|}
 
=== Server Options ===
 
{| class="wikitable"
|-
|-
| <code>--backup-dir <path></code> || Where to store backups
! Option !! Description !! Default
|-
|-
| <code>--backup-frequency <mins></code> || Backup interval in minutes
| <code>--assets <path></code> || Path to Assets.zip (required) || None
|-
|-
| <code>--disable-sentry</code> || Disable crash reporting (for development)
| <code>--bind <ip:port></code> || Address and port to listen on || 0.0.0.0:5520
|-
|-
| <code>--allow-op</code> || Allow operator commands
| <code>--auth-mode <mode></code> || <code>authenticated</code> or <code>offline</code> || authenticated
|-
|-
| <code>--accept-early-plugins</code> || Load experimental plugins (unsupported)
| <code>--backup</code> || Enable automatic backups || Disabled
|}
 
=== Example Launch Commands ===
 
'''Production server with backups:'''
<pre>
java -Xms6G -Xmx6G -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60 --backup-dir ./backups
</pre>
 
'''Development server (offline mode, no crash reporting):'''
<pre>
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --auth-mode offline --disable-sentry
</pre>
 
'''Custom port binding:'''
<pre>
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --bind 0.0.0.0:25565
</pre>
 
== Performance Optimization ==
 
=== JVM Tuning ===
 
Beyond basic <code>-Xms</code> and <code>-Xmx</code> flags, consider these optimizations:
 
'''Using the AOT Cache (Faster Startup):'''
 
Hytale includes a pre-trained AOT (Ahead-of-Time) cache that speeds up server boot time:
<pre>
java -XX:AOTCache=HytaleServer.aot -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip
</pre>
 
'''Garbage Collection Tuning:'''
 
For servers with 8GB+ RAM, consider G1GC tuning:
<pre>
java -Xms8G -Xmx8G -XX:+UseG1GC -XX:MaxGCPauseMillis=50 -jar HytaleServer.jar --assets Assets.zip
</pre>
 
=== Resource Usage Guidelines ===
 
{| class="wikitable"
|-
|-
! Resource !! What Increases Usage !! How to Reduce
| <code>--backup-dir <path></code> || Backup storage location || ./backups
|-
|-
| '''CPU''' || High player count, many entities (NPCs, mobs) || Reduce mob spawning, limit entity counts
| <code>--backup-frequency <mins></code> || Backup interval || 60
|-
|-
| '''RAM''' || Large view distance, players spread out || Lower view distance, enable chunk unloading
| <code>--disable-sentry</code> || Disable crash reporting || Enabled
|-
|-
| '''Storage''' || Large worlds, frequent backups || Pre-generation limits, backup rotation
| <code>--allow-op</code> || Allow operator commands || Disabled
|-
|-
| '''Network''' || High player count, high tick rate || Optimize player cap, use compression
| <code>--accept-early-plugins</code> || Load experimental plugins || Disabled
|}
|}


== Permissions Configuration ==
=== Example Launch Scripts ===


The <code>permissions.json</code> file controls who can do what on your server.
'''Production server (Windows - start.bat):'''
<pre>
@echo off
java -Xms6G -Xmx6G -XX:+UseG1GC -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60
pause
</pre>


=== Basic Structure ===
'''Production server (Linux - start.sh):'''
<pre>
#!/bin/bash
java -Xms6G -Xmx6G -XX:+UseG1GC -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60
</pre>


'''Development server:'''
<pre>
<pre>
{
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --auth-mode offline --disable-sentry
  "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 ==

Revision as of 11:02, 12 January 2026

This guide covers advanced Hytale server configuration including complete configuration file references, world pre-generation, 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

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

Main Server Configuration (config.json)

{
  "ServerName": "My Hytale Server",
  "MOTD": "Welcome to my server!",
  "MaxPlayers": 20,
  "ViewDistance": 12,
  "SimulationDistance": 10,
  "WhitelistEnabled": false,
  "Difficulty": "Normal",
  "DefaultGameMode": "Survival",
  "AllowFlight": false,
  "SpawnProtection": 16,
  "EnableCommandBlock": false,
  "MaxWorldSize": 29999984,
  "NetworkCompressionThreshold": 256,
  "PlayerIdleTimeout": 0,
  "PreventProxyConnections": false,
  "EnableQuery": false,
  "QueryPort": 5521,
  "RCON": {
    "Enabled": false,
    "Port": 5522,
    "Password": ""
  },
  "Backups": {
    "Enabled": true,
    "FrequencyMinutes": 60,
    "MaxBackups": 24,
    "Directory": "./backups"
  }
}
Setting Description
ServerName Name displayed to players
MOTD Message of the day shown on connection
MaxPlayers Maximum concurrent players
ViewDistance How far players can see (chunks)
SimulationDistance How far entities are active
WhitelistEnabled Restrict to approved players
Difficulty Peaceful, Easy, Normal, Hard
DefaultGameMode Survival, Creative, Adventure
SpawnProtection Protected radius around spawn (blocks)
PlayerIdleTimeout Kick idle players after X minutes (0 = disabled)
NetworkCompressionThreshold Packet compression threshold

World Configuration (universe/worlds/[WorldName]/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": {}
}
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
IsUnloadingChunks Unload empty chunks
DeleteOnUniverseStart Delete world on server start
DeleteOnRemove Delete world files when removed

Permissions Configuration (permissions.json)

{
  "Groups": {
    "default": {
      "DisplayName": "Player",
      "Prefix": "",
      "Permissions": [
        "hytale.chat",
        "hytale.build",
        "hytale.break",
        "hytale.interact",
        "hytale.command.help",
        "hytale.command.spawn",
        "hytale.command.home"
      ],
      "Inheritance": []
    },
    "vip": {
      "DisplayName": "VIP",
      "Prefix": "[VIP] ",
      "Permissions": [
        "hytale.command.fly",
        "hytale.command.nick",
        "hytale.bypass.afk"
      ],
      "Inheritance": ["default"]
    },
    "moderator": {
      "DisplayName": "Moderator",
      "Prefix": "[MOD] ",
      "Permissions": [
        "hytale.command.kick",
        "hytale.command.mute",
        "hytale.command.warn",
        "hytale.command.tp",
        "hytale.command.tphere",
        "hytale.command.vanish",
        "hytale.bypass.spam"
      ],
      "Inheritance": ["vip"]
    },
    "admin": {
      "DisplayName": "Admin",
      "Prefix": "[ADMIN] ",
      "Permissions": [
        "hytale.command.ban",
        "hytale.command.unban",
        "hytale.command.give",
        "hytale.command.gamemode",
        "hytale.command.time",
        "hytale.command.weather",
        "hytale.command.whitelist"
      ],
      "Inheritance": ["moderator"]
    },
    "owner": {
      "DisplayName": "Owner",
      "Prefix": "[OWNER] ",
      "Permissions": [
        "*"
      ],
      "Inheritance": []
    }
  },
  "Players": {
    "your-uuid-here": {
      "Group": "owner",
      "AdditionalPermissions": []
    },
    "friend-uuid-here": {
      "Group": "admin",
      "AdditionalPermissions": [
        "hytale.command.stop"
      ]
    }
  }
}
  • * grants all permissions
  • Inheritance lets groups build on each other
  • AdditionalPermissions adds extra permissions to specific players beyond their group
  • Changes require a server restart

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. 

{
  "Network": {
    "Mode": "mesh",
    "ServerId": "lobby-1",
    "SharedSecret": "your-secure-secret-key-here"
  },
  "Referrals": {
    "Enabled": true,
    "Targets": {
      "survival": {
        "Host": "survival.myserver.com",
        "Port": 5520,
        "DisplayName": "Survival World"
      },
      "creative": {
        "Host": "creative.myserver.com",
        "Port": 5520,
        "DisplayName": "Creative World"
      },
      "minigames": {
        "Host": "games.myserver.com",
        "Port": 5520,
        "DisplayName": "Minigames"
      }
    }
  },
  "Redirect": {
    "Enabled": true,
    "DefaultTarget": "lobby",
    "Rules": [
      {
        "Condition": "ServerFull",
        "Target": "lobby-2"
      },
      {
        "Condition": "Maintenance",
        "Target": "maintenance"
      }
    ]
  },
  "Fallback": {
    "Enabled": true,
    "Server": {
      "Host": "lobby.myserver.com",
      "Port": 5520
    }
  }
}
Feature Description
Player Referral Transfer players between servers seamlessly
Connection Redirect Redirect during handshake before full connection
Disconnect Fallback Auto-reconnect to fallback if server crashes

Security: Referral payloads pass through the client. Use SharedSecret to cryptographically sign payloads 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 60
--disable-sentry Disable crash reporting Enabled
--allow-op Allow operator commands Disabled
--accept-early-plugins Load experimental plugins 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

See Also


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