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:

Cavern registration

subterrane:register_cave_layer(cave_layer_def)

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.

subterrane:register_cave_decor(minimum_depth, maximum_depth)

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.

Utilities

subterrane:vertically_consistent_random(vi, area)

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.

subterrane:override_biome(biome_def)

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:dry_stal", base_dry_node_def)
    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.

Player spawn

subterrane:register_cave_spawn(cave_layer_def, start_depth)

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.