Aquifers

Minecraft uses Aquifers to determine where to place liquids and air. Without aquifers all empty space below the sea-level would be filled with water. Aquifers thus allow caves to be dry.

Global Fluid Picker

The global fluid picker is used when aquifers are disabled and in some cases with aquifers enabled.

The global fluid picker is quite simple:

air above the sea-level
the default liquid between the sea-level and y=-54
lava below y=-54

If the sea-level is below y=-54:

air above the sea-level
lava below the sea-level

Preliminary Surface Height

The preliminary surface height the easiest way for the game to calculate the height of the terrain. It is calculated based on the inital_density_without_jaggedness density function. Checking from top to bottom, the first height where inital_density_without_jaggedness > 0.390625 is the preliminary surface height.

In vanilla, this height is usually about 8 blocks below the real surface, thus most calculations add 8 to the preliminary surface height.

Thus, for brevity, the following will use surface to refer to "8 blocks above the preliminary surface height".

Floodedness

States

For each position in the world, there is one of 4 aquifer floodedness states:

Disabled: In this case the global fluid picker is used. (meaning flooded caves and oceans, no water above sea-level)
Flooded: In this case, the fluid is placed up to the sea-level and air above. (similar to disabled, but with fluid selection)
Empty: In this case always air is placed.
Randomized: In this case, the fluid level is determined randomly. See below. (This case is what most people would usually associate with aquifers)

Determining Floodedness

The following will describe how the floodedness is determined:

Disabled, if the global fluid picker picks lava.
Disabled, if the position is at least 12 blocks above the surface.
Disabled, if the position is at most 12 blocks below the surface (or above) and there is a position nearby* where the surface is below sea-level.
Empty if erosion < -0.22499999403953552 and depth > 0.8999999761581421 (i.e. deep dark region, but hardcoded)
Otherwise, the floodedness is determined based on the value of the fluid_level_floodedness density function:
- Flooded if fluid_level_floodedness > min_disabled(usally 0.8)
- Empty if fluid_level_floodedness <= max_empty(usually 0.4)
- Randomized otherwise.

* for nearby positions the check happens offset in chunks: {0, 0}, {-2, -1}, {-1, -1}, {0, -1}, {1, -1}, {-3, 0}, {-2, 0}, {-1, 0}, {1, 0}, {-2, 1}, {-1, 1}, {0, 1}, {1, 1} (yes, this is not symmetric, don't ask me why)

Cut of values

min_disabled and max_empty can differ from the usual values if the surface is below the sea-level:

min_disabled varies linearly from -0.3 at the surface to 0.8 64 blocks below the surface.
max_empty varies linearly from -0.8 at the surface to 0.4 64 blocks below the surface.

Randomized fluid level

If the floodedness is determined to be Randomized, then the fluid level is determined using the fluid_level_spread density function.

For this, the world is split into 16x40x16 block cells. Each cell gets a uniform fluid level. The fluid level is calculated as center_height + fluid_level_spread * 10 where center_height is the height 20 blocks above the floor of the cell. The fluid level is then rounded down to the next multiple of 3.

Caution: the fluid_level_spread density function is sampled at 1/16, 1/40, 1/16 scale.

Fluid selection

If the fluid level at the current position is above -10, the default fluid is always used.

Otherwise, the fluid selection is based on the lava density function. For this, the world is split into 64x40x64 cells (i.e. 4x1x4 fluid level cells) with each cell given a single fluid.

The fluid is the default fluid if abs(lava) <= 0.3 and lava otherwise.

Caution: the lava density function is sampled at 1/64, 1/40, 1/64 scale.

Barriers

TODO [Somehow based on the barrier density function]

jacobsjo/explanation.md