From 2a6ffd9f92da85bdec76db32c8b8c906b7e69082 Mon Sep 17 00:00:00 2001 From: Bram van den Heuvel Date: Tue, 3 Sep 2024 23:32:35 +0200 Subject: [PATCH] Update API.md --- API.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 111 insertions(+), 13 deletions(-) diff --git a/API.md b/API.md index 71cdc27..cc61037 100644 --- a/API.md +++ b/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 = + + -- Node tiles for layout + tiles = + + -- 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.