HytaleDocs

Instances

Asset path: Server/Instances/*instance.bson

Configuration for a single world. Settings in here only affect the world this configuration belongs to.

Instances share this configuration but ignore certain parameters (e.g. UUID). In this case the configuration willbe cloned before loading the instance.

Version

Type information: Integer

UUID

Type information:

Either String or Map of the following:

KeyType
any Stringanything

DisplayName

The player facing name of this world.

Type information: (Nullable) String

Seed

The seed of the world, used for world generation.

If a seed is not set then one will be randomly generated.

Type information: Integer

SpawnPoint

Deprecated: Please use SpawnProvider instead.

Type information:

(Nullable)

Transform with the following properties:

KeyTypeDescription
XNumber defaults to: 0.0
YNumber defaults to: 0.0
ZNumber defaults to: 0.0
Pitch(Nullable) Either Number or String that matches the pattern: ^(-?Infinity|NaN)$
Yaw(Nullable) Either Number or String that matches the pattern: ^(-?Infinity|NaN)$
Roll(Nullable) Either Number or String that matches the pattern: ^(-?Infinity|NaN)$

SpawnProvider

Sets the spawn provider for the world.

This controls where new players will enter the world at. This can be provided by world generation in some cases.

Type information:

(Nullable) Any of these:

Key: IdType
FitToHeightMap

A spawn provider that takes a spawn point from another provider and, when its Y is the no-height sentinel, places it one block above the heightmap of the world.

FitToHeightMapSpawnProvider

FitToHeightMapSpawnProvider with the following properties:

KeyTypeDescription
IdConstant value: FitToHeightMap

This field controls the type, it must be set to the constant value "FitToHeightMap" to function as this type.

SpawnProvider(Nullable) Type Selector

The target spawn provider to take the initial spawn point from.

default case: Global

A spawn provider that provides a single static spawn point for all players.

GlobalSpawnProvider

GlobalSpawnProvider with the following properties:

KeyTypeDescription
Id(Nullable) String

This field controls the type, it must be set to the constant value "Global" to function as this type.

SpawnPoint(Nullable) Transform

The spawn point for all players to spawn at

Individual

A spawn provider that selects a spawn point from a list based on the player being spawned in. This gives random but consistent spawn points for players.

IndividualSpawnProvider

IndividualSpawnProvider with the following properties:

KeyTypeDescription
IdConstant value: Individual

This field controls the type, it must be set to the constant value "Individual" to function as this type.

SpawnPoints(Nullable) Array of the type: Transform

The list of spawn points to select from.

WorldGen

Sets the world generator that will be used by the world.

Type information:

(Nullable) Any of these:

Key: TypeType
CubicTest

A cubic-aware test generator that tiles the world into colour-coded feature regions to exercise the heightmap and other cubic-chunk paths.

CubicTestWorldGenProvider

Dummy

A dummy world generation provider that places a single layer of unknown blocks in each chunk.

DummyWorldGenProvider

DummyWorldGenProvider with the following properties:

KeyTypeDescription
TypeConstant value: Dummy

This field controls the type, it must be set to the constant value "Dummy" to function as this type.

Flat

A world generation provider that generates a flat world with defined layers.

FlatWorldGenProvider

FlatWorldGenProvider with the following properties:

KeyTypeDescription
TypeConstant value: Flat

This field controls the type, it must be set to the constant value "Flat" to function as this type.

Tint(Nullable) A color in the form:

  • #RRGGBB

  • rgb(rrr, ggg, bbb)

The tint to set for all chunks that are generated.

LayersArray of the type: Layer

The list of layers to add to the world.

default case: Hytale

The standard generator for Hytale.

HytaleWorldGenProvider

HytaleWorldGenProvider with the following properties:

KeyTypeDescription
Type(Nullable) String

This field controls the type, it must be set to the constant value "Hytale" to function as this type.

Name(Nullable) String defaults to: Default

The name of the generator to use. "Default" if not provided.

Version(Nullable) String is at least 1 characters long

The version of the generator to use. "0.0.0" if not provided.

Path(Nullable) String

The path to the world generation configuration.

Defaults to the server provided world generation folder if not set.

HytaleGenerator

The standard generator for Hytale.

HandleProvider

HandleProvider with the following properties:

KeyTypeDescription
TypeConstant value: HytaleGenerator

This field controls the type, it must be set to the constant value "HytaleGenerator" to function as this type.

WorldStructure(Nullable) String defaults to: Default

The world structure to be used for this world.

SeedOverride(Nullable) String

If set, this will override the world's seed to ensure consistency.

Void

A world generation provider that does not generate any blocks.

VoidWorldGenProvider

VoidWorldGenProvider with the following properties:

KeyTypeDescription
TypeConstant value: Void

This field controls the type, it must be set to the constant value "Void" to function as this type.

Tint(Nullable) A color in the form:

  • #RRGGBB

  • rgb(rrr, ggg, bbb)

The tint to set for all chunks that are generated.

Environment(Nullable) String

Reference to a Environment asset

The environment to set for every column in generated chunks.

WorldMap

Type information:

(Nullable) Either

DisabledWorldMapProvider with the following properties:

KeyTypeDescription
TypeConstant value: Disabled

This field controls the type, it must be set to the constant value "Disabled" to function as this type.

or

WorldGenWorldMapProvider with the following properties:

KeyTypeDescription
Type(Nullable) String

This field controls the type, it must be set to the constant value "WorldGen" to function as this type.

WorldMapConfig

Optional per-world overrides for world map configuration and limits.

Type information:

(Nullable)

WorldWorldMapConfig with the following properties:

KeyTypeDescription
ViewRadiusMinInteger
ViewRadiusMaxInteger

ChunkStorage

Sets the storage system that will be used by the world to store chunks.

Type information:

(Nullable) Any of these:

Key: TypeType
Empty

A chunk storage provider that discards any chunks to save and will always fail to find chunks.

EmptyChunkStorageProvider

EmptyChunkStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: Empty

This field controls the type, it must be set to the constant value "Empty" to function as this type.

default case: Hytale

Selects the default recommended storage as decided by the server.

DefaultChunkStorageProvider

DefaultChunkStorageProvider with the following properties:

KeyTypeDescription
Type(Nullable) String

This field controls the type, it must be set to the constant value "Hytale" to function as this type.

VersionInteger
IndexedStorage

Uses the indexed storage file format to store chunks.

IndexedStorageChunkStorageProvider

IndexedStorageChunkStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: IndexedStorage

This field controls the type, it must be set to the constant value "IndexedStorage" to function as this type.

FlushOnWriteBoolean defaults to: false

Controls whether the indexed storage flushes during writes. Recommended to be enabled to prevent corruption of chunks during unclean shutdowns.

Migration

A provider that combines multiple storage providers in a chain to assist with migrating worlds between storage formats.

Can also be used to set storage to load chunks but block saving them if combined with the Empty storage provider

MigrationChunkStorageProvider

MigrationChunkStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: Migration

This field controls the type, it must be set to the constant value "Migration" to function as this type.

Loaders(Nullable) Array of the type: Type Selector (1)

A list of storage providers to use as chunk loaders.

Each loader will be tried in order to load a chunk, returning the chunk if found otherwise trying the next loaded until found or none are left.

Saver(Nullable) Type Selector (1)

The storage provider to use to save chunks.

RocksDb
RocksDbChunkStorageProvider

RocksDbChunkStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: RocksDb

This field controls the type, it must be set to the constant value "RocksDb" to function as this type.

ChunkConfig

Configuration for chunk related settings

Type information:

ChunkConfig with the following properties:

KeyTypeDescription
PregenerateRegion(Nullable)
Box2D

Box2D with the following properties:

KeyTypeDescription
Min(Nullable) Vector2d
Max(Nullable) Vector2d

Sets the region that will be pregenerated for the world.

If set, the specified region will be pregenerated when the world starts.

KeepLoadedRegion(Nullable)
Box2D

Box2D with the following properties:

KeyTypeDescription
Min(Nullable) Vector2d
Max(Nullable) Vector2d

Sets a region of chunks that will never be unloaded.

IsTicking

Sets whether chunks in this world are ticking or not.

Type information: Boolean defaults to: true

IsBlockTicking

Sets whether blocks in this world are ticking or not.

Type information: Boolean defaults to: true

IsPvpEnabled

Sets whether PvP is allowed in this world or not.

Type information: Boolean defaults to: false

IsFallDamageEnabled

Sets whether fall damage is allowed in this world or not.

Type information: Boolean defaults to: true

IsGameTimePaused

Sets whether the game time is paused.

This effects things like day/night cycles and things that rely on those.

Type information: Boolean defaults to: false

GameTime

The current time of day in the world.

Type information: (Nullable) String

ForcedWeather

Sets the type of weather that is being forced to be active in this world.

Type information: (Nullable) String

Reference to a Weather asset

ClientEffects

Settings for the client's weather and post-processing effects in this world.

Type information:

(Nullable)

ClientEffectWorldSettings with the following properties:

KeyTypeDescription
SunHeightPercent(Nullable) Either Number defaults to: 100.0 or String that matches the pattern: ^(-?Infinity|NaN)$
SunAngleDegrees(Nullable) Either Number defaults to: 0.0 or String that matches the pattern: ^(-?Infinity|NaN)$
BloomIntensity(Nullable) Either Number defaults to: 0.30000001192092896 or String that matches the pattern: ^(-?Infinity|NaN)$
BloomPower(Nullable) Either Number defaults to: 8.0 or String that matches the pattern: ^(-?Infinity|NaN)$
SunIntensity(Nullable) Either Number defaults to: 0.25 or String that matches the pattern: ^(-?Infinity|NaN)$
SunshaftIntensity(Nullable) Either Number defaults to: 0.30000001192092896 or String that matches the pattern: ^(-?Infinity|NaN)$
SunshaftScaleFactor(Nullable) Either Number defaults to: 4.0 or String that matches the pattern: ^(-?Infinity|NaN)$

PregenerateRegion

Type information:

(Nullable)

Box with the following properties:

KeyTypeDescription
Min(Nullable)
Vector3d

Vector3d with the following properties:

KeyTypeDescription
XNumber defaults to: 0.0
YNumber defaults to: 0.0
ZNumber defaults to: 0.0
Max(Nullable)
Vector3d

Vector3d with the following properties:

KeyTypeDescription
XNumber defaults to: 0.0
YNumber defaults to: 0.0
ZNumber defaults to: 0.0

RequiredPlugins

Sets the plugins that are required to be enabled for this world to function.

Type information:

(Nullable) Map of the following:

KeyType
StringString

GameMode

Sets the default gamemode for this world.

Type information:

(Nullable) Any one of the following String:

NameDescription
"Adventure"

The normal gamemode for players playing the game.

"Creative"

Makes the player invulnerable and grants them the ability to fly.

DefaultPermissionGroup

The default permission group assigned to new players joining this world.

Type information: (Nullable) String

IsSpawningNPC

Whether NPCs can spawn in this world or not.

Type information: Boolean defaults to: true

IsBlockSpawnersEnabled

Whether block spawners resolve into their target blocks in this world.

Type information: Boolean defaults to: true

IsSpawnMarkersEnabled

Whether spawn markers are enabled for this world.

Type information: Boolean defaults to: true

IsAllNPCFrozen

Whether all NPCs are frozen for this world

Type information: Boolean defaults to: false

GameplayConfig

The gameplay configuration being used by this world

Type information: (Nullable) String defaults to: Default

Reference to a GameplayConfig asset

Death

Inline death configuration overrides for this world. If set, these values take precedence over the referenced GameplayConfig.

Type information:

(Nullable)

MutableDeathConfig with the following properties:

KeyTypeDescription
RespawnControllerType Selector (2)

The respawn controller that determines where the player respawns.

ItemsLossMode(Nullable) Any one of the following String (defaults to None):
ItemsLossMode
NameDescription
"None"
"All"
"Configured"

The mode used to compute what the entity will lose upon death.

ItemsAmountLossPercentageNumber defaults to: 10.0

The amount (in %) of items lost for an ItemStack upon death (applied to the entire inventory). Used ONLY if ItemsLossMode is set to 'Configuredand applied to items that haveDropOnDeathset totrue`.

ItemsDurabilityLossPercentageNumber defaults to: 10.0

The amount of durability (in %) items lose upon death (applied to the entire inventory).

GameModeTypeOnDeath(Nullable) String

Reference to a GameModeType asset

When set, dying players skip the respawn screen, respawn in place, and enter this GameModeType. When unset, normal death behavior applies.

DaytimeDurationSeconds

Override for the duration of daytime in seconds. If set, takes precedence over the referenced GameplayConfig.

Type information: Integer

NighttimeDurationSeconds

Override for the duration of nighttime in seconds. If set, takes precedence over the referenced GameplayConfig.

Type information: Integer

IsCompassUpdating

Whether the compass is updating in this world

Type information: Boolean defaults to: true

IsSavingPlayers

Whether the configuration for player's is being saved for players in this world.

Type information: Boolean defaults to: true

IsSavingChunks

Whether the chunk data is allowed to be saved to the disk for this world.

Type information: Boolean defaults to: true

SaveNewChunks

Whether newly generated chunks should be marked for saving or not. Enabling this can prevent random chunks from being out of place if/when worldgen changes but will increase the size of the world on disk.

Type information: Boolean defaults to: true

IsUnloadingChunks

Whether the chunks should be unloaded like normally, or should be prevented from unloading at all.

Type information: Boolean defaults to: true

IsObjectiveMarkersEnabled

Whether objective markers are enabled for this world.

Type information: Boolean defaults to: true

DeleteOnUniverseStart

Whether this world should be deleted when loaded from Universe start. By default this is when going through the world folders in the universe directory.

Type information: Boolean defaults to: false

DeleteOnRemove

Whether this world should be deleted once its been removed from the server

Type information: Boolean defaults to: false

CrashRecovery

Recovery policy for this world when its thread crashes. Overrides the server default.

Type information:

(Nullable)

CrashRecoveryConfig with the following properties:

KeyTypeDescription
Mode(Nullable) Any one of the following String:
WorldCrashRecovery
NameDescription
"None"
"Reload"
"Shutdown"

The action taken when the world crashes. One of None, Reload or Shutdown. If unset, the default world uses the singleplayer or dedicated default. Any other world with this block reloads.

MaxAttemptsInteger

The number of reload attempts before the fallback runs. Reload only.

RetryDelaySecondsInteger

The delay in seconds before a reload attempt. Reload only.

Fallback(Nullable) Any one of the following String:
WorldCrashRecovery
NameDescription
"None"
"Reload"
"Shutdown"

The action after the reload attempts run out. One of None or Shutdown. Reload only.

Instance

Instance specific configuration.

Type information:

(Nullable) Map of the following:

KeyType
any Stringanything

DisabledFluidTickers

A set of fluid tag strings (e.g. "Fluid=Water", "Fire=Fire") whose tickers should be disabled in this world. Fluids matching any of these tags will not tick.

Type information: (Nullable) Array of String

ResourceStorage

Sets the storage system that will be used to store resources.

Type information:

(Nullable) Any of these:

Key: TypeType
Disk
DiskResourceStorageProvider

DiskResourceStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: Disk

This field controls the type, it must be set to the constant value "Disk" to function as this type.

Path(Nullable) String defaults to: resources
Empty
EmptyResourceStorageProvider

EmptyResourceStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: Empty

This field controls the type, it must be set to the constant value "Empty" to function as this type.

default case: Hytale
DefaultResourceStorageProvider

DefaultResourceStorageProvider with the following properties:

KeyTypeDescription
Type(Nullable) String

This field controls the type, it must be set to the constant value "Hytale" to function as this type.

Plugin

Type information:

Object with the following properties:

KeyTypeDescription
CreativeHub
CreativeHubWorldConfig

CreativeHubWorldConfig with the following properties:

KeyTypeDescription
StartupInstance(Nullable) String

The instance asset path under Server/Instances (for example Defaults/CreativeHub for the Crossroads template).

Instance
InstanceWorldConfig

InstanceWorldConfig with the following properties:

KeyTypeDescription
RemovalConditionsArray of the type: Type Selector (4)

The set of conditions that have to be met to remove the world.

If no conditions are provided (e.g. a empty list) then the world will not be removed automatically

ReturnPoint(Nullable) WorldReturnPoint

The location to send players to when leaving this world.

PreventReconnectionBoolean defaults to: false

Whether to prevent reconnecting into this world.

Players that reconnect back into the world will forced out of the world to the return point (or their own).

InheritWorldSettingsBoolean defaults to: false

Whether a new copy of this instance inherits settings defined by the player upon world creation (e.g. fall damage, PvP). Disabled by default.

Discovery(Nullable) InstanceDiscoveryConfig

Optional discovery configuration for displaying an event title when a player enters this instance for the first time.

RespawnWhenTargetedBoolean defaults to: false

Whether a return point targeting a copy of this instance reuses a live copy, or spawns a fresh one, when the original copy is gone. Requires InstanceKey. Only enable this on instances that restore their own state (or are stateless), because a fresh copy starts from the template.

InstanceKey(Nullable) String

The fixed world key this instance's single copy lives under. Every spawn path converges on this one copy, and returns look it up by this key. Omit for instances that spawn a copy per use.

InstanceName(Nullable) String

The instance asset this world was spawned from. Set by the spawn flow; not authored.

EventTitleOnRemoval(Nullable) EventTitleConfig

The event title to show to the players of this world while it closes. If no title is provided then the world closes immediately.

PortalWorldConfig
PortalWorldConfig

PortalWorldConfig with the following properties:

KeyTypeDescription
Config(Nullable) PortalKey

An inline portal key to mimic. On start, the world is configured as if summoned through a portal device with this key.

Marks a world as a portal world without a summoning device.

WorldEvents
WorldEventsWorldConfig

WorldEventsWorldConfig with the following properties:

KeyTypeDescription
EnableWorldEventsBoolean defaults to: true

Sets whether world events run in this world. When false, no gameplay or global world events start and running events are cancelled.

Notes:

Types referenced by this type

Type Selector

Any of these:

Key: IdType
FitToHeightMap

A spawn provider that takes a spawn point from another provider and, when its Y is the no-height sentinel, places it one block above the heightmap of the world.

FitToHeightMapSpawnProvider

FitToHeightMapSpawnProvider with the following properties:

KeyTypeDescription
IdConstant value: FitToHeightMap

This field controls the type, it must be set to the constant value "FitToHeightMap" to function as this type.

SpawnProvider(Nullable) Type Selector

The target spawn provider to take the initial spawn point from.

default case: Global

A spawn provider that provides a single static spawn point for all players.

GlobalSpawnProvider

GlobalSpawnProvider with the following properties:

KeyTypeDescription
Id(Nullable) String

This field controls the type, it must be set to the constant value "Global" to function as this type.

SpawnPoint(Nullable) Transform

The spawn point for all players to spawn at

Individual

A spawn provider that selects a spawn point from a list based on the player being spawned in. This gives random but consistent spawn points for players.

IndividualSpawnProvider

IndividualSpawnProvider with the following properties:

KeyTypeDescription
IdConstant value: Individual

This field controls the type, it must be set to the constant value "Individual" to function as this type.

SpawnPoints(Nullable) Array of the type: Transform

The list of spawn points to select from.

Type Selector (1)

Any of these:

Key: TypeType
Empty

A chunk storage provider that discards any chunks to save and will always fail to find chunks.

EmptyChunkStorageProvider

EmptyChunkStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: Empty

This field controls the type, it must be set to the constant value "Empty" to function as this type.

default case: Hytale

Selects the default recommended storage as decided by the server.

DefaultChunkStorageProvider

DefaultChunkStorageProvider with the following properties:

KeyTypeDescription
Type(Nullable) String

This field controls the type, it must be set to the constant value "Hytale" to function as this type.

VersionInteger
IndexedStorage

Uses the indexed storage file format to store chunks.

IndexedStorageChunkStorageProvider

IndexedStorageChunkStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: IndexedStorage

This field controls the type, it must be set to the constant value "IndexedStorage" to function as this type.

FlushOnWriteBoolean defaults to: false

Controls whether the indexed storage flushes during writes. Recommended to be enabled to prevent corruption of chunks during unclean shutdowns.

Migration

A provider that combines multiple storage providers in a chain to assist with migrating worlds between storage formats.

Can also be used to set storage to load chunks but block saving them if combined with the Empty storage provider

MigrationChunkStorageProvider

MigrationChunkStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: Migration

This field controls the type, it must be set to the constant value "Migration" to function as this type.

Loaders(Nullable) Array of the type: Type Selector (1)

A list of storage providers to use as chunk loaders.

Each loader will be tried in order to load a chunk, returning the chunk if found otherwise trying the next loaded until found or none are left.

Saver(Nullable) Type Selector (1)

The storage provider to use to save chunks.

RocksDb
RocksDbChunkStorageProvider

RocksDbChunkStorageProvider with the following properties:

KeyTypeDescription
TypeConstant value: RocksDb

This field controls the type, it must be set to the constant value "RocksDb" to function as this type.

Type Selector (2)

Any of these:

Key: TypeType
ExitInstance
ExitInstance

ExitInstance with the following properties:

KeyTypeDescription
TypeConstant value: ExitInstance

This field controls the type, it must be set to the constant value "ExitInstance" to function as this type.

FallbackType Selector (3)
HomeOrSpawnPoint
HomeOrSpawnPoint

HomeOrSpawnPoint with the following properties:

KeyTypeDescription
TypeConstant value: HomeOrSpawnPoint

This field controls the type, it must be set to the constant value "HomeOrSpawnPoint" to function as this type.

WorldSpawnPoint
WorldSpawnPoint

WorldSpawnPoint with the following properties:

KeyTypeDescription
TypeConstant value: WorldSpawnPoint

This field controls the type, it must be set to the constant value "WorldSpawnPoint" to function as this type.

Type Selector (3)

Any of these:

Key: TypeType
ExitInstance
ExitInstance

ExitInstance with the following properties:

KeyTypeDescription
TypeConstant value: ExitInstance

This field controls the type, it must be set to the constant value "ExitInstance" to function as this type.

FallbackType Selector (3)
HomeOrSpawnPoint
HomeOrSpawnPoint

HomeOrSpawnPoint with the following properties:

KeyTypeDescription
TypeConstant value: HomeOrSpawnPoint

This field controls the type, it must be set to the constant value "HomeOrSpawnPoint" to function as this type.

WorldSpawnPoint
WorldSpawnPoint

WorldSpawnPoint with the following properties:

KeyTypeDescription
TypeConstant value: WorldSpawnPoint

This field controls the type, it must be set to the constant value "WorldSpawnPoint" to function as this type.

Type Selector (4)

Any of these:

Key: TypeType
IdleTimeout

A condition that triggers after the world has be idle (without players) for a set time.

IdleTimeoutCondition

IdleTimeoutCondition with the following properties:

KeyTypeDescription
TypeConstant value: IdleTimeout

This field controls the type, it must be set to the constant value "IdleTimeout" to function as this type.

TimeoutSecondsNumber defaults to: 300.0

How long (in seconds) the world has to be idle (without players) for before triggering.

Portal

A condition for temporary portal worlds.

PortalRemovalCondition

PortalRemovalCondition with the following properties:

KeyTypeDescription
TypeConstant value: Portal

This field controls the type, it must be set to the constant value "Portal" to function as this type.

TimeoutSecondsNumber defaults to: 60.0

How long the portal world will stay open (in seconds) after being joined. 0 or less means no time limit.

Timeout

A condition that triggers after a set time limit.

TimeoutCondition

TimeoutCondition with the following properties:

KeyTypeDescription
TypeConstant value: Timeout

This field controls the type, it must be set to the constant value "Timeout" to function as this type.

TimeoutSecondsNumber defaults to: 300.0

How long to wait (in seconds) before closing the world.

WorldEmpty

A condition that triggers when the world is empty.

It will only trigger after at least one player has joined. As a safety measure it provides a timeout for waiting for a player to join in case the player disconnected before entering the world.

WorldEmptyCondition

WorldEmptyCondition with the following properties:

KeyTypeDescription
TypeConstant value: WorldEmpty

This field controls the type, it must be set to the constant value "WorldEmpty" to function as this type.

TimeoutSecondsNumber defaults to: 300.0

How long to wait (in seconds) for a player to join before closing the world.

On this page