Structures

Structures are the large, hand-authored pieces of the world: villages, temples, strongholds, trial chambers. Unlike a feature, a structure can span many chunks and be assembled from separate building blocks, and it starts generating during structures_starts, before the terrain itself, which is why terrain can adapt around it instead of cutting through it.

Four file types work together, from the smallest to the largest scale:

A structure made of a single fixed shape only needs the last two; a jigsaw structure like a village uses all four.

References: Structure, Structure definition

Processor List

Processors transform the blocks of a structure template as it is stamped into the world: aging bricks, randomizing block types, dropping the structure onto the terrain. They run in declaration order, each one taking the output of the previous.

val processors = dp.processorList("my_processors") {
	blockIgnore(Blocks.STRUCTURE_BLOCK, Blocks.JIGSAW)
	blockAge(0.5)
	gravity(HeightMap.WORLD_SURFACE_WG)
}

{
	"processors": [
		{
			"processor_type": "minecraft:block_ignore",
			"blocks": [
				{ "Name": "minecraft:structure_block" },
				{ "Name": "minecraft:jigsaw" }
			]
		},
		{ "processor_type": "minecraft:block_age", "mossiness": 0.5 },
		{ "processor_type": "minecraft:gravity", "heightmap": "WORLD_SURFACE_WG", "offset": 0 }
	]
}

Every processor is a function scoped to the processorList { } block.

limit accepts a plain Int or any int provider, and the delegate cannot be another capped processor:

processorList("capped_aging") {
	capped(uniform(1, 4)) {
		blockAge(0.8)
	}
}

Reference: Processor list

Rules

A rule replaces a template block by outputState when its three predicates pass, and the first matching rule wins.

processorList("mossify") {
	rules {
		rule {
			inputPredicate = blockMatch(Blocks.STONE_BRICKS)
			locationPredicate = tagMatch(Tags.Block.DIRT)
			outputState = blockState(Blocks.MOSSY_STONE_BRICKS)
		}

		rule {
			positionPredicate = axisAlignedLinearPos(Axis.Y) {
				minDist = 0
				maxDist = 4
				minChance = 1.0
				maxChance = 0.0
			}

			inputPredicate = randomBlockStateMatch(blockState(Blocks.STONE), 0.5)
			outputState = blockState(Blocks.CRACKED_STONE_BRICKS)
			blockEntityModifier = appendLoot(LootTables.Chests.SIMPLE_DUNGEON)
		}
	}
}

Position predicates, scoped to rule { }:

Block entity modifiers, also scoped to rule { }:

Rule tests, used by inputPredicate and locationPredicate. These are the shared worldgen ones from io.github.ayfri.kore.features.worldgen.ruletest, also available in the target { } block of the ore-like features:

Template Pool

A template pool is a weighted bag of pieces the jigsaw system may pick from. Pieces connect through jigsaw blocks: each one names the pool it wants next, so a village street pool can point at a house pool that points back at the street pool, and the structure grows until it hits its size budget.

val pool = dp.templatePool("my_pool") {
	fallback = TemplatePools.Empty

	single(Structures.Village.Plains.TownCenters.PLAINS_FOUNTAIN_01, ProcessorLists.EMPTY, weight = 3)
	feature(PlacedFeatures.PILE_HAY, weight = 1)
	empty(weight = 2)
}

fallback is the pool used when a piece cannot connect any further - usually TemplatePools.Empty, which is also the default.

Every builder takes weight (1 to 150, default 1) and projection (Projection.RIGID keeps the original shape, TERRAIN_MATCHING adapts it to the terrain height; default RIGID). processors defaults to ProcessorLists.EMPTY. A trailing block reaches the remaining fields, such as overrideLiquidSettings on single and legacySingle.

dp.templatePool("houses") {
	single(Structures.Village.Plains.Houses.PLAINS_SMALL_HOUSE_1, weight = 4) {
		projection = Projection.TERRAIN_MATCHING
		overrideLiquidSettings = LiquidSettings.IGNORE_WATERLOGGING
	}

	list(weight = 1) {
		single(Structures.Village.Plains.Houses.PLAINS_SMALL_HOUSE_2, ProcessorLists.MOSSIFY_10_PERCENT)
		feature(PlacedFeatures.PILE_HAY)
	}
}

Elements inside a list are unweighted: the weight belongs to the list entry itself.

Reference: Template pool

Configured Structure

A configured structure picks the generation algorithm and says where it is allowed to appear. Each type is a function on the structures { } scope, taking the file name first and everything else in a trailing block, so one call writes one file:

dp.structures {
	desertPyramid("my_pyramid") {
		biomes(Biomes.DESERT, Biomes.BADLANDS)
		terrainAdaptation = TerrainAdaptation.BEARD_BOX

		spawnOverrides {
			monster(BoundingBox.FULL) {
				spawner(EntityTypes.HUSK, weight = 1, minCount = 4, maxCount = 4)
			}
		}
	}
}

dp.structuresBuilder.desertPyramid(...) writes the same file outside a structures { } block, and dp.structure(fileName, type) takes an already built type, for the rare case where the generator itself needs tweaking, such as overriding its namespace.

Shared Fields

Every type defaults step to the step its vanilla counterpart uses, so it only needs setting when a structure should generate at another point of the world generation.

spawnOverrides takes one block per mob category (ambient, axolotls, creature, misc, monster, undergroundWaterCreature, waterAmbient, waterCreature), each with a BoundingBox: FULL applies to the whole structure, PIECE to the individual piece and is the default. A category left out keeps the biome spawns, while a category declared with an empty block stops it from spawning inside the structure entirely:

spawnOverrides {
	// No monster ever spawns inside the mansion, whatever the biome says.
	monster(BoundingBox.PIECE)

	// Guardians spawn anywhere inside the monument, on top of the biome spawns being dropped.
	waterCreature(BoundingBox.FULL) {
		spawner(EntityTypes.GUARDIAN, weight = 20, minCount = 2, maxCount = 4)
	}
}

Structure Types

Only jigsaw builds its shape from data; every other type runs a hardcoded algorithm and only exposes the knobs listed above.

structures {
	mineshaft("badlands_mineshaft") {
		biomes(Tags.Worldgen.Biome.IS_BADLANDS)
		mineshaftType = MineshaftType.MESA
	}

	netherFossil("deep_fossil") {
		biomes(Biomes.SOUL_SAND_VALLEY)
		height = uniformHeightProvider(aboveBottom(32), belowTop(2))
	}

	ruinedPortal("my_ruined_portal") {
		biomes(Biomes.DESERT)
		setup(RuinedPortalPlacement.PARTLY_BURIED, mossiness = 0.0f, weight = 1f)
		setup(RuinedPortalPlacement.ON_LAND_SURFACE, overgrown = true, vines = true, weight = 0.5f)
	}

	oceanRuin("my_ocean_ruin") {
		biomes(Biomes.WARM_OCEAN)
		biomeTemp = BiomeTemperature.WARM
		largeProbability = 0.4f
		clusterProbability = 0.8f
	}
}

A ruinedPortal needs at least one setup: it is the weighted list one variant is drawn from per instance, and vanilla rejects the structure when it is empty.

Jigsaw

structures {
	jigsaw("my_village", startPool = villageStart) {
		biomes(Biomes.PLAINS)
		terrainAdaptation = TerrainAdaptation.BEARD_THIN
		size = 6
		startHeight = constantAbsolute(0)
		projectStartToHeightmap = HeightMap.WORLD_SURFACE_WG
		maxDistanceFromCenter(80)
	}
}

dimensionPadding(value) and maxDistanceFromCenter(value) are functions, taking one value for both directions or two for each. Given one value, they write a bare number instead of an object.

Pool Aliases

Pool aliases rewire which pool an alias resolves to, per structure instance. That is how a single jigsaw structure can produce differently themed variants without duplicating every pool.

poolAliases {
	// Always resolve this alias to that pool.
	directPoolAlias(TemplatePools.Empty, housesPool)

	// Draw the target from a weighted list, per instance.
	randomPoolAlias(TemplatePools.Empty) {
		weightedPoolEntry(1, desertHouses)
		weightedPoolEntry(2, plainsHouses)
	}

	// Draw a whole group of aliases at once, keeping a variant coherent.
	randomGroupPoolAlias {
		weightedGroupEntry(1) {
			directPoolAlias(TemplatePools.Empty, desertHouses)
			directPoolAlias(TemplatePools.Empty, desertStreets)
		}
	}
}

Structure Set

A structure set decides how instances spread over the world. Several structures can share a set, in which case the weights make them mutually exclusive: only one generates per grid cell.

val villages = dp.structureSet("custom_villages") {
	structure(ConfiguredStructures.VILLAGE_PLAINS, weight = 3)
	structure(ConfiguredStructures.VILLAGE_DESERT, weight = 1)

	randomSpreadPlacement(spacing = 34, separation = 8) {
		salt = 10387312
		spreadType = SpreadType.LINEAR
	}
}

Every configured structure builder returns a ConfiguredStructureArgument, which is exactly what structure() takes, so a set mixes your own structures and the vanilla ones from the generated ConfiguredStructures object:

val myPyramid = dp.structuresBuilder.desertPyramid("my_pyramid") {
	biomes(Biomes.DESERT)
}

dp.structureSet("my_pyramids") {
	structure(myPyramid, weight = 2)
	randomSpreadPlacement(spacing = 32, separation = 8)
}

Placement

Two placement types exist, and a set has exactly one. Without a call to either, it uses an empty random spread.

randomSpreadPlacement(spreadType, spacing, separation) is the common one. The world is cut into a grid of spacing chunks; each cell gets at most one structure, placed at random inside it, never closer than separation chunks to the cell edge. separation must stay below spacing, and the closer the two, the more regular the layout. SpreadType.LINEAR picks the position uniformly, TRIANGULAR biases it towards the cell center.

concentricRingsPlacement(distance, spread, count) places structures in rings around the world origin, the way strongholds do: distance chunks to the first ring, spread chunks of jitter, count structures in total. preferredBiomes(...) restricts where within a ring a structure may land.

Both share these fields, set inside the trailing block:

dp.structureSet("my_strongholds") {
	structure(ConfiguredStructures.STRONGHOLD)

	concentricRingsPlacement(distance = 32, spread = 3, count = 128) {
		preferredBiomes(Biomes.PLAINS, Biomes.FOREST)
		exclusionZone(villages, chunkCount = 5)
	}
}

Reference: Structure set

See Also

• Biomes - the biomes a structure restricts itself to
• Features - the smaller decorations placed alongside structures
• Providers - height and int providers used by jigsaw and processors
• Tags - grouping processor lists, template pools and structures
• World Generation - overview of the worldgen system