From 36b755725dfdcbae3063f91b8d132039be3c3aa2 Mon Sep 17 00:00:00 2001
From: Bram van den Heuvel <bram.vdh1999@gmail.com>
Date: Mon, 22 Apr 2024 07:50:14 +0200
Subject: [PATCH] Add biome definition

---
 API.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/API.md b/API.md
index 44becb9..34a0c2c 100644
--- a/API.md
+++ b/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.
+}
+```