View source for Custom world generation

{{see also|Tutorials/Custom world generation}}
{{Exclusive|java}}

'''Custom world generation''' allows [[data pack]]s to change how the world generate.

== World Preset and Dimension ==
{{main|Custom world preset|Custom dimension}}

A '''world preset''' controls what dimensions a world has. Before [[Java Edition 1.19|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 {{cd|data/<namespace>/worldgen/noise_settings}}, and are used with the {{cd|minecraft:noise}} generator in a dimension. Vanilla settings include {{cd|minecraft:overworld}} for normal [[Overworld]] generation, {{cd|minecraft:amplified}} for [[Amplified]] Overworld generation, {{cd|minecraft:nether}} for regular [[The Nether|Nether]] generation, {{cd|minecraft:caves}} for Cave (Nether-like generation but with Overworld [[terrain features]]) generation, {{cd|minecraft:end}} for regular [[The End|End]] generation, and {{cd|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, {{cd|minecraft:surface}} noise is used to calculate the thickness of the surface layer. {{cd|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 {{cd|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 ===
<div class="treeview">
* {{nbt|compound}}: Root object.
{{/noise settings}}
</div>

=== Density Function and Noise ===
{{main|Density function}}

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 <code>data/<namespace>/worldgen/noise</code>.

In addition to being called by density functions and surface rules, there are also some noises with hard-coded usage:
* {{code|minecraft:surface}}: Affects the surface layer thickness in surface rule.
* {{code|minecraft:surface_secondary}}: Used as the thickness of additional surface layer in surface rule.
* {{code|minecraft:clay_bands_offset}}: Used to generate badland terracotta bands in {{code|bandlands}} surface rule.
* {{code|minecraft:badlands_pillar}}, {{code|minecraft:badlands_pillar_roof}}, {{code|minecraft:badlands_surface}}: Used when generating badland [[Terrain_features#Hoodoo|hoodoo]]s in {{cd|minecraft:eroded_badlands}} biome.
* {{code|minecraft:iceberg_pillar}}, {{code|minecraft:iceberg_pillar_roof}}, {{code|minecraft:iceberg_surface}}: Used when generating iceberg [[terrain feature]] in {{cd|minecraft:frozen_ocean}} and {{cd|minecraft:deep_frozen_ocean}} biomes.

==== JSON format of Noise ====

<div class="treeview">
* {{nbt|compound}}: Root object.
{{/noise}}
</div>

== Biome ==
{{Main|Custom 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 {{cd|data/<namespace>/worldgen/biome}}.

== Carver ==
{{Main|Custom carver}}

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

== Feature ==
{{Main|Custom 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 [[tree]]s, [[flower]]s, ore, etc.

== Structure ==
{{Main|Custom structure}}

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

== Surface builder ==
{{Main|Configured surface builder}}
{{removed}}
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 {{cd|data/<namespace>/worldgen/configured_surface_builder}}.

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

== External links ==
* [https://github.com/slicedlime/examples/commits/master A list of all worldgen files for each Minecraft version before 1.19.3 (22w42a)]
* [https://gist.github.com/misode/45559d34627755ecaa52497daea83544 How to add a custom structure to the world]

== Notes ==
{{notelist}}

{{Data packs}}

[[de:Angepasste Weltgenerierung]]
[[ja:カスタムワールド生成]]
[[pt:Geração de mundo personalizado]]
[[zh:自定义世界生成]]