Creating Generators

Generators

Generators are the most powerful part of the configuration system for BetterStructures. By default there are 29 generators which collectively manage the builds currently distributed by BetterStructures, and while you can create your own generators, you can also use existing ones as a shortcut.

Generators tell the plugin where exactly things should spawn and define loot tables. The default generators are also named in ways that should be very easy to guess what they do.

Generator Configuration Options

Key	Default	Mandatory	Description
isEnabled	true	❌	Whether the generator is enabled. Setting it to false also stops every schematic pointing at this generator from being registered, so it is the quickest way to switch a whole set of structures off.
structureType	-	✅	Where structures spawn (see table below)
lowestYLevel	-59	❌	Minimum Y level for spawning
highestYLevel	320	❌	Maximum Y level for spawning
validWorlds	All allowed	❌	List of worlds where structures can spawn
validWorldEnvironments	All allowed	❌	NORMAL, NETHER, THE_END, CUSTOM
validBiomesV2	All biomes	❌	List of valid biomes (namespace:key format)
treasureFilename	-	❌	Treasure file for chest loot
generateLootInBarrels	true	❌	Whether barrels found in this generator's schematics should be filled with loot
barrelTreasureFilename	treasure_barrel_food.yml	❌	Treasure file used to fill barrels for this generator

---

structureType

Sets what kind of structure the build is. You can specify multiple structure types for a single generator!

Type	Overworld / Custom	Nether	End	Description
SURFACE	Surface	Surface-like points	Surface	Spawns at the surface of the world
SKY	80-120 blocks above the highest block	Air pocket found between Y 45 and Y 100	80-120 blocks above the highest block	Spawns in the sky (configurable in config.yml)
UNDERGROUND_SHALLOW	Y 0-50	Y 60-120	Y 0-80	Shallow underground structures
UNDERGROUND_DEEP	Y -53 to 0	Y 5-60	Y 0-80	Deep underground structures
LIQUID_SURFACE	Water (oceans)	Lava ocean at Y 31	No liquid check is applied	Spawns on liquid surfaces
DUNGEON	✅	✅	✅	Used for modular dungeon placement

The sky ranges are offsets applied above the world's highest block at that column, not absolute Y levels.

Multiple Structure Types Example

structureType:
- SURFACE
- UNDERGROUND_SHALLOW

This allows the same generator to spawn structures in multiple locations, such as both on the surface and in shallow underground areas.

Note: There are two underground settings because Minecraft has a lot of underground space. Having both ensures even distribution across depths and prevents players from missing structures.

---

Y-Level Ranges by Dimension

Default altitude ranges per dimension (configurable in config.yml):

Dimension	Default Range	Config Settings
Overworld/Custom	Y=-60 to Y=320	lowestYNormalCustom / highestYNormalCustom
Nether	Y=4 to Y=120	lowestYNether / highestYNether
End	Y=0 to Y=320	lowestYEnd / highestYEnd
Sky (Overworld/Custom)	80 to 120 blocks above the highest block	normalCustomAirBuildingMinAltitude / normalCustomAirBuildingMaxAltitude
Sky (End)	80 to 120 blocks above the highest block	endAirBuildMinAltitude / endAirBuildMaxAltitude

These defaults can be overridden per-generator using lowestYLevel and highestYLevel.

The two sky rows are offsets added on top of the highest block in the column, not absolute Y levels. Both the Overworld/Custom and End sky offsets are rolled at random between their min and max on every placement.

The Nether ignores those offsets entirely: instead of building above the highest block, BetterStructures scans the column between Y 45 and Y 100 for an air pocket at least 20 blocks tall and places the structure inside it. If no such pocket exists, nothing spawns in that chunk.

---

Custom Biome Support

BetterStructures automatically supports custom biomes from world generators like Terralith, Iris, Terra, and TerraformGenerator.

When you specify a vanilla biome in validBiomesV2, the plugin automatically includes compatible custom biomes:

validBiomesV2:
  - minecraft:plains
  - minecraft:forest

This spawns structures in the vanilla biomes AND all custom biomes mapped to these types (e.g., terralith:blooming_plains).

Where the mappings actually live

The custom-biome to vanilla-biome mapping table is not stored in BetterStructures. It is a single hardcoded table inside MagmaCore, the shared library bundled into BetterStructures, and is shared with the other MagmaGuy plugins that need it.

That has two practical consequences:

1. The long biome lists you see in the shipped generator_surface_*.yml files are generated output, not the source of truth. On load, BetterStructures reads validBiomesV2, looks up every minecraft: entry in the MagmaCore table, appends whatever custom biomes map to it, and then writes the expanded list straight back into the generator file. So a generator you wrote with two lines can come back with a hundred. Editing that expanded list only affects that one generator, and any minecraft: entry you leave in place will be re-expanded on the next load.
2. Adding support for a new custom biome for everyone is a MagmaCore change, not a config change. If a world generator ships a biome that BetterStructures does not recognise, adding it to a generator's validBiomesV2 is a local workaround for that one generator. Getting it mapped properly means getting it added to MagmaCore's mapping table, which is a code change — open a request rather than trying to solve it in the yml files.

You can still name a custom biome directly in validBiomesV2 (anything already containing a : is taken as-is and is not expanded further), which is the right move for a one-off generator that should only spawn in one specific custom biome.

Biomes that MagmaCore maps to nothing are deliberately excluded — they are custom biomes considered unsuitable for structures, and no vanilla biome will pull them in.

---

treasureFilename

Sets the treasure file for chest loot. This applies to all builds using this generator, unless overridden in the schematic configuration.

---

generateLootInBarrels and barrelTreasureFilename

BetterStructures now treats barrels as a second loot container alongside chests.

• generateLootInBarrels (default true) toggles whether barrels inside structures placed by this generator get filled. Set it to false to leave barrels untouched.
• barrelTreasureFilename (default treasure_barrel_food.yml) selects which treasure file is rolled when filling those barrels. The default ships a lightweight food-focused loot table, but you can point it at any treasure file.

Both options can be overridden per-schematic with the matching barrelTreasureFilename field in the schematic config.