Noise & Terrain

Noise, density functions and noise settings are the three layers that shape Minecraft terrain. They build on each other in that order:

1. Noise definitions (worldgen/noise) - raw Perlin noise, described by octaves and amplitudes.
2. Density functions (worldgen/density_function) - composable math nodes that sample noises and combine them into a density value for any 3D position.
3. Noise settings (worldgen/noise_settings) - the terrain configuration a dimension points at: world bounds, default blocks, the noise router wiring density functions to generation roles, and the surface rules painting the top layers.

Minecraft decides whether a position is solid from the density value the router's finalDensity produces: positive density is a block, negative density is air (or fluid, below sea level).

References: Noise, Density function, Noise settings

Noise Definitions

A noise definition configures one Perlin noise instance. Octaves layer noise samples at different scales - low octaves make large features (continents), high octaves add fine detail (small bumps).

firstOctave = -7 starts at the 2⁷ = 128 block scale. Each following octave doubles in frequency, and amplitudes weights each one, usually decreasing so detail never overwhelms the base shape.

val hills = dp.noise("hills") {
	firstOctave = -5
	amplitudes = listOf(1.0, 0.5, 0.25)
}

amplitudes(...) sets the weights inline instead of building the list:

val hills = dp.noise("hills") {
	firstOctave = -5
	amplitudes(1.0, 0.5, 0.25)
}

A file name holding slashes lands in subfolders, so noise("cave/entrance") writes data/<namespace>/worldgen/noise/cave/entrance.json.

Every call returns a NoiseArgument. Vanilla noises are available as Noises.AquiferBarrier, Noises.Continentalness and so on, and can be passed anywhere a NoiseArgument is expected.

Density Functions

Density functions are math nodes evaluated per position. Each one lives in its own file and holds exactly one node type, so composing them means referencing other density function files.

Declare them inside a densityFunctions { ... } block, one builder call per file:

dp.densityFunctions {
	val base = constant("base", 1.0)
	val hills = noise("hills", Noises.Continentalness, xzScale = 0.25, yScale = 0.0)

	abs("abs_hills", hills)
	add("terrain", base, hills)
}

Each call returns a DensityFunctionArgument usable as an input to another node, as a noise router field, or anywhere else a density function is expected. Vanilla nodes come from the generated DensityFunctions object, e.g. DensityFunctions.Overworld.BASE_3D_NOISE.

The block itself returns the builder scope, not the last node, so arguments you need later are captured in vals inside it. For a single node, or to return one node out of a group, dp.densityFunctionsBuilder exposes the same builders:

dp.densityFunctionsBuilder.abs("abs_base_3d_noise", DensityFunctions.Overworld.BASE_3D_NOISE)

val terrain = with(dp.densityFunctionsBuilder) {
	val gradient = yClampedGradient("gradient") { fromY = 0; toY = 128; fromValue = 1.0; toValue = -1.0 }
	add("terrain", DensityFunctions.Overworld.BASE_3D_NOISE, gradient)
}

Most builders accept either a Double or a DensityFunctionArgument for their inputs, in every combination. noise, shift, shiftA, shiftB and shiftedNoise take a NoiseArgument instead, since they sample a noise definition directly.

Density Function Types

All builders live in io.github.ayfri.kore.features.worldgen.densityfunction.types and take the file's name as their first argument.

beardifier, blend_alpha, blend_offset, blend_density and cache_all_in_cell are internal to vanilla generation and are not meant to be referenced from a datapack, even though the builders exist.

Multi-Parameter Nodes

Nodes with more than a couple of inputs take a builder block instead of a long positional list:

dp.densityFunctions {
	rangeChoice("caves") {
		input(DensityFunctions.Overworld.BASE_3D_NOISE)
		minInclusive = -0.3
		maxExclusive = 0.3
		whenInRange(-1.0)
		whenOutOfRange(1.0)
	}

	yClampedGradient("depth_bias") {
		fromY = -64
		toY = 320
		fromValue = 1.0
		toValue = -1.0
	}

	shiftedNoise("shifted_hills", Noises.Continentalness) {
		xzScale = 0.25
		yScale = 0.0
		shiftX(DensityFunctions.ShiftX)
		shiftZ(DensityFunctions.ShiftZ)
	}

	intervalSelect("cave_shape") {
		input(DensityFunctions.Overworld.BASE_3D_NOISE)
		thresholds(-0.3f, 0.3f)
		function(DensityFunctions.Nether.BASE_3D_NOISE)
		function(0.0)
		function(DensityFunctions.End.BASE_3D_NOISE)
	}

	findTopSurface("top_surface", DensityFunctions.Overworld.BASE_3D_NOISE, DensityFunctions.Y, lowerBound = -64, cellHeight = 8)
}

intervalSelect holds one more function than it has thresholds: the first function applies below the first threshold, each following one applies between two consecutive thresholds, and the last one applies at or above the last threshold. Thresholds must be sorted ascending.

Splines

A spline interpolates control points over a coordinate density function. Points hold either a constant value or a nested spline, which is how vanilla layers continentalness, erosion and ridges into a single terrain offset:

dp.densityFunctions {
	spline("offset", DensityFunctions.Overworld.CONTINENTS) {
		point(-1.1f, 0.044f)
		point(-0.51f, DensityFunctions.Overworld.EROSION, derivative = 0.5f) {
			point(-0.6f, 1.0f)
			point(0.5f, -1.0f)
		}
	}

	spline("flat", 0.5f)
}

Points are ordered by increasing location, and derivative sets the slope of the curve at that point.

Fields typed DensityFunctionOrDouble are set through their matching setter function (input(...), whenInRange(...), shiftX(...)), overloaded for both a Double and a DensityFunctionArgument. Assigning the field directly needs an explicit densityFunctionOrDouble(...) wrapper.

Noise Settings

Noise settings are the complete terrain configuration for a dimension. A dimension references one through its noise generator.

val terrain = dp.noiseSettings("custom_terrain") {
	seaLevel = 63
	aquifersEnabled = true
	oreVeinsEnabled = true

	noiseOptions(minY = -64, height = 384, sizeHorizontal = 1, sizeVertical = 2)

	defaultBlock(Blocks.STONE)
	defaultFluid(Blocks.WATER) { this["level"] = "0" }

	noiseRouter {
		finalDensity(DensityFunctions.Overworld.SLOPED_CHEESE)
	}

	surfaceRules {
		block(Blocks.STONE)
	}
}

Properties

Defaults below are Kore's, which are not always vanilla's - the Overworld for instance ships with aquifersEnabled and oreVeinsEnabled set to true.

Noise Options

noiseOptions(
	minY = -64,         // Lowest generated Y level, -2032 to 2031, multiple of 16
	height = 384,       // Total height, 0 to 4064, multiple of 16
	sizeHorizontal = 1, // Horizontal cell size, 1 to 4
	sizeVertical = 2    // Vertical cell size, 1 to 4
)

minY + height must stay within the dimension type's own vertical range, and larger size values mean coarser, cheaper terrain.

Default Blocks

defaultBlock(Blocks.DEEPSLATE)
defaultFluid(Blocks.LAVA) { this["level"] = "0" }

Both take an optional block-state property block, and both accept a plain Map<String, String> instead.

Noise Router

The noise router maps density functions to generation roles. Every field is a DensityFunctionOrDouble, so set it with the matching function, which is overloaded for both a Double and a DensityFunctionArgument:

noiseRouter {
	barrier(0.5)
	lava(DensityFunctions.End.BASE_3D_NOISE)
	finalDensity(myTerrainDensity)
}

Unset fields serialize as 0.0, which means flat, featureless terrain - so a hand-written router usually starts from the vanilla density functions in the generated DensityFunctions object.

Reference: Noise router

Surface Rules

Surface rules decide which blocks replace the top layers of terrain. They are evaluated in order, and the first rule producing a block wins.

surfaceRules {
	condition(biomes(Biomes.DESERT)) {
		block(Blocks.SAND)
	}

	condition(stoneDepth(Surface.FLOOR, addSurfaceDepth = true)) {
		condition(water(offset = -1, surfaceDepthMultiplier = 0)) {
			block(Blocks.GRASS_BLOCK)
		}
		block(Blocks.DIRT)
	}

	block(Blocks.STONE)
}

Every builder below lives on the surfaceRules scope, so nothing leaks into the global namespace and the IDE completes the whole rule set from inside the block.

A condition block holding a single rule serializes as that rule, several rules are wrapped in a sequence.

Conditions

Condition builders live on the surfaceRules scope too, so they resolve without extra imports inside the block.

noiseThreshold evaluates its noise in 2D (X/Z) by default. Set is3d = true to evaluate it in 3D instead:

condition(noiseThreshold(hills) {
	minThreshold = -0.5
	maxThreshold = 0.5
	is3d = true
}) {
	block(Blocks.GRANITE)
}

AbovePreliminarySurface, Hole, Steep and Temperature take no arguments, so they are passed directly as objects:

condition(AbovePreliminarySurface) {
	block(Blocks.GRASS_BLOCK)
}

condition(not(Steep)) {
	block(Blocks.GRAVEL)
}

The vertical anchors used by yAbove and verticalGradient are built with absolute(y), aboveBottom(offset) or belowTop(offset), all scoped to the surfaceRules { } block:

condition(verticalGradient("bedrock_floor", aboveBottom(0), aboveBottom(5))) {
	block(Blocks.BEDROCK)
}

Reference: Surface rule

Putting It Together

The worldgen overview walks through a noise, its density functions, the noise settings wiring them together, and the dimension pointing at the result.

See Also

• Biomes - the biomes a noise generator distributes over the terrain
• Carvers - the caves cut out of the terrain afterwards
• Dimensions - the dimension pointing at noise settings
• Providers - the vertical anchors used by surface rule conditions
• World Generation - overview of the worldgen system