Update API.md

API.md

@@ -54,7 +54,7 @@ under can do this.
 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
+the droplet. If there's no surface within 50 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.
 
@@ -85,17 +85,115 @@ Huge dripstone cannot be upgraded to a dripstone block, however.
 
 ## Lua modders
 
-The following API functions are exposed for you to manipulate this mod with.
+Everything until this section has been an introduction to how the mod has
+implemented dripstone. However, you are welcome to make changes and add your
+own types!
 
-- `noordstar_dripstone.add_lava_source(nodename)` Add a node name that the mod
-should consider a source of lava droplets above dripstone blocks.
-- `noordstar_dripstone.add_water_source(nodename)` Add a node name that the mod
-should consider a source of water droplets above dripstone blocks.
-- `noordstar_dripstone.add_lava_catcher(oldnodename, newnodename)` Register a
-node that can catch lava droplets to transform into a new node, such as a
-cauldron.
-- `noordstar_dripstone.add_water_catcher(oldnodename, newnodename)` Register a
-node that can catch water droplets to transform into a new node, such as a
-cauldron.
+Matter of fact, everything until this section has been written using this
+publicly available mod. So take a look at [the init.lua file](init.lua) if
+you'd prefer to look at a real example.
 
-All input values are strings in this API.
+This mod uses **droplets** to build the dripstone. These are incredibly tiny
+drops of liquid that flow down a dripstone. Currently, there are two
+types in use: `water` and `lava`.
+
+### noordstar_dripstone.register_droplet(droplet)
+
+Every droplet type is a unique string. Different droplets interact uniquely
+with different dripstones.
+
+```lua
+noordstar_dripstone.register_droplet("magma")
+noordstar_dripstone.register_droplet("mercury")
+noordstar_dripstone.register_droplet("mineral_water")
+```
+
+### noordstar_dripstone.add_droplet_source(droplet, nodename)
+
+In order to let droplets stream down dripstone nodes, you need to define which
+nodes a full dripstone block can absorb liquid from. Absorbing liquid does not
+affect the liquid node: this mod creates a way for players to duplicate liquid
+nodes.
+
+Generally, you are recommended to use liquid source blocks to create droplets.
+However, you don't need to do this! You could use any node, as long as it has a
+name.
+
+```lua
+noordstar_dripstone.add_droplet_source("water", "mymod:swamp_water_source")
+```
+
+### noordstar_dripstone.add_droplet_catcher(droplet, oldnodename, newnodename)
+
+Similarly, on the other side of the dripstone, you can create a catcher that
+can catch any of the liquid drops dripping down. You can use this to create
+orchids, or to create other interactions with nodes that might change from a
+tiny bit of liquid.
+
+```lua
+noordstar_dripstone.add_droplet_catcher("water", "mymod:cauldron_empty", "mymod:water_cauldron")
+noordstar_dripstone.add_droplet_catcher("water", "mymod:dirt", "mymod:farmland")
+noordstar_dripstone.add_droplet_catcher("lava", "mymod:precious_orchid", "mymod:dead_bush")
+```
+
+### noordstar_dripstone.register_dripstone(flavor, def)
+
+You can define your own dripstone type. You need to pick a flavor (which you
+shouldn't namespace) and you need to offer a dripstone definition, which is
+defined as follows:
+
+```
+{
+    -- What item is dropped when the dripstone is broken.
+    -- When left nil, the spike of the dripstone type is dropped.
+    drop = "dry"
+
+    -- What flavor to become when using liquid to grow.
+    -- Leave to nil when unable to grow.
+    grow_to = "dry"
+
+    -- When receiving a droplet of a given type, transform into a different
+    -- dripstone type. When a droplet is unspecified, the block cannot
+    -- receive the droplet.
+    on_droplet_receive = {
+        water = "watered",
+        lava = "molten",
+    }
+
+    -- Sounds that the dripstone makes
+    sounds = <standard sound definition for a node>
+
+    -- Node tiles for layout
+    tiles = <node tile layout>
+
+    -- Droplet type that the dripstone flavor can pass down.
+    -- When the droplet is passed down, the dripstone converts to the
+    -- "grow_to" type
+    trickle_down = "water"
+
+    -- Speed of how often a droplet trickles down.
+    trickle_speed = 5
+}
+```
+
+For examples, refer to [this mod's init.lua file](init.lua).
+
+### noordstar_dripstone.size_to_name(flavor, size)
+
+Lastly, this function serves as a tool to help you find the node name of a
+dripstone of a given flavor and size. Remember that dripstone size range from 1
+to 8.
+
+```lua
+noordstar_dripstone.size_to_name("dry", 1)
+-- Returns "noordstar_dripstone:dry_dripstone_spike"
+
+noordstar_dripstone.size_to_name("lol", 3)
+-- Returns "noordstar_dripstone:small_lol_dripstone"
+
+noordstar_dripstone.size_to_name("cool", 8)
+-- Returns "noordstar_dripstone:cool_dripstone_block"
+```
+
+Note how the function even returns a string if the dripstone type hasn't been
+registered.