Minecraft:Surface rule

Surface rules are used to determine the block for each solid position of the terrain. They are responsible for grass and Minecraft:dirt layers, creating different bands of Minecraft:terracotta in badlands, for Minecraft:deepslate, Minecraft:bedrock, and more.

Surface rules are used in the noise settings of a Minecraft:data pack.

JSON format

A surface rule is a type of decision tree. Using a combination of sequences and conditions, it can implement checks to place the right blocks in the right places.

• Template:Nbt The root object.
  • Template:Nbt: Type of the surface rule as a Minecraft:resource location.
  • Extra fields of the surface rule, described below.

The possible values for Template:Nbt and associated extra fields:

• bandlandsTemplate:Sic — Used in Minecraft:badlands to place Minecraft:terracotta. This rule has no extra fields.

• block — Places a specified block.
  • Template:Nbt: The block state to place.
    • Template:Nbt inherit/block state

• condition — Checks a condition
  • Template:Nbt: The surface condition (see below) to check.
  • Template:Nbt: The surface rule to run if the condition matches.

• sequence — Tries surface rules in order, only the first that matches is applied.
  • Template:Nbt: A list of surface rules to try.
    • Template:Nbt A surface rule object.

Surface conditions

• Template:Nbt The root object.
  • Template:Nbt: Type of the surface condition as a Minecraft:resource location.
  • Extra fields of the surface condition, described below.

The possible values for Template:Nbt and associated extra fields:

• above_preliminary_surface — Checks if the current position is above the preliminary surface level, which is a Y-level usually a few blocks below the main surface, ignoring noise caves. This is used to prevent grass blocks from being placed in noise caves. This condition has no extra fields. The preliminary surface level is calculated from the Template:Cd noise router density function.

• biome — Checks the biome at the current position.
  • Template:Nbt: A list of biomes where this condition matches.
    • Template:Nbt A resource location of a Minecraft:biome.

• hole — Passes for columns where the surface depth is 0. This condition has no extra fields.

• noise_threshold — Computes the noise value of the current column using a specified Minecraft:noise and checks if it is between the min and max threshold.
  • Template:Nbt: Template:Json ref.
  • Template:Nbt: The minimum noise value where the condition passes.
  • Template:Nbt: The maximum noise value where the condition passes.

• not — Inverts a surface conditions, passing when the nested condition fails.
  • Template:Nbt: The surface condition object to invert.

• steep — Checks if the current position is a steep face on the north or east sides of a mountain. This condition has no extra fields.

• stone_depth — Checks if the current position is within a specified distance from the surface, either upward or downward, using terrain depth. This is used in vanilla to place grass blocks and dirt layers on the surface in the Minecraft:overworld, and Minecraft:soul sand, Minecraft:soul soil, Minecraft:gravel and Minecraft:basalt floors and ceilings in the Minecraft:nether.
  • Template:Nbt: Either floor or ceiling. If floor, the blocks will be placed based on the distance to the surface above, if ceiling, the distance to the surface below will be used instead.
  • Template:Nbt: The vertical offset.
  • Template:Nbt: If true, adds the surface depth to the offset. Note: this is not Template:Cd!
  • Template:Nbt: Adds a mapped value of the secondary surface depth to the offset, calculated using the formula: Template:Cd.

• temperature — Checks if the current block is in a biome that is cold enough for Minecraft:snowfall. This condition has no extra fields.

• vertical_gradient — Compares the current Y position, with a messy transition, just like the deepslate and bedrock transitions.
  • Template:Nbt: Used as a seed to randomize the gradient.
  • Template:Nbt: The lower vertical anchor. Positions at and below this always pass.
    • Template:Nbt inherit/vertical anchor
  • Template:Nbt: The upper vertical anchor. Positions at and above this always fail. The Y-coords between the two vertical anchors produces a gradient where the probability of success is Template:Cd.
    • Template:Nbt inherit/vertical anchor

• water — Checks if the current position is above water, based on terrain depth. Note that if there is no water above this block, the condition always passes, regardless of the values of the fields.
  • Template:Nbt: The value added to the water depth before the comparison is done. This value can be negative to match blocks at a specific depth relative to water surface.
  • Template:Nbt: Value between -20 and 20. How much it is affected by the surface depth. Template:Cd is added to offset before comparing.
  • Template:Nbt: If true, adds the distance to the surface to the offset, effectively checking if the surface block above this one is above water.

• y_above — Checks if the current position is above a specified height (exclusive).
  • Template:Nbt: The vertical anchor to compare the height with.
    • Template:Nbt inherit/vertical anchor
  • Template:Nbt: Value between -20 and 20. How much it is affected by the surface depth. Template:Cd is added to anchor before comparing.
  • Template:Nbt: If true, adds the distance to the surface above to the offset.

Surface depth

The surface depth is an integer value computed for each column, which is used by various conditions. It uses the Template:Cd Minecraft:noise. The calculation is as follows: Template:Cd where Template:Cd returns the noise value of the Template:Cd noise and Template:Cd returns a random value between 0 and 1.

Secondary surface depth

The secondary surface depth is a value between -1 and 1 computed for each column, which can be used by the stone_depth condition. It uses the Template:Cd Minecraft:noise.

Terrain depth

The generator tracks the vertical distance to the surface above (internally stoneDepthAbove) and the cavity below (internally stoneDepthBelow), as well as how deep underwater each block is (if there is any water above it at all; waterHeight). These values are used in the stone_depth, water and y_above conditions.

History