Skip to main content

​
Master Your Hytale Server

This complete guide covers everything from basic configuration to advanced multi-server architectures. Whether you are setting up your first server or optimizing a production environment, you will find expert-level instructions here.

Difficulty

Intermediate

Time

15 Minutes

​
Configuration File Locations

Your Hytale server uses several JSON configuration files to manage its behavior. Understanding where these files are located is the first step toward effective server management.

​
Server Root Directory

FilePurposeWhen to Edit
config.jsonMain server settingsServer name, slots, view distance
permissions.jsonPlayer permissions & admin groupsAdding admins, setting roles
bans.jsonBanned player listBanning/unbanning players
whitelist.jsonAllowed players (if enabled)Private server access

​
World-Specific Configuration

LocationPurpose
universe/worlds/[WorldName]/config.jsonIndividual world settings (PvP, spawning, effects)

​
Editing Your Configuration

Follow these steps to safely modify your server files.

​
Safety 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.

​
How to Edit Files

​
Server Configuration (config.json)

The main config.json controls your server core behavior. This is the primary file for customization.

​
Settings Overview

SettingDescription
ServerNameThe name displayed in the server browser.
MaxPlayersThe maximum number of simultaneous players.
MaxViewRadiusControls how many chunks are sent to players (impacts performance).

​
Advanced Architecture

​
Multi-Server Support

Hytale features built-in multi-server support, meaning you do not need an external proxy like BungeeCord or Velocity.

​
Network Protocol

Hytale uses the QUIC protocol over UDP instead of traditional TCP. Ensure your firewall is configured to allow UDP traffic on your server ports.
For high-traffic servers, adjusting launch arguments can improve stability.
  • -XX:+UseG1GC: Recommended garbage collector for Hytale.
  • -Xms and -Xmx: Set your minimum and maximum RAM allocation.
Eliminate exploration lag by pre-generating your world chunks before players join. This significantly reduces CPU strain during gameplay.

​
Need Extra Help?

If you encounter any issues, our support team is ready to assist:

​
Save on Your Hosting

Ready to get a new server? Use code KB20 at checkout for 20% off your first month!
Last Updated: January 2026 | Hytale: Advanced Configuration Guide.

​
World Configuration (Per-World Settings)

Each world has independent settings stored in universe/worlds/[WorldName]/config.json. These allow you to customize gameplay mechanics per dimension or world instance.

​
Gameplay Settings

SettingDefaultDescription
SeedRandomThe world generation seed.
IsPvpEnabledfalseEnables or disables player combat.
IsFallDamageEnabledtrueControls if players take damage from falling.
IsGameTimePausedfalseFreezes the day/night cycle.
IsSpawningNPCtrueEnables natural NPC spawning.
IsAllNPCFrozenfalseFreezes all NPC AI.

​
Performance & Save Settings

SettingDefaultDescription
IsTickingtrueControls if world physics are active.
IsBlockTickingtrueControls if block updates are active.
IsSavingPlayerstrueEnables saving of player data.
IsSavingChunkstrueEnables saving of terrain changes.
SaveNewChunkstrueCaches new terrain as it is generated.
IsUnloadingChunkstrueFrees unused memory by unloading distant chunks.
DeleteOnUniverseStartfalseWipes the world on every restart (use with extreme caution).

​
Visual Effects (ClientEffects)

EffectDefaultDescription
SunIntensity0.25Adjusts the brightness of the sun.
BloomIntensity0.3Controls the strength of the glow effect.
BloomPower8.0Adjusts the sharpness of the bloom effect.
SunshaftIntensity0.3Controls the strength of “God rays”.

​
World Pre-Generation

Pre-generating terrain before players explore eliminates chunk generation lag during gameplay. This is highly recommended for production servers.
Best for small maps or quick setups.
  1. Start your server and join as an admin.
  2. Enable fly mode.
  3. Fly around the map; chunks will save automatically as they are rendered.
Best for large worlds and automated generation.
  1. Download a pre-generation mod and place it in the mods/ folder.
  2. Configure the radius and center coordinates.
  3. Execute the generation command provided by the mod.
Check for native options using:
java -jar HytaleServer.jar --help

​
Server Mesh Architecture

Hytale features built-in multi-server support, allowing you to transfer players between servers without an external proxy like BungeeCord.

​
Transferring Players

You can use the native Java API to move players smoothly: 
// Send a player to another server
PlayerRef.referToServer(host, port, payload)

// Handle incoming player connections
PlayerSetupConnectEvent.referToServer(host, port)

​
Security Alert

Referral payloads pass through the client and can be modified. Always sign payloads using HMAC with a shared secret key so the receiving server can verify authenticity.

​
Launch Options & Performance

​
JVM Memory Flags

For optimal stability, allocate enough RAM to your Hytale instance. We recommend setting the initial and maximum RAM to the same value to prevent performance dips during allocation.
FlagExamplePurpose
-Xms-Xms6GInitial RAM allocation.
-Xmx-Xmx6GMaximum RAM allocation.
-XX:+UseG1GC—G1 Garbage Collector (recommended for low-latency).

​
Server Launch Options

FlagDescription
--assets <path>Game assets location (e.g., Assets.zip).
--bind <ip:port>Bind to a specific network interface.
--auth-mode <mode>authenticated (online) or offline (LAN).
--backupEnables automatic world backups.
--backup-frequency <mins>Time between backups in minutes.

​
Need Extra Help?

If you encounter any issues, our support team is ready to assist:

​
Save on Your Hosting

Ready to get a new server? Use code KB20 at checkout for 20% off your first month!
Last Updated: January 2026 | Hytale: Advanced Configuration Guide.