Add biome definition

API.md

@@ -100,4 +100,57 @@ The shapes are defined as follows:
 Just like the surface world, the underground world uses biomes to decorate their
 caves. The cave biomes are independent of the cave shapes.
 
-**Under development.**
+For shapes, the following functions are available:
+
+- `noordstar_caves.register_biome(biome def)` Define a new cave biome
+- `noordstar_caves.unregister_biome(name)` Remove a defined cave biome
+- `noordstar_caves.clear_registered_biomes()` Remove all known cave biomes
+
+The biomes are defined as follows:
+
+```lua
+{
+    name = "noordstar_caves:tundra",
+    -- Unique name identifying the biome
+    -- Namespacing is not required but recommended
+
+    node_dust = "foo:snow",
+    -- Node dropped onto floor after all else is generated
+
+    node_floor = "foo:dirt_with_snow",
+    -- Node forming the floor that the player walks on
+
+    node_wall = "foo:ice",
+    -- Node forming the side walls of the cave
+
+    node_roof = "foo:bluestone",
+    -- Node forming the ceiling of the cave
+
+    node_shell = "foo:permafrost",
+    depth_shell = 3,
+    -- Node forming a layer around the entire cave and thickness of this layer
+    -- You can make the depth as high as you want, but raising it past 16
+    -- might cause hard cut-offs at chunk edges.
+
+    y_max = -100,
+    y_min = -31000,
+    -- Upper and lower limits of the cave biome.
+    -- Alternatively you can use xyz limits as shown below.
+
+    max_pos = { x =  31000, y = -100, z =  31000 }
+    min_pos = { x = -31000, y = -500, z = -31000 }
+    -- xyz limits for biome, an alternative to using `y_min` and `y_max`.
+    -- Cave biome is limited to a cuboid defined by these positions.
+    -- Any x, y or z field left undefined defaults to -31000 in `min_pos` or
+    -- 31000 in `max_pos`.
+
+    heat_point = 0,
+    humidity_point = 50,
+    -- Characteristic temperature and humidity for the biome.
+    -- Just like the Minetest Lua API for biomes, these values create
+    -- 'biome points' on a voronoi diagram with heat and humidity as axes.
+    -- The resulting voronoi cells determine the distribution of the biomes.
+    -- Heat and humidity have an average of 50, vary mostly between 0 and 100
+    -- but can exceed these values.
+}
+```