BetterStructures Configuration

This page is the reference for the two plugin-level configuration files BetterStructures writes into plugins/BetterStructures. Content-level configuration lives elsewhere: see Creating Generators, Creating Structures, Creating Treasure and Modular Dungeons.

Both files are re-read on the server thread whenever you run /bs reload, so you do not need a restart to apply a change here.

Folder layout

Path	Contents
config.yml	Plugin-wide settings, documented below
ValidWorlds.yml	Per-world on/off switches, documented below
schematics/	Structure .schem files and their generated .yml configs, scanned recursively
modules/	Modular dungeon .schem files and their generated .yml configs, scanned recursively
generators/	Generator configs
module_generators/	Module generator configs
treasures/	Treasure (loot table) configs
spawn_pools/	Spawn pool configs used by [pool: name] signs
content_packages/	Package descriptors used by the setup menu and download commands
components/	Created empty on startup, for content that ships supporting components
imports/	Drop-in folder for manual content imports
.schematic_cache/	Managed cache of converted schematics, safe to delete

---

config.yml

Structure spacing

BetterStructures places structures on a seeded diamond grid, one grid per structure type. The distance keys set how far apart the grid points are, and the offset keys jitter each point off the grid so placements do not look mechanical.

Both are measured in chunks, not blocks. A distanceSurface of 27 means roughly one surface structure every 27 chunks (about 432 blocks).

Key	Default	Description
distanceSurface	27	Grid spacing for SURFACE structures
distanceShallow	22	Grid spacing for UNDERGROUND_SHALLOW structures
distanceDeep	22	Grid spacing for UNDERGROUND_DEEP structures
distanceSky	90	Grid spacing for SKY structures
distanceLiquid	60	Grid spacing for LIQUID_SURFACE structures
distanceDungeonV2	80	Grid spacing for DUNGEON placements
maxOffsetSurface	5	Random jitter applied to surface grid points
maxOffsetShallow	5	Random jitter applied to shallow underground grid points
maxOffsetDeep	5	Random jitter applied to deep underground grid points
maxOffsetSky	5	Random jitter applied to sky grid points
maxOffsetLiquid	5	Random jitter applied to liquid surface grid points
maxOffsetDungeonV2	18	Random jitter applied to dungeon grid points

Smaller distances mean more structures. Smaller offsets mean more grid-like placement; larger offsets mean less predictable placement.

Validation. Distances must be at least 1. Offsets must be between 0 and 1073741823, the largest value the placement randomiser can safely use. A value outside its range makes BetterStructures log a warning, write that key's default back into config.yml, and carry on with the default rather than failing generation.

The offsets are derived from the world seed and the structure type name, so the same seed produces the same layout on every restart.

Spawn protection

Key	Default	Description
spawnProtectionRadius	100	Minimum distance in blocks from coordinates 0, 0 within which no structures are placed. Applies to every world. Set to 0 to disable.

Note that this is measured from the world origin, not from each world's spawn point.

Altitude bounds

These clamp where underground structures may end up, per dimension. A structure whose anchor would fall outside the range is pulled back inside it.

Key	Default	Description
lowestYNormalCustom	-60	Lowest Y for NORMAL and CUSTOM worlds
highestYNormalCustom	320	Highest Y for NORMAL and CUSTOM worlds
lowestYNether	4	Lowest Y in the Nether
highestYNether	120	Highest Y in the Nether
lowestYEnd	0	Lowest Y in the End
highestYEnd	320	Highest Y in the End

Sky structures use their own settings, and these are offsets above the highest block in the column, not absolute Y levels. A random value between the min and max is rolled for every placement.

Key	Default	Description
normalCustomAirBuildingMinAltitude	80	Lowest sky offset in NORMAL and CUSTOM worlds
normalCustomAirBuildingMaxAltitude	120	Highest sky offset in NORMAL and CUSTOM worlds
endAirBuildMinAltitude	80	Lowest sky offset in the End
endAirBuildMaxAltitude	120	Highest sky offset in the End

The Nether ignores all four: sky structures there are placed inside an air pocket found by scanning between Y 45 and Y 100.

Performance

Key	Default	Description
percentageOfTickUsedForPasting	0.2	Share of each server tick BetterStructures may spend pasting blocks, from 0.01 (1%) to 1 (100%). Lower values reduce lag but make builds pop in more visibly.
percentageOfTickUsedForPregeneration	0.1	Share of each server tick used by /bs pregenerate, same 0.01 to 1 range
pregenerationTPSPauseThreshold	12.0	Pregeneration pauses when server TPS falls below this
pregenerationTPSResumeThreshold	14.0	Pregeneration resumes when TPS is at or above this. Keep it higher than the pause threshold to avoid rapid pause/resume cycling.
modularChunkPastingSpeed	10	Currently unused. The key is still written into config.yml, but nothing reads it, so changing it has no effect.

Admin and integration

Key	Default	Description
warnAdminsAboutNewBuildings	true	Whether online players with betterstructures.warn (OPs by default) get a clickable teleport message when a structure finishes pasting or a modular dungeon starts generating, anywhere on the server. /bs silent flips this value and saves it.
setupDone	false	Whether the first-time setup flow has been completed. Set to false and reload to make /bs initialize prompt again.
protectEliteMobsRegions	true	Whether BetterStructures creates WorldGuard protection for EliteMobs-backed combat areas. Requires both WorldGuard and EliteMobs.
regionProtectedMessage	&8[BetterStructures] &cDefeat the zone's bosses to edit blocks!	Message shown when a player tries to edit blocks inside one of those protected regions
nightbreak.autoDownloadPluginUpdates	false	Whether plugin and content updates download automatically on startup. This is the key behind the Automatic Updates toggle in /bs setup. Downloaded content and plugin updates are used after the next restart, unless nightbreak.applyPluginUpdatesWithoutRestart applies the plugin update sooner.
nightbreak.applyPluginUpdatesWithoutRestart	never	When a downloaded plugin update is applied. never waits for the next restart. when-empty applies it the next time no players are online, checking every 30 seconds. immediately applies it as soon as it is downloaded. Any other value counts as never. Applying an update reloads BetterStructures and the MagmaGuy plugins that depend on it, so bosses, arenas and dungeon instances in progress end. A plugin from another author that depends on BetterStructures blocks the swap. /bs applypluginupdate applies a staged update on demand.

---

ValidWorlds.yml

This file decides which worlds BetterStructures generates in.

New worlds spawn structures: true
Valid worlds v2:
  world: true
  world_nether: true
  world_the_end: true

Key	Default	Description
New worlds spawn structures	true	Whether a world BetterStructures has not seen before is registered as enabled
Valid worlds v2	populated automatically	One worldname: true/false entry per world. Set a world to false to stop all structure generation in it.

On upgrade, a ValidWorlds.yml containing the old Valid worlds key is moved intact to plugins/MagmaCore/outdated files/BetterStructures/<archive batch>/ValidWorlds.yml. BetterStructures generates a replacement using the current world defaults. Review your previous choices in the archive and reapply the ones you want under Valid worlds v2, then run /bs reload. Do not copy the old file back unchanged, because it still matches the retired format.

Automatic behaviour

• New worlds are registered on load. A world loading for the first time gets an entry written immediately, using New worlds spawn structures as its value.
• EliteMobs-managed worlds are excluded. The adventurers guild hub and instanced dungeon copies are registered as false even when New worlds spawn structures is true, because their unbuilt void chunks count as new chunks and had BetterStructures decorating dungeon hubs. The entry is still written, so setting it back to true works if that is genuinely what you want.
• Current-format choices are preserved. BetterStructures does not infer ownership from an em_ name or rewrite an existing Valid worlds v2 toggle. It uses EliteMobs' world registry for new-world defaults. An explicitly enabled EliteMobs world stays enabled and produces a warning so you can decide whether to change it. Legacy Valid worlds files follow the archive-and-regenerate process above.
• Dead entries are pruned. On startup, and roughly ten seconds after a world unloads, entries whose world is neither loaded nor present on disk are removed so the file does not grow indefinitely.