Intended as a utility mod for other mods to use when creating a more interesting underground experience in Minetest, primarily through the creation of enormous underground "natural" caverns with biome-based features. Installing this mod by itself will not do anything.
The API has the following methods:
This causes large caverns to be hollowed out during map generation. By default these caverns are just featureless cavities, but you can add extra subterrane-specific properties to biomes and the mapgen code will use them to add features of your choice.
Use this method when you want the following biome methods to be applied to pre-existing caves within a range of y values but don't want to excavate giant caverns there:
It's essentially a trimmed-down version of register_cave_layer.
Takes a voxelmanip index and the corresponding area object, and returns a pseudorandom float from 0-1 based on the x and z coordinates of the index's location.
This is mainly intended for use when placing stalactites and stalagmites, since in a natural cavern these two features are almost always paired with each other spatially.
Unfortunately there's currently no easy way to override a single biome (pre-Minetest 0.5), so this method does it by clearing and re-registering all existing biomes.
Not only that, but the decorations also need to be wiped and re-registered - it appears they keep track of the biome they belong to via an internal ID that gets changed when the biomes are re-registered, resulting in them being left assigned to the wrong biomes.
This method is provided in subterrane because the default mod includes and "underground" biome that covers everything below -113 and would be annoying to work around. Any mod using subterrane in conjunction with the default mod should probably override the "underground" biome.
Common cavern features
subterrane.register_stalagmite_nodes(base_name, base_node_def, drop_base_name)
This registers a set of four standardized stalactite/stalagmite nodes that can be used with the subterrane:stalagmite function below. "base name" is a string that forms the prefix of the names of the nodes defined, for example the coolcaves mod might use "coolcaves:crystal_stal" and the resulting nodes registered would be "coolcaves:crystal_stal_1" through "coolcaves:crystal_stal_4". "base_node_def" is a node definition table much like is used with the usual node registration function. register_stalagmite_nodes will amend or substitute properties in this definition as needed, so the simplest base_node_def might just define the textures used. "drop_base_name" is an optional string that will substitute the node drops with stalagmites created by another use of register_stalagmite_nodes, for example if you wrote
subterrane.register_stalagmite_nodes("coolcaves:wet_stal", base_wet_node_def, "coolcaves:dry_stal")
then when the player mines a dry stalactite they'll get a dry stalactite node and if they mine a wet stalactite they'll get a corresponding dry stalactite node as the drop instead.
This method returns a table consisting of the content IDs for the four stalactite nodes, which can be used directly in the following method:
subterrane:stalagmite(vi, area, data, param2_data, param2, height, stalagmite_id)
This method can be used to create a small stalactite or stalagmite, generally no more than 5 nodes tall. Use a negative height to generate a stalactite. The parameter stalagmite_id is a table of four content IDs for the stalagmite nodes, in order from thinnest ("_1") to thickest ("_4"). The register_stalagmite_nodes method returns a table that can be used for this directly.
subterrane:giant_stalagmite(vi, area, data, min_height, max_height, base_material, root_material, shaft_material)
Generates a very large multi-node stalagmite three nodes in diameter (with a five-node-diameter "root").
subterrane:giant_stalactite(vi, area, data, min_height, max_height, base_material, root_material, shaft_material)
Similar to above, but generates a stalactite instead.
subterrane:giant_shroom(vi, area, data, stem_material, cap_material, gill_material, stem_height, cap_radius)
Generates an enormous mushroom. Cap radius works well in the range of around 2-6, larger or smaller than that may look odd.
When the player spawns (or respawns due to death), this method will tell Minetest to attempt to locate a subterrane-generated cavern to place the player in. cave_layer_def is the same format as the cave definition above. Start_depth is the depth at which the game will start searching for a location to place the player. If the game doesn't find a location immediately it may wind up restarting the search for a spawn location at the top of the cave definition, so start_depth is not a guarantee that the player will start at least that deep; he could spawn anywhere within the cave layer's depth range.