Custom world generation

This feature is exclusive to Java Edition.

Custom world generation allows data packs to change how the world generate.

World Preset and Dimension[]

A world preset controls what dimensions a world has. Before 1.19 (22w11a), dimensions are defined in dimension folder rather than in world preset. Although in current version the world preset is recommended, the dimension folder is still supported.

World preset or dimension define what generator (noise, debug or superflat) is used in a dimension. If it is noise, they define what noise settings and biomes are used and how the biomes are placed.

Noise settings[]

Noise settings are for generating the shape of the terrain and noise caves, and what blocks the terrain is generated with, stored as JSON files within a data pack in the path data/<namespace>/worldgen/noise_settings, and are used with the minecraft:noise generator in a dimension. Vanilla settings include minecraft:overworld for normal Overworld generation, minecraft:amplified for Amplified Overworld generation, minecraft:nether for regular Nether generation, minecraft:caves for Cave (Nether-like generation but with Overworld terrain features) generation, minecraft:end for regular End generation, and minecraft:floating_islands for Floating Islands (similar to The End outer islands) generation.

During terrain generation, block position where the final density value is less than zero become air and will be filled by the aquifer, and the position where the value is greater than zero become the default block and will be filled with the surface rule.

When applying surface rule, minecraft:surface noise is used to calculate the thickness of the surface layer. noise_value_at_(X,0,Z) × 2.75 + 3.0 is calculated at each horizonal coordinates, and the surface layer thickness fluctuates from this value by ±0.25 affected by random numbers based on the coordinates. This minecraft:surface noise and actual surface layer are used in vanilla surface rule, for example, to determine the total thickness of dirt and grass block in the plains.

JSON format[]

: Root object.
- sea_level: The sea level in this dimension. Note that this value only affects world generation. The sea level for mob spawning is a fixed value 63.
- disable_mob_generation: Disables creature spawning upon chunk generation.
- ore_veins_enabled: Whether ore veins generate.
- aquifers_enabled: Whether aquifers generate. If set to false, almost all caves below sea level will be filled with water.
- legacy_random_source: Whether to use the old random number generator from before 1.18 for world generation.
- default_block: The default block used for the terrain.
  - Block state
- default_fluid: The default block used for seas and lakes.
  - Block state
- spawn_target: (Required, but can be empty) A list of noise parameters to specify the points around which the player tries to spawn. The game will select some horizonal locations that are not more than 2560 blocks away from the origin (0,0), then sample the noise values ("depth" noise and "offset" are alway 0), and calculate ((x^2+z^2)^2) / 390625 + (the square of the mininum distance to the ranges in the list). The player will spawn near the location whose this value is smallest.
  - ：A range.
    - Noise parameter for biome (See Biome for usages of each parameter in vanilla game)
- noise: Fields for world generation.
  - min_y: The minimum Y coordinate where terrain starts generating. Value between -2032 and 2031 (both inclusive). Must be divisible by 16.
  - height: The total height where terrain generates. Value between 0 and 4064 (both inclusive). Must be divisible by 16. And min_y + height cannot exceed 2032.
  - size_horizontal: Value between 0 and 4 (both inclusive)
  - size_vertical: Value between 0 and 4 (both inclusive)
- noise_router: Routes density functions to noise parameters used for world generation. Each field can be an ID of density function or a density function (can be in constant form or object form).
  - initial_density_without_jaggedness: Related to the generation of aquifer and surface rule. At a horizonal position, starting from the top of the world, the game searches from top to bottom with the precision of size_vertical*4 blocks. The first Y-level whose noise value greater than 25/64 is used as the initial terrain height for world generation. This height should be generally lower than the actual terrain height (determined by the final density).
  - final_density: Determines where there is an air or a default block. If positive, returns default block which will can be replaced by the surface_rule. Otherwise, an air where aquifers can generate.
  - barrier: Affects whether to separate between aquifers and open areas in caves. Larger values leads to higher probability to separate.
  - fluid_level_floodedness: Affects the probability of generating liquid in an cave for aquifer. The larger value leads to higher probability. The noise value greater than 1.0 is regarded as 1.0, and value less than -1.0 is regarded as -1.0.
  - fluid_level_spread: Affects the height of the liquid surface at a horizonal position. Smaller value leads to higher probability for lower height.
  - lava: Affects whether an aquifer here uses lava instead of water. The threshold is 0.3.
  - vein_toggle: Affects ore vein type and vertical range. If the noise value is greater than 0.0, the vein will be a copper vein. If the noise value is less than or equal to 0.0, the vein will be an iron vein.
  - vein_ridged: Controls which blocks are part of a vein. If greater than or equal to 0.0, the block will not be part of a vein. If less than 0.0, the block will be either the vein type's stone block, or possibly an ore block.
  - vein_gap: Affects which blocks in a vein will be ore blocks. If greater than -0.3, and a random number is less than the absolute value of vein_toggle mapped from 0.4 - 0.6 to 0.1 - 0.3, with values outside of this range clamped, an ore block will be placed, with a 2% chance for the ore block to be a raw metal block. Otherwise, the ore type's stone block will be placed.
  - temperature: The temperature values only for biome placement. Note that this field and the following five fields do not affect terrain shape, as terrain generation is defined in final_density.
  - vegetation: The humidity values only for biome placement.
  - continents: The continentalness values only for biome placement.
  - erosion: The erosion values only for biome placement and aquifer generation.
  - depth: The depth values only for biome placement and aquifer generation.
  - ridges: The weirdness values only for biome placement.
- surface_rule: To place blocks in the terrain.
  - Surface rule

Density Function and Noise[]

A density function providers position-dependent values for noise router.

Noise[]

A noise can be referenced by a density function and surface rule. It is stored as JSON files within a data pack in the path data/<namespace>/worldgen/noise.

In addition to being called by density functions and surface rules, there are also some noises with hard-coded usage:

minecraft:surface: Affects the surface layer thickness in surface rule.
minecraft:surface_secondary: Used as the thickness of additional surface layer in surface rule.
minecraft:clay_bands_offset: Used to generate badland terracotta bands in bandlands surface rule.
minecraft:badlands_pillar, minecraft:badlands_pillar_roof, minecraft:badlands_surface: Used when generating badland hoodoos in minecraft:eroded_badlands biome.
minecraft:iceberg_pillar, minecraft:iceberg_pillar_roof, minecraft:iceberg_surface: Used when generating iceberg terrain feature in minecraft:frozen_ocean and minecraft:deep_frozen_ocean biomes.

JSON format of Noise[]

: Root object.

- firstOctave: First octave. If legacy_random_source in the noise settings is true, it must be an integer less than or equal to 1, otherwise the value range is not unlimited.
- amplitudes: Amplitudes of sub-noise. The frequency of a sub-noise at index (from 0) in the list is 2^(- firstOctave + index), and the amplitude (the value of the sub-noise ranges from -amplitude to +amplitude) of this sub-noise is about 1.04 * doubleValueAtIndex * 2^(sizeOfThisList - index - 1) / (2^sizeOfThisList - 1) (assuming the range of 3D Improved Perlin Noise is ±1.04). For each sub-noise, two 3D improved perlin noises are created and their average is taken. The final range of this noise value is ± 10 * sumOfSubNoises / ( 3 * ( 1 + 1 / m ) ), where m is the number of elements in the list after removing the leading and trailing zero elements. If legacy_random_source in the noise settings is true, the length must be less than or equal to 1-firstOctave. If false, the length is unlimited.
  - : A double value for a sub-noise.

Biome[]

A biome is a region in a dimension with distinct features, carvers, climates, spawned mobs, ambient sound and music, and sky, water, grass and foliage colors, stored as JSON files within a data pack in the path data/<namespace>/worldgen/biome.

Carver[]

Carvers are used to add carver caves and canyons. Note that noise caves are generated by noise settings.

Feature[]

Features are small decorations that can at most write to a 3x3 chunk area centered on the placement chunk. They're locally placed per chunk and cannot be searched for using commands. Examples are trees, flowers, ore, etc.

Structure[]

Structures are large decorations that can write to a much larger area than the 3x3 chunks of a feature. They're placed globally and spaced out in a randomized grid (or in concentric rings for strongholds), and can be scanned for and found using /locate. Structures can affect terrain generation.

Surface builder[]

This page describes content that exists only in outdated versions of Minecraft.

This feature used to be in the game, but has ever since been removed.It may or may not return in a future update.

Surface builders were used to control how the surface of the terrain is shaped and what blocks it is generated with. They are stored as JSON files within a data pack in the path data/<namespace>/worldgen/configured_surface_builder.

History[]

Java Edition
1.16.2	20w28a	Added support for custom world generation.
	20w28a	Added template for custom world generation on GitHub.
	20w29a	Noise settings can also be changed in worldgen.
1.18.2	22w06a	Added tag field to structure noise settings.
	1.18.2 Pre-release 1	Added `noise_router` to noise settings.
	1.18.2 Pre-release 1	Moved structure generation settings to separate files from noise settings.
1.19	22w11a	Added `spawn_target` field in noise settings, which is a list of climate target points.
	22w11a	Removed the `terrain_shaper` field in the `noise` field in noise settings. The terrain shaper splines have been moved to density functions.
	22w12a	Removed the `top_slide`, `bottom_slide` and `sampling` fields in the `noise` field in noise settings. Instead, these configurations are moved to density functions.
1.19.3	22w42a	World generation data now stored in data/minecraft/worldgen in client.jar.
1.19.3	22w42a	Template for custom world generation on GitHub no longer updates.