Add heightmap types guide

src/guides/adding-custom-structures.md

@@ -120,7 +120,7 @@ Let's go over all the fields.
 * f`start_pool`: This is a reference to the template pool [(see next step)](#the-template-pool).
 * f`size`: This is a number between 1 and 7. This is important if your structure uses jigsaw. In this simple example, we'll leave it at 1.
 * f`start_height`: A height provider specifying at which height the structure should spawn. The example uses the constant shorthand so it just specifies a vertical anchor. If used together with f`project_start_to_heightmap`, will offset the height relative to the heightmap.
-* f`project_start_to_heightmap`: An optional heightmap type. Possible values: s`WORLD_SURFACE_WG`, s`WORLD_SURFACE`, s`OCEAN_FLOOR_WG`, s`OCEAN_FLOOR`, s`MOTION_BLOCKING`, and s`MOTION_BLOCKING_NO_LEAVES`. If f`start_height` is not 0, will move the start relative to the heightmap.
+* f`project_start_to_heightmap`: An optional [heightmap type](/guides/heightmap-types/). Possible values: s`WORLD_SURFACE_WG`, s`WORLD_SURFACE`, s`OCEAN_FLOOR_WG`, s`OCEAN_FLOOR`, s`MOTION_BLOCKING`, and s`MOTION_BLOCKING_NO_LEAVES`.
 * f`max_distance_from_center`: Value between 1 and 128. The maximum distance that a jigsaw can branch out.
 * f`use_expansion_hack`: You should always set this to false. Vanilla villages set this to true to fix an issue with their streets.
 #}

src/guides/heightmap-types.md

@@ -0,0 +1,33 @@
+---
+title: The different heightmap types explained
+versions:
+  - '1.16'
+  - '1.17'
+  - '1.18'
+  - '1.18.2'
+  - '1.19'
+tags:
+  - worldgen
+---
+
+Heightmaps are essentially a cache that store the height of the terrain for each block column in a chunk.
+
+They are computed by starting at the top of the world and iterating downwards, for each block checking if a condition still matches. Let's go over each type to see how they work.
+
+## `WORLD_SURFACE`
+The world surface heightmap is simplest one. It checks whether the block is air or not. This only matches `air`, `void_air` and `cave_air`.
+
+## `WORLD_SURFACE_WG`
+The worldgen variant of `WORLD_SURFACE`. Works exactly the same, but is updated during worldgen and is discarded after worldgen is finished.
+
+## `OCEAN_FLOOR`
+The ocean floor heightmap checks that the block has no collision box. This means it will pass through air, water, lava, bubble columns, portals, most plants, fire, cobwebs, powder snow, and many more blocks. An exception are carpets, which are seen as having no collision box to this heightmap.
+
+## `OCEAN_FLOOR_WG`
+The worldgen variant of `OCEAN_FLOOR`. Works exactly the same, but is updated during worldgen and is discarded after worldgen is finished.
+
+## `MOTION_BLOCKING`
+The motion blocking heightmap is similar to `OCEAN_FLOOR` that checks that the block has no collision box. The difference is that it also checks that there is no fluid in the block.
+
+## `MOTION_BLOCKING_NO_LEAVES`
+Similar to `MOTION_BLOCKING` but as the name suggests, this ignores leaves. The heightmap will be set to the ground next to trees even if leaves are above it.