Providers

Most worldgen fields do not take a plain number: they take a provider, a small object the game samples at every position. That is how one ore configuration can produce veins of varying size, or one carver can dig tunnels at varying heights.

Four families exist, and they show up across carvers, features, structures and surface rules:

Vertical anchors - a single Y level, expressed absolutely or relative to the world bounds.
Height providers - a distribution of vertical anchors.
Int providers - a distribution of integers, for counts and sizes.
Float providers - a distribution of floats, for radii, chances and scales.

Every builder is scoped: it only resolves inside a block actually accepting that kind of value, so nothing pollutes the global completion list.

Vertical Anchors

A vertical anchor is one Y level. It serializes as a one-key object, and the resolved Y is always clamped to the build height of the dimension.

Builder	JSON	Meaning
`absolute(y)`	`{"absolute": y}`	Absolute Y coordinate, the one shown on the F3 screen.
`aboveBottom(n)`	`{"above_bottom": n}`	`n` blocks above the bottom of the dimension, `0` being `min_y`.
`belowTop(n)`	`{"below_top": n}`	`n` blocks below the top of the dimension, larger values go down.

The builders extend VerticalAnchorScope, so they resolve inside a placed feature, a carver configuration, a surfaceRules { } block, and anywhere a height provider is being built.

Reference: Vertical anchor

Height Providers

A height provider picks a Y level between two anchors, following a distribution. It is what heightRange() on a placed feature, y on a carver and startHeight on a jigsaw structure take.

Builder	Behavior
`constantHeightProvider(anchor)`	Always the given anchor. Serializes as the bare anchor, with no wrapper.
`constantAbsolute(y)` / `constantAboveBottom(n)` / `constantBelowTop(n)`	Shorthands for `constantHeightProvider` on each anchor form.
`uniformHeightProvider(min, max)`	Equal chance at every level between both bounds, included.
`trapezoidHeightProvider(min, max, plateau)`	Flat top of `plateau` blocks in the middle, linear falloff on both sides.
`biasedToBottomHeightProvider(min, max, inner)`	Uniform over the `inner` bottom blocks, exponential falloff above them.
`veryBiasedToBottomHeightProvider(min, max, inner)`	Same shape with a sharper falloff, the vanilla diamond pattern.
`weightedListHeightProvider { }`	Picks one of the nested providers, by weight.

Every builder except weightedListHeightProvider also takes plain Int bounds, read as absolute Y coordinates. They extend HeightProviderScope, which itself extends VerticalAnchorScope, so anchors are available in the same block.

heightRange(uniformHeightProvider(minInclusive = 0, maxInclusive = 64))
heightRange(trapezoidHeightProvider(minInclusive = 0, maxInclusive = 64, plateau = 20))
heightRange(constantAbsolute(32))
heightRange(constantHeightProvider(belowTop(16)))
heightRange(veryBiasedToBottomHeightProvider(aboveBottom(8), absolute(16)))

heightRange(weightedListHeightProvider {
	entry(3, constantAbsolute(32))
	entry(1, uniformHeightProvider(aboveBottom(0), absolute(16)))
})

Reference: Height provider

Int Providers

Int providers fill every field expecting a variable count or size: count() and countOnEveryLayer() on placed features, the limit of a capped processor, the layer heights of a blockColumn, and so on.

Builder	Behavior
`constant(value)`	Always returns `value`. Serializes as a plain integer, no wrapper object.
`uniform(minInclusive, maxInclusive)`	Uniform random integer in `[min, max]`.
`biasedToBottom(minInclusive, maxInclusive)`	Random integer in `[min, max]`, weighted towards the minimum.
`trapezoid(min, max, plateau)`	Trapezoid distribution over `[min, max]` with a flat top of width `plateau`.
`clampedNormal(minInclusive, maxInclusive, mean, dev)`	Samples a normal distribution (`mean`/`dev`) and clamps the result to `[min, max]`.
`clamped(minInclusive, maxInclusive, source)`	Evaluates `source` and clamps its result to `[min, max]`.
`weightedList { }`	Randomly selects one entry from a weighted pool.

count(constant(10))
count(biasedToBottom(3, 8))
count(clampedNormal(1, 10, mean = 5.0f, deviation = 2.0f))

// Reroll uniform(0, 20), but never below 4 or above 12.
count(clamped(4, 12, uniform(0, 20)))

// 70% chance of 1, 30% chance of 3.
count(weightedList {
	add(weightedEntry(7, constant(1)))
	add(weightedEntry(3, constant(3)))
})

Float Providers

Float providers fill float fields such as yScale and floorLevel on carvers, radius on foliage placers, heightScale and stalactiteBluntness on features, and volume or pitch on enchantment effects.

Builder	Behavior
`constant(value)`	Always returns `value`. Serializes as a plain float, no wrapper object.
`uniform(minInclusive, maxExclusive)`	Uniform random float in `[min, max)`. `maxExclusive` cannot be less than `minInclusive`.
`trapezoid(min, max, plateau)`	Trapezoid distribution over `[min, max]` with a flat top of width `plateau`.
`clampedNormal(mean, deviation, min, max)`	Samples a normal distribution (`mean`/`deviation`) and clamps the result to `[min, max]`.

yScale = constant(1.5f)
pitch = uniform(0.8f, 1.2f)
floorLevel = clampedNormal(mean = 0.5f, deviation = 0.2f, min = 0.0f, max = 1.0f)
thickness = trapezoid(min = 0.0f, max = 2.0f, plateau = 0.5f)

constant, uniform, trapezoid and clampedNormal are named the same for ints and floats and are told apart by their argument types. When both imports are in scope and the call is ambiguous, use the *FloatProvider aliases: constantFloatProvider, uniformFloatProvider, trapezoidFloatProvider, clampedNormalFloatProvider.

linkProviders

linkVertical Anchors

linkHeight Providers

linkInt Providers

linkFloat Providers

linkSee Also

Providers

Vertical Anchors

Height Providers

Int Providers

Float Providers

See Also