Add API documentation

API.md

@@ -0,0 +1,84 @@
+# Dripstone API manual
+
+The dripstone behavior in this mod differs from games like Minecraft by adding
+more complexity in a context agnostic manner. This means that in comparison to
+a game like Minecraft:
+
+- This dripstone is **computationally very cheap**, as it doesn't care whether
+it's part of a stalactite, stalagmite or neither.
+- This dripstone grows in **more accurate shapes**, forming more complex shapes
+that occur in nature too.
+- This dripstone doesn't know whether it is part of a stalactite or stalagmite,
+so it **doesn't support falling stalactites**.
+
+![Dripstone demonstration showing various complex shapes](textures/dripstone_example.png)
+
+## Composition
+
+Dripstone has 4 dripstone types:
+
+- Dry dripstone, which is the default type.
+- Watered dripstone, which has absorbed water.
+- Molten dripstone, which has absorbed lava.
+- Hardened dripstone, which has absorbed water & lava at the same time.
+
+Dripstone has 8 different sizes:
+
+- A base dripstone block
+- 7  dripstone spike shapes that can grow in height and thickness.
+
+As you can see in the image below, shape sizes from smallest to largest are
+spike, tiny, small, medium, great, large, huge, and block.
+
+![Classification of all 32 dripstone nodes](textures/dripstone_classification.png)
+
+From left to right, the dripstone types are dry dripstone, watered dripstone,
+molten dripstone and hardened dripstone.
+
+## Dry dripstone
+
+Dry dripstone is the base dripstone type. All dripstone types mimick this type
+with a few minor changes.
+
+Dry dripstone blocks are the only type that can absorb liquids. When doing so,
+they become watered or molten dripstone blocks.
+
+## Watered & molten dripstone
+
+Dripstone that has absorbed water or lava, can use it for three things. Once it
+has done either of the three following options, the dripstone becomes dry.
+
+1. The dripstone can use it to grow 1 size. Only dripstone of size 6 (Large) and
+under can do this.
+2. The dripstone can pass the liquid down to a dripstone directly below it.
+Liquids can never be passed down to hardened dripstones.
+3. If the dripstone is a spike size, it can release the droplet downwards to the
+ground or to an object (such as a dripstone spike or a cauldron) that can catch
+the droplet. If there's no surface within 25 blocks, the droplet evaporates. If
+there's a surface that is unable to catch the droplet, a new spike will grow on
+top, effectively forming a new stalagmite.
+
+Since dripstone blocks are the only blocks that can absorb liquids, they
+function as a sprinkler that grows both the stalactite and stalagmite beneath
+it.
+
+**Note:** It is impossible to grow new dripstone blocks using dripstone blocks.
+As a result, you must either build your dripstone/lava/water farm in a cave, or
+you need to acquire silk touch to be able to break, move and place the dripstone
+blocks.
+
+## Hardened dripstone
+
+Similar to how unbreakable a block of obsidian is when lava & water mix,
+hardened dripstone is a tough, less breakable type of dripstone that occurs when
+a dripstone absorbs both watetr & lava before drying up.
+
+Hardened dripstone cannot grow, it cannot absorb water or pass it on.
+
+## Crafting
+
+Dripstone blocks cannot be crafted.
+
+All other sizes can be crafted using dripstone spikes. You can upgrade a
+dripstone item by surrounding it with (the same type of) dripstone spikes.
+Huge dripstone cannot be upgraded to a dripstone block, however.

README.md

@@ -4,6 +4,9 @@ This Minetest mod adds dripstone to Minetest.
 
 ![Dripstone in various shapes and forms, absorbing water and lava](textures/noordstar_dripstone_preview.png)
 
+You can read the [API manual](API.md) for an extensive explanation on how the
+dripstone works in this mod.
+
 ## Contribute
 
 You can contribute by making pull requests or by reaching out to me