documentation

guide.md

@@ -168,6 +168,12 @@ Not all vast open spaces underground are the result of aeons of erosion by water
 
 The great extent of chasms makes them hospitable to small flying creatures, and their narrowness makes the hospitable to creatures that feed on them - giant cave spider webs can be found strung across them here and there. A dubious salvation for anyone falling from above.
 
+# Pit caves
+
+![Looking up from the bottom of a pit](./df_caverns/screenshots/pit_cave.jpg)
+
+A pit cave is a type of cave which contains one or more significant vertical shafts rather than being predominantly a conventional horizontal cave passage. Pit caves typically form in limestone as a result of long-term erosion by water. Given the vast scope of the flowstone formations found throughout the upper layers of the world's caverns, correspondingly gigantic pits can also be found. They sometimes breach the surface of the world, and at their greatest extent can have a drop over two kilometers deep. Bring plenty of rope when exploring such abysses.
+
 # Sunless Sea
 
 ![Sunless river](./df_caverns/screenshots/sunless_river.jpg)

pit_caves/README.md

@@ -0,0 +1,18 @@
+A pit cave, shaft cave or vertical cave—or often simply called a pit (in the US) or pot (in the UK); jama in South Slavic languages scientific and colloquial vocabulary (borrowed since early research in the Western Balkan Dinaric Alpine karst)—is a type of cave which contains one or more significant vertical shafts rather than being predominantly a conventional horizontal cave passage. Pit caves typically form in limestone as a result of long-term erosion by water.
+
+In the real world, the deepest known vertical drop in a cave is 603m in Vrtoglavica Cave in Slovenia. This mod adds pits of varying depth, with some under the default settings being up to 2500m deep. They are widely scattered and not all of them breach the surface, so they are a rare find, but with the right tools a pit cave can give access to a huge swath of underground terrain.
+
+## Settings and commands
+
+The following settings are available for configuring pit cave generation:
+
+    pit_caves_min_bottom (Lower limit of bottoms of pits) int -2500
+    pit_caves_max_bottom (Upper limit of bottoms of pits) int -500
+    pit_caves_min_top (Lower limit of tops of pits) int -100
+    pit_caves_max_top (Upper limit of tops of pits) int 100
+    pit_caves_mapblock_spacing (Average number of map blocks between pits) int 16
+    pit_caves_seal_ocean (Seal off pits that are under ocean water) bool true
+
+The pit_caves_seal_ocean setting isn't perfect, some map generation scenarios can result in a gap through which water can flow. But it's better than having drain holes everywhere.
+
+Users with the "server" privilege can use the ``/findpits`` command, which will list the locations of nearby pit caves.

pit_caves/init.lua

@@ -188,7 +188,7 @@ local send_nearby_states = function(pos, name)
 	return retval
 end
 
-minetest.register_chatcommand("findpit", {
+minetest.register_chatcommand("findpits", {
     params = "pos", -- Short parameter description
     description = S("find the pits near the player's map region, or in the map region containing pos if provided"),
     func = function(name, param)