Hytale Updated April 27, 2026

Configuring Your Hytale Server (config.json)

A complete reference for the Hytale server config.json file and its most important settings.

HytaleConfigconfig.jsonSettingsGame Modes

Configuring Your Hytale Server (config.json)

Hytale server configuration lives in two places: the root config.json for global server settings, and per-world config.json files under universe/worlds/<world-name>/config.json for world-specific options.

Root config.json

The root config.json is located in your server's root directory, alongside HytaleServer.jar. This file controls server identity, networking, and default gameplay rules.

Full Example

{
  "serverName": "My Hytale Server",
  "maxPlayers": 20,
  "gameMode": "survival",
  "difficulty": "normal",
  "pvp": false,
  "whitelist": false,
  "port": 5520,
  "motd": "Welcome to My Hytale Server!",
  "viewDistance": 10,
  "tickRate": 20
}

Field Reference

Field	Type	Default	Description
`serverName`	string	`"Hytale Server"`	Display name shown in the server browser
`maxPlayers`	integer	`20`	Maximum concurrent players (subject to session limits)
`gameMode`	string	`"survival"`	`"survival"` or `"creative"`
`difficulty`	string	`"normal"`	`"peaceful"`, `"easy"`, `"normal"`, or `"hard"`
`pvp`	boolean	`false`	Enables player-vs-player combat
`whitelist`	boolean	`false`	When `true`, only players in `whitelist.json` can join
`port`	integer	`5520`	UDP port for the server (QUIC)
`motd`	string	`""`	Message of the day shown on the server listing
`viewDistance`	integer	`10`	Chunk render distance; lower values reduce CPU/RAM load
`tickRate`	integer	`20`	Server tick rate; 20 is standard

Per-World config.json

Each world in universe/worlds/ can have its own config.json to override global settings for that specific world:

universe/worlds/overworld/config.json
universe/worlds/dungeon-realm/config.json

A per-world config supports a subset of the global options plus world-specific keys:

{
  "gameMode": "survival",
  "difficulty": "hard",
  "pvp": true,
  "seed": 8675309,
  "generateStructures": true
}

Per-world settings take precedence over the root config.json for players in that world.

Applying Configuration Changes

Most settings require a server restart to take effect. Stop the server, edit config.json, then start again:

sudo systemctl stop hytale
nano /opt/hytale-server/config.json
sudo systemctl start hytale

Common Configuration Tasks

Enabling the Whitelist

{
  "whitelist": true
}

After enabling, add players in whitelist.json. See Using the Hytale Server Whitelist.

Switching to Creative Mode

{
  "gameMode": "creative"
}

Reducing Lag on Low-RAM Servers

Reduce view distance and tick rate:

{
  "viewDistance": 6,
  "tickRate": 20
}

See Hytale Server Performance Optimization for more tuning tips.

Changing the Port

If you need to run on a non-default port, update the port field and make sure UDP is opened on the new port in your firewall:

{
  "port": 5521
}

Back to Knowledgebase

Need help? Submit a Ticket →

Configuring Your Hytale Server (config.json)