Master Your Hytale Server — This comprehensive guide covers everything from basic configuration to advanced multi-server architectures. Whether you’re setting up your first server or optimizing a production environment, you’ll find expert-level instructions here.
| Reading Time | Difficulty | Last Updated |
|---|
| 15 minutes | Intermediate | January 2026 |
Quick Navigation
| Section | What You’ll Learn |
|---|
| File Locations | Where to find all config files |
| Editing Files | Step-by-step editing guide |
| Server Config | Main server settings explained |
| World Config | Per-world customization |
| Pre-Generation | Eliminate exploration lag |
| Multi-Server | Connect multiple servers |
| Launch Arguments | JVM flags & server options |
| Firewall | Network & port configuration |
Important: Before You Begin
[!CAUTION]
Stop! Read This First
- Always create a backup of your server files before making changes
- Stop your server completely before editing any configuration files
- Changes made while the server is running will be overwritten
Configuration File Locations
Your Hytale server uses several JSON configuration files. Here’s where to find each one:
Server Root Directory
| File | Purpose | When to Edit |
|---|
config.json | Main server settings | Server name, slots, view distance |
permissions.json | Player permissions & admin groups | Adding admins, setting roles |
bans.json | Banned player list | Banning/unbanning players |
whitelist.json | Allowed players (if enabled) | Private server access |
World-Specific Configuration
| Location | Purpose |
|---|
universe/worlds/[WorldName]/config.json | Individual world settings (PvP, spawning, effects) |
How to Edit Configuration Files
Option A: Hosted Server (Control Panel)
Step 1 → Log into your control panel
Step 2 → Click "Stop" to shut down the server
Step 3 → Navigate to "Configuration Files" or "FTP Access"
Step 4 → Edit the file and click "Save"
Step 5 → Click "Start" to restart your server
Option B: Self-Hosted Server
Step 1 → Stop the server (type "stop" or press Ctrl+C)
Step 2 → Open the config file in any text editor
Step 3 → Make changes and save the file
Step 4 → Start your server
Pro Tip: Use a JSON validator (like jsonlint.com) to check your syntax before saving!
Server Configuration (config.json)
The main config.json controls your server’s core behavior. This is the first file you should customize.
Complete config.json Template
{
"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"
}
}
Settings Reference Table
| Setting | Type | Default | Description |
|---|
ServerName | String | ”Hytale Server” | Name shown in server browser |
MOTD | String | Empty | Welcome message for players |
Password | String | Empty | Leave blank for public servers |
MaxPlayers | Integer | 100 | Maximum player slots |
MaxViewRadius | Integer | 32 | Render distance (chunks) |
LocalCompressionEnabled | Boolean | false | Compress local network traffic |
Defaults.World | String | ”default” | Spawn world for new players |
Defaults.GameMode | String | ”Adventure” | Starting game mode |
[!IMPORTANT]
Optimize Your View Distance
The official Hytale documentation recommends MaxViewRadius: 12 instead of 32.
| Setting | RAM Usage | Performance |
|---|
MaxViewRadius: 32 | Very High | May cause lag |
MaxViewRadius: 12 | Optimal | Recommended |
World Configuration (Per-World Settings)
Each world has independent settings stored in universe/worlds/[WorldName]/config.json.
Complete World config.json Template
{
"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": {}
}
Gameplay Settings
| Setting | Default | What It Does |
|---|
Seed | Random | World generation seed |
IsPvpEnabled | false | Enable player combat |
IsFallDamageEnabled | true | Players take fall damage |
IsGameTimePaused | false | Freeze day/night cycle |
IsSpawningNPC | true | Natural NPC spawns |
IsAllNPCFrozen | false | Freeze all NPC AI |
| Setting | Default | What It Does |
|---|
IsTicking | true | World physics active |
IsBlockTicking | true | Block updates active |
IsSavingPlayers | true | Save player data |
IsSavingChunks | true | Save terrain changes |
SaveNewChunks | true | Cache new terrain |
IsUnloadingChunks | true | Free unused memory |
DeleteOnUniverseStart | false | Wipes world on restart (use with caution) |
Visual Effects (ClientEffects)
| Effect | Default | Range | Description |
|---|
SunIntensity | 0.25 | 0.0 - 1.0 | Sunlight brightness |
BloomIntensity | 0.3 | 0.0 - 1.0 | Glow effect strength |
BloomPower | 8.0 | 1.0 - 16.0 | Bloom sharpness |
SunshaftIntensity | 0.3 | 0.0 - 1.0 | ”God rays” strength |
World Pre-Generation (Reduce Lag)
Pre-generating terrain before players explore eliminates chunk generation lag during gameplay.
Method 1: Manual Exploration
Best for: Small maps, quick setup
| Step | Action |
|---|
| 1 | Start server and join as admin |
| 2 | Enable fly mode and explore the map |
| 3 | Chunks save automatically as you fly |
Method 2: Pre-Generation Mods
Best for: Large worlds, automated generation
| Step | Action |
|---|
| 1 | Download a pre-gen mod and place in mods/ folder |
| 2 | Configure radius and center coordinates |
| 3 | Run the mod’s generation command |
Method 3: Built-in Command Line
Best for: Checking native options
java -jar HytaleServer.jar --help
Server Mesh Architecture (Multi-Server Networks)
Hytale has built-in multi-server support — no BungeeCord or Velocity proxy needed!
Transfer Players Between Servers
Use the native Java API to move players seamlessly:
// Send a player to another server
PlayerRef.referToServer(host, port, payload)
// Handle incoming player connections
PlayerSetupConnectEvent.referToServer(host, port)
Referral payloads pass through the client and can be modified by hackers.
Solution: Sign all payloads using HMAC with a shared secret key so receiving servers can verify authenticity.
Building Custom Proxies
For advanced network architectures, build custom proxy servers:
| Technology | Location |
|---|
| Netty QUIC | Transport layer |
| Packet Definitions | HytaleServer.jar → com.hypixel.hytale.protocol.packets |
Command-Line Arguments & Launch Options
Basic Launch Syntax
java [JVM options] -jar HytaleServer.jar [server options]
| Flag | Example | Purpose |
|---|
-Xms | -Xms4G | Initial RAM (set equal to -Xmx) |
-Xmx | -Xmx4G | Maximum RAM allocation |
-XX:+UseG1GC | — | G1 Garbage Collector (recommended) |
-XX:AOTCache | HytaleServer.aot | Faster startup via AOT compilation |
Server Launch Options
| Flag | Description |
|---|
--assets <path> | Game assets location (e.g., Assets.zip) |
--bind <ip:port> | Bind to specific network interface |
--auth-mode <mode> | authenticated (online) or offline (LAN) |
--backup | Enable automatic world backups |
--backup-dir <path> | Custom backup storage location |
--backup-frequency <mins> | Time between backups (minutes) |
--disable-sentry | Disable crash reporting |
--allow-op | Enable operator commands |
--accept-early-plugins | Allow early plugin initialization |
Ready-to-Use 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
start.sh)
#!/bin/bash
java -Xms6G -Xmx6G -XX:+UseG1GC -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip --backup --backup-frequency 60
java -Xms4G -Xmx4G -jar HytaleServer.jar --assets Assets.zip --auth-mode offline --disable-sentry
Firewall Configuration (Open Ports)
Hytale uses QUIC protocol over UDP — not TCP!
| Protocol | Port | Direction |
|---|
| UDP | 5520 | Inbound |
Windows — PowerShell (Run as Administrator)
New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow
Linux — UFW (Recommended)
Linux — iptables
sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT
Additional Resources
| Resource | Link |
|---|
| Official Hytale Website | hytale.com |
| Hytale Support Portal | support.hytale.com |
Support Channels
If you need assistance or have any questions, please contact our support team:First Month Discount
Use code KB20 at checkout to get 20% off your first month of hosting!
Last Updated: January 2026 | Need Help? Contact our 24/7 support team!