config.json

The main server configuration file at the server root. Auto-generated with defaults on first launch if it doesn’t exist. Changes made via the API are saved automatically.

File: config.json
Class: HytaleServerConfig

HytaleServerConfig config = HytaleServer.get().getConfig();

Core Settings

Field	Type	Default	Description
ServerName	String	"Hytale Server"	Server name shown in the server list
MOTD	String	""	Message of the day
Password	String	""	Server password (empty = no password)
MaxPlayers	int	100	Maximum concurrent players
MaxViewRadius	int	32	Maximum view distance in chunks
DefaultModsEnabled	boolean	true (multiplayer) / false (singleplayer)	Whether mods in the mods/ directory are enabled by default
SkipModValidationForVersion	String	null	Skip mod validation for a specific server version
DisplayTmpTagsInStrings	boolean	false	Show temporary tags in string output (debugging)

config.setServerName("My Server");
config.setMotd("Welcome!");
config.setMaxPlayers(50);
config.setMaxViewRadius(16);

Defaults

Controls the default world and game mode for new players.

Field	Type	Default	Description
Defaults.World	String	"default"	Name of the world players join on connect
Defaults.GameMode	GameMode	Adventure	Default game mode

HytaleServerConfig.Defaults defaults = config.getDefaults();
defaults.setWorld("lobby");
defaults.setGameMode(GameMode.Creative);

Connection Timeouts

Timeouts for each phase of the connection lifecycle. The server uses different defaults depending on whether it’s running in singleplayer or multiplayer mode.

Field	Singleplayer	Multiplayer	Description
InitialTimeout	30s	15s	Initial connection handshake
AuthTimeout	60s	30s	Authentication exchange
AuthGrantTimeout	60s	30s	Auth grant response
AuthTokenTimeout	60s	30s	Auth token exchange
AuthServerExchangeTimeout	30s	15s	Auth server exchange
PasswordTimeout	60s	45s	Password entry
PlayTimeout	120s	60s	Transition to play state
SetupWorldSettings	30s	15s	World settings sync
SetupAssetsRequest	300s	120s	Asset request phase
SetupSendAssets	300s	120s	Asset transfer phase
SetupAddToUniverse	120s	60s	Adding player to universe

If a phase exceeds its timeout, the connection is dropped. Singleplayer defaults are more generous to account for local loading.

{
  "ConnectionTimeouts": {
    "InitialTimeout": "PT15S",
    "AuthTimeout": "PT30S",
    "PlayTimeout": "PT60S"
  }
}

Duration values use ISO 8601 format: PT15S = 15 seconds, PT2M = 2 minutes.

Rate Limiting

Limits inbound packets per connection to mitigate abuse.

Field	Type	Default	Description
RateLimit.Enabled	boolean	true	Whether rate limiting is active
RateLimit.PacketsPerSecond	int	2000	Sustained packet rate
RateLimit.BurstCapacity	int	500	Burst allowance above the sustained rate

HytaleServerConfig.RateLimitConfig rateLimit = config.getRateLimitConfig();
rateLimit.setPacketsPerSecond(1000);
rateLimit.setBurstCapacity(200);

Modules

Hierarchical module toggle system. Each module has an Enabled flag and can contain nested sub-modules and arbitrary data via a BsonDocument.

{
  "Modules": {
    "MyModule": {
      "Enabled": true,
      "Modules": {
        "SubModule": {
          "Enabled": false
        }
      }
    }
  }
}

HytaleServerConfig.Module module = config.getModule("MyModule");
boolean enabled = module.isEnabled(true); // pass default if not set

// nested modules
HytaleServerConfig.Module sub = module.getModule("SubModule");

// store/retrieve custom typed data
module.put(myKeyedCodec, myValue);
MyType value = module.getDataNow(myKeyedCodec);

Modules that don’t exist yet are auto-created when accessed via getModule().

Log Levels

Per-package log levels as a string-to-level map. Uses java.util.logging.Level names.

{
  "LogLevels": {
    "com.hypixel.hytale.server.core": "FINE",
    "com.hypixel.hytale.server.core.universe": "WARNING"
  }
}

See also the —log CLI argument for setting levels at startup.

Mods

Per-mod configuration. Each entry is keyed by PluginIdentifier (format: group:name) and can enable/disable the mod or require a specific version range.

Field	Type	Description
Mods.<id>.Enabled	Boolean	true to enable, false to disable, null for default
Mods.<id>.RequiredVersion	SemverRange	Required version range (rejects mods outside this range)

{
  "Mods": {
    "mygroup:mymod": {
      "Enabled": true,
      "RequiredVersion": ">=1.0.0 <2.0.0"
    },
    "hytale:teleport": {
      "Enabled": false
    }
  }
}

Note

In config versions 0-2, this field was called Plugins. On load, entries are automatically migrated to Mods.

Player Storage

Controls how player data is persisted. Two built-in providers:

Type	Description
Hytale (default)	Default provider — uses disk storage at <universe>/players/
Disk	Explicit disk storage with a configurable path

{
  "PlayerStorage": {
    "Type": "Disk",
    "Path": "/data/players"
  }
}

The default Hytale provider stores player data as <uuid>.json files in the universe’s players/ directory.

Backup

Controls the built-in periodic backup system. All fields can be overridden by CLI arguments.

Field	Type	Default	Description
Backup.Enabled	boolean	false	Whether automatic backups are enabled
Backup.FrequencyMinutes	int	30	Minutes between backups (minimum 1)
Backup.Directory	String	null	Backup directory path (required for backups to run)
Backup.MaxCount	int	5	Maximum recent backups to retain
Backup.ArchiveMaxCount	int	5	Maximum archived backups to retain

Backups only run when both Enabled is true and Directory is set. The --backup CLI flag overrides Enabled to true.

{
  "Backup": {
    "Enabled": true,
    "FrequencyMinutes": 60,
    "Directory": "/backups/hytale",
    "MaxCount": 10,
    "ArchiveMaxCount": 5
  }
}

Auth Credential Store

Raw BSON configuration for the authentication credential store provider. This controls how the server stores its OAuth tokens for the authentication system.

{
  "AuthCredentialStore": { ... }
}

Auto-Update

Controls the built-in server update system.

Field	Type	Default	Description
Update.Enabled	boolean	true	Whether update checking is active
Update.CheckIntervalSeconds	int	3600	Seconds between update checks
Update.NotifyPlayersOnAvailable	boolean	true	Notify online players when an update is available
Update.Patchline	String	null	Patchline to track (e.g. "release")
Update.RunBackupBeforeUpdate	boolean	true	Run a full backup before applying an update
Update.BackupConfigBeforeUpdate	boolean	true	Back up config files before update
Update.AutoApplyMode	enum	DISABLED	When to auto-apply updates (see below)
Update.AutoApplyDelayMinutes	int	30	Delay before auto-applying

Auto-Apply Modes

Mode	Behavior
DISABLED	Never auto-apply — manual only
WHEN_EMPTY	Apply when no players are online
SCHEDULED	Apply after AutoApplyDelayMinutes regardless of players

When an update is applied, the server backs up config.json, permissions.json, bans.json, and whitelist.json if backup is enabled.

Example

A minimal config.json with common customizations:

{
  "Version": 4,
  "ServerName": "My Hytale Server",
  "MOTD": "Welcome to the server!",
  "Password": "",
  "MaxPlayers": 50,
  "MaxViewRadius": 16,
  "Defaults": {
    "World": "lobby",
    "GameMode": "Adventure"
  },
  "RateLimit": {
    "Enabled": true,
    "PacketsPerSecond": 2000,
    "BurstCapacity": 500
  },
  "Mods": {
    "hytale:buildertools": {
      "Enabled": false
    }
  },
  "Update": {
    "Enabled": true,
    "AutoApplyMode": "WHEN_EMPTY"
  }
}