World Configuration

World settings use a two-layer system: WorldConfig (per-world, saved to disk) and GameplayConfig (asset-based, shared by name). Some WorldConfig fields can override GameplayConfig values.

WorldConfig

Per-world configuration saved as config.json in each world’s directory. Saved automatically by WorldConfigSaveSystem every 10 seconds when changed.

WorldConfig config = world.getWorldConfig();

Core Settings

Field	Type	Default	Description
`DisplayName`	`String`	`null`	Player-facing world name
`Seed`	`long`	`currentTimeMillis()`	World generation seed
`GameMode`	`GameMode`	server default	Default game mode for the world
`GameplayConfig`	`String`	`"Default"`	Name of the GameplayConfig asset to use

Gameplay Toggles

Field	Type	Default	Description
`IsPvpEnabled`	`boolean`	`false`	Whether PvP damage is allowed
`IsFallDamageEnabled`	`boolean`	`true`	Whether fall damage applies
`IsSpawningNPC`	`boolean`	`true`	Whether NPCs can spawn
`IsSpawnMarkersEnabled`	`boolean`	`true`	Whether spawn markers are active
`IsAllNPCFrozen`	`boolean`	`false`	Whether all NPCs are frozen

Ticking & Time

Field	Type	Default	Description
`IsTicking`	`boolean`	`true`	Whether chunks tick
`IsBlockTicking`	`boolean`	`true`	Whether blocks tick
`IsGameTimePaused`	`boolean`	`false`	Whether day/night cycle is paused
`GameTime`	`Instant`	5:30 AM	Current in-game time of day
`ForcedWeather`	`String`	`null`	Force a specific weather type (validated against Weather assets)

See World Time for the time system.

Saving & Storage

Field	Type	Default	Description
`IsSavingPlayers`	`boolean`	`true`	Whether player data is saved
`IsSavingChunks`	`boolean`	`true`	Whether chunk data is saved to disk
`SaveNewChunks`	`boolean`	`true`	Whether newly generated chunks are marked for saving
`IsUnloadingChunks`	`boolean`	`true`	Whether chunks can unload
`DeleteOnUniverseStart`	`boolean`	`false`	Delete world on universe load
`DeleteOnRemove`	`boolean`	`false`	Delete world files when removed from server

See Chunk Saving for the save system.

Chunk Config

Nested under ChunkConfig:

Field	Type	Default	Description
`PregenerateRegion`	`Box2D`	`null`	Region to pregenerate on world start
`KeepLoadedRegion`	`Box2D`	`null`	Region of chunks that never unload

Client Effects

Nested under ClientEffects. These affect rendering on the client:

Field	Type	Default	Description
`SunHeightPercent`	`float`	`100.0`	Sun height percentage
`SunAngleDegrees`	`float`	`0.0`	Sun angle in degrees
`BloomIntensity`	`float`	`0.3`	Post-processing bloom intensity
`BloomPower`	`float`	`8.0`	Post-processing bloom power
`SunIntensity`	`float`	`0.25`	Sun light intensity
`SunshaftIntensity`	`float`	`0.3`	Sunshaft/god-ray intensity
`SunshaftScaleFactor`	`float`	`4.0`	Sunshaft scale

ClientEffectWorldSettings effects = config.getClientEffects();
effects.setSunHeightPercent(80.0f);
effects.setBloomIntensity(0.5f);

Other

Field	Type	Default	Description
`SpawnProvider`	`ISpawnProvider`	`null` (worldgen default)	Controls where new players spawn
`IsCompassUpdating`	`boolean`	`true`	Whether compass updates
`IsObjectiveMarkersEnabled`	`boolean`	`true`	Whether objective markers are visible
`RequiredPlugins`	`Map`	empty	Mods required for this world

Per-World Overrides

Three GameplayConfig values can be overridden directly on WorldConfig. When set, they take precedence over the GameplayConfig asset:

Override Field	Overrides
`Death`	DeathConfig — inline death config
`DaytimeDurationSeconds`	Day/night duration
`NighttimeDurationSeconds`	Day/night duration

// the World class resolves overrides automatically
DeathConfig deathConfig = world.getDeathConfig();        // checks WorldConfig override first
int daytime = world.getDaytimeDurationSeconds();         // checks WorldConfig override first

GameplayConfig

Asset-based configuration loaded from JSON. A world references a GameplayConfig by name (defaults to "Default"). Multiple worlds can share the same GameplayConfig.

GameplayConfig gameplay = world.getGameplayConfig();

GameplayConfig contains multiple sub-configs, each controlling a different system.

Death

Controls item loss on death and respawn behavior. See Death for the full death flow.

DeathConfig deathConfig = world.getDeathConfig();

Field	Default	Description
`RespawnController`	`HomeOrSpawnPoint`	Where to respawn (see below)
`ItemsLossMode`	`NONE`	`NONE` = keep all items, `ALL` = drop everything, `CONFIGURED` = use percentages below
`ItemsAmountLossPercentage`	`10.0`	% of stackable item quantity lost (when mode is `CONFIGURED`)
`ItemsDurabilityLossPercentage`	`10.0`	% of durability lost from all items on death

Respawn controllers determine where the player teleports on respawn:

Type	Behavior
`HomeOrSpawnPoint` (default)	Teleports to nearest valid respawn point (bed/campfire), or world spawn if none set
`WorldSpawnPoint`	Always teleports to world spawn
`ExitInstance`	Exits the current instance (falls back to `HomeOrSpawnPoint` on failure)

Respawn Points

Controls respawn point limits (beds, campfires, etc.):

Field	Default	Description
`RadiusLimitRespawnPoint`	`500`	Max block radius for respawn points
`MaxRespawnPointsPerPlayer`	`3`	Max respawn points per player

Combat

Field	Default	Description
`OutOfCombatDelaySeconds`	`5.0`	Seconds before entity is considered “out of combat”
`StaminaBrokenEffectId`	`"Stamina_Broken"`	Effect applied when stamina depleted
`DisplayHealthBars`	`true`	Show health bars above entities
`DisplayCombatText`	`true`	Show combat text (damage numbers)
`DisableNPCIncomingDamage`	`false`	Make all NPCs invulnerable
`DisablePlayerIncomingDamage`	`false`	Make all players invulnerable

Player

Field	Default	Description
`MovementConfig`	`"BuiltinDefault"`	Movement config preset ID
`HitboxCollisionConfig`	`null`	Hitbox collision config ID
`RepulsionConfig`	`null`	Repulsion config ID
`MaxDeployableEntities`	`-1` (unlimited)	Max simultaneous deployable entities per player
`ArmorVisibilityOption`	`ALL`	Which armor pieces can be hidden (`ALL`, `HELMET_ONLY`, `NONE`)

World Settings

Field	Default	Description
`AllowBlockBreaking`	`true`	Whether blocks can be broken (checked before BreakBlockEvent)
`AllowBlockGathering`	`true`	Whether blocks can be gathered
`AllowBlockPlacement`	`true`	Whether blocks can be placed (checked before PlaceBlockEvent)
`BlockPlacementFragilityTimer`	`0.0`	Seconds after placement during which blocks are instantly breakable
`DaytimeDurationSeconds`	`1728`	Real-world seconds for daytime
`NighttimeDurationSeconds`	`1728`	Real-world seconds for nighttime
`TotalMoonPhases`	`5`	Number of moon phases

Sleep

Nested under World.Sleep:

Field	Default	Description
`WakeUpHour`	`5.5` (5:30 AM)	In-game hour players wake up at
`AllowedSleepHoursRange`	`null` (unrestricted)	In-game hour range during which sleep is allowed

Crafting

Field	Default	Description
`BenchMaterialChestHorizontalSearchRadius`	`14`	Horizontal radius to find chests near a crafting bench
`BenchMaterialChestVerticalSearchRadius`	`6`	Vertical radius to find chests near a crafting bench
`BenchMaterialChestLimit`	`100`	Max chests a bench draws materials from

Items

Item Durability

Nested under ItemDurability.BrokenPenalties:

Field	Default	Description
`Tool`	`null`	Penalty multiplier for broken tools
`Armor`	`null`	Penalty multiplier for broken armor
`Weapon`	`null`	Penalty multiplier for broken weapons

Item Entities (Drops)

Nested under ItemEntity:

Field	Default	Description
`PickupRadius`	`1.75`	Radius at which items are picked up
`Lifetime`	`null` (no expiry)	Time in seconds before dropped items despawn
`ShowItemParticles`	`true`	Whether to show particles on dropped items
`ParticleSystemId`	`"Item"`	Particle system for item entities

World Map

Controls what appears on the player’s world map:

Field	Default	Description
`DisplaySpawn`	`true`	Show spawn point
`DisplayHome`	`true`	Show home location
`DisplayWarps`	`true`	Show warp points
`DisplayDeathMarker`	`true`	Show death location
`DisplayPlayers`	`true`	Show other players

Camera Effects

Field	Default	Description
`DamageEffects`	`null`	Map of DamageCause ID to CameraEffect ID

Spawning

Field	Default	Description
`FirstSpawnParticles`	`null`	Particles shown on a player’s first spawn in the world
`SpawnParticles`	`null`	Particles shown on subsequent spawns
`MaxEnvironmentalNPCSpawns`	`500`	Max environmental NPC spawns in the world

Gathering

Controls effects when gathering blocks incorrectly:

Field	Default	Description
`UnbreakableBlock.ParticleSystemId`	—	Particle when hitting unbreakable blocks
`UnbreakableBlock.SoundEventId`	—	Sound when hitting unbreakable blocks
`IncorrectTool.ParticleSystemId`	—	Particle when using wrong tool
`IncorrectTool.SoundEventId`	—	Sound when using wrong tool

Other

Field	Default	Description
`ShowItemPickupNotifications`	`true`	Show item pickup notifications
`CreativePlaySoundSet`	`null`	Sound set used in creative mode

Plugin Extensions

Both WorldConfig and GameplayConfig have a Plugin codec map that allows mods to register their own sub-configs via the Codec Registry. Built-in mods use this for stamina tuning, portal settings, reputation, stash systems, and more.

// register a custom gameplay config type in setup()
getCodecRegistry(GameplayConfig.PLUGIN_CODEC)
    .register(Priority.NORMAL, "MyModConfig", MyModConfig.class, MyModConfig.CODEC);

This allows your settings to appear in the GameplayConfig JSON:

{
  "Plugin": {
    "MyModConfig": {
      "MySetting": 42
    }
  }
}