Hytale Advanced Server Configuration: Difference between revisions

From Survival Servers
Jump to navigation Jump to search
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
This guide covers advanced Hytale server configuration including complete configuration file references, world pre-generation, and server mesh architecture.
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.
'''Important:''' Always back up your server files before making configuration changes. Stop your server before editing any configuration files.
Line 20: Line 20:
|}
|}


== Editing Configuration Files ==
== Server Configuration (config.json) ==
 
=== For Survival Servers Customers ===
 
# Log into your [https://www.survivalservers.com/sspanel/ control panel]
# Click '''Stop''' to shut down your server
# Click '''Server Config''' button (easy editor) or use '''File Manager'''
# Edit the desired file and save
# Click '''Start''' to restart your server
 
=== For Self-Hosted Servers ===


# Stop your server (type <code>stop</code> or press <code>Ctrl+C</code>)
The main <code>config.json</code> in your server root controls server-wide settings:
# Open the config file in a text editor
# Make your changes and save
# Start your server
 
== Main Server Configuration (config.json) ==


<pre>
<pre>
{
{
   "ServerName": "My Hytale Server",
   "Version": 3,
   "MOTD": "Welcome to my server!",
   "ServerName": "Hytale Server",
   "MaxPlayers": 20,
   "MOTD": "",
  "ViewDistance": 12,
   "Password": "",
   "SimulationDistance": 10,
   "MaxPlayers": 100,
  "WhitelistEnabled": false,
   "MaxViewRadius": 32,
   "Difficulty": "Normal",
   "LocalCompressionEnabled": false,
   "DefaultGameMode": "Survival",
   "Defaults": {
   "AllowFlight": false,
    "World": "default",
   "SpawnProtection": 16,
    "GameMode": "Adventure"
  "EnableCommandBlock": false,
   },
  "MaxWorldSize": 29999984,
   "ConnectionTimeouts": {
  "NetworkCompressionThreshold": 256,
     "JoinTimeouts": {}
  "PlayerIdleTimeout": 0,
  "PreventProxyConnections": false,
   "EnableQuery": false,
  "QueryPort": 5521,
   "RCON": {
     "Enabled": false,
    "Port": 5522,
    "Password": ""
   },
   },
   "Backups": {
   "RateLimit": {},
    "Enabled": true,
  "Modules": {},
    "FrequencyMinutes": 60,
  "LogLevels": {},
    "MaxBackups": 24,
  "Mods": {},
     "Directory": "./backups"
  "DisplayTmpTagsInStrings": false,
  "PlayerStorage": {
     "Type": "Hytale"
   }
   }
}
}
Line 74: Line 53:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Setting !! Description
! Setting !! Description !! Recommended
|-
|-
| <code>ServerName</code> || Name displayed to players
| <code>ServerName</code> || Display name shown to players || Your server name
|-
|-
| <code>MOTD</code> || Message of the day shown on connection
| <code>MOTD</code> || Message of the day || Short welcome message
|-
|-
| <code>MaxPlayers</code> || Maximum concurrent players
| <code>Password</code> || Server password (empty = no password) || Leave empty for public
|-
|-
| <code>ViewDistance</code> || How far players can see (chunks)
| <code>MaxPlayers</code> || Maximum concurrent players || Based on RAM (20-50 typical)
|-
|-
| <code>SimulationDistance</code> || How far entities are active
| <code>MaxViewRadius</code> || How far players can see (in chunks) || '''12''' for performance
|-
|-
| <code>WhitelistEnabled</code> || Restrict to approved players
| <code>LocalCompressionEnabled</code> || Enable local network compression || false
|-
|-
| <code>Difficulty</code> || Peaceful, Easy, Normal, Hard
| <code>Defaults.World</code> || Default world name players spawn in || "default"
|-
|-
| <code>DefaultGameMode</code> || Survival, Creative, Adventure
| <code>Defaults.GameMode</code> || Default game mode for new players || "Adventure" or "Creative"
|-
| <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:''' 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
=== For Self-Hosted Servers ===
# 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 Configuration (universe/worlds/[WorldName]/config.json) ==
== World Configuration (universe/worlds/[WorldName]/config.json) ==
Each world has its own configuration file. Below is the documented world config structure:


<pre>
<pre>
Line 126: Line 120:
   "IsGameTimePaused": false,
   "IsGameTimePaused": false,
   "GameTime": "0001-01-01T08:26:59.761606129Z",
   "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": {},
   "RequiredPlugins": {},
   "IsSpawningNPC": true,
   "IsSpawningNPC": true,
Line 134: Line 137:
   "IsSavingPlayers": true,
   "IsSavingPlayers": true,
   "IsSavingChunks": true,
   "IsSavingChunks": true,
  "SaveNewChunks": true,
   "IsUnloadingChunks": true,
   "IsUnloadingChunks": true,
   "IsObjectiveMarkersEnabled": true,
   "IsObjectiveMarkersEnabled": true,
Line 168: Line 172:
|-
|-
| <code>IsSavingChunks</code> || Save world changes
| <code>IsSavingChunks</code> || Save world changes
|-
| <code>SaveNewChunks</code> || Save newly generated chunks to disk
|-
|-
| <code>IsUnloadingChunks</code> || Unload empty chunks
| <code>IsUnloadingChunks</code> || Unload empty chunks
|-
| <code>ClientEffects</code> || Visual effects settings (sun, bloom, sunshafts)
|-
|-
| <code>DeleteOnUniverseStart</code> || Delete world on server start
| <code>DeleteOnUniverseStart</code> || Delete world on server start
Line 175: Line 183:
| <code>DeleteOnRemove</code> || Delete world files when removed
| <code>DeleteOnRemove</code> || Delete world files when removed
|}
|}
== Permissions Configuration (permissions.json) ==
<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>
* <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


== World Pre-Generation ==
== World Pre-Generation ==
Line 284: Line 206:
== 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.
Hytale has built-in support for connecting multiple servers together without third-party proxies like BungeeCord.


<pre>
These features are implemented via the server's Java API:
{
  "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
    }
  }
}
</pre>


{| class="wikitable"
{| class="wikitable"
|-
|-
! Feature !! Description
! Feature !! API Method !! Description
|-
|-
| '''Player Referral''' || Transfer players between servers seamlessly
| '''Player Referral''' || <code>PlayerRef.referToServer(host, port, payload)</code> || Transfer players between servers with optional 4KB payload
|-
|-
| '''Connection Redirect''' || Redirect during handshake before full connection
| '''Connection Redirect''' || <code>PlayerSetupConnectEvent.referToServer(host, port)</code> || Redirect during handshake before full connection
|-
|-
| '''Disconnect Fallback''' || Auto-reconnect to fallback if server crashes
| '''Disconnect Fallback''' || Coming soon || Auto-reconnect to fallback if server crashes
|}
|}


'''Security:''' Referral payloads pass through the client. Use <code>SharedSecret</code> to cryptographically sign payloads so receiving servers can verify authenticity.
'''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 <code>HytaleServer.jar</code> at <code>com.hypixel.hytale.protocol.packets</code>.
'''Custom Proxies:''' Build proxy servers using Netty QUIC. Packet definitions available in <code>HytaleServer.jar</code> at <code>com.hypixel.hytale.protocol.packets</code>.
Line 389: Line 262:
| <code>--backup-dir <path></code> || Backup storage location || ./backups
| <code>--backup-dir <path></code> || Backup storage location || ./backups
|-
|-
| <code>--backup-frequency <mins></code> || Backup interval || 60
| <code>--backup-frequency <mins></code> || Backup interval in minutes || 60
|-
|-
| <code>--disable-sentry</code> || Disable crash reporting || Enabled
| <code>--disable-sentry</code> || Disable crash reporting || Enabled
Line 395: Line 268:
| <code>--allow-op</code> || Allow operator commands || Disabled
| <code>--allow-op</code> || Allow operator commands || Disabled
|-
|-
| <code>--accept-early-plugins</code> || Load experimental plugins || Disabled
| <code>--accept-early-plugins</code> || Load experimental plugins (unsupported) || Disabled
|}
|}


Line 416: Line 289:
<pre>
<pre>
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --auth-mode offline --disable-sentry
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --auth-mode offline --disable-sentry
</pre>
== Firewall Configuration ==
Hytale uses QUIC protocol over UDP (not TCP).
'''Windows PowerShell:'''
<pre>
New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow
</pre>
'''Linux (iptables):'''
<pre>
sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT
</pre>
'''Linux (ufw):'''
<pre>
sudo ufw allow 5520/udp
</pre>
</pre>


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"