Spawn level: Add 'get_spawn_level(x, z)' API

Returns a suitable player spawn y co-ordinate for unmodified terrain.

1 files changed, 9 insertions, 0 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 6fe14472f..0bbf9c79b 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -3035,6 +3035,15 @@ and `minetest.auth_reload` call the authentication handler.
       unattached `group:attached_node` node to fall.
     * spread these updates to neighbours and can cause a cascade
       of nodes to fall.
+* `minetest.get_spawn_level(x, z)`
+    * Returns a player spawn y co-ordinate for the provided (x, z) co-ordinates,
+      or `nil` for an unsuitable spawn point.
+    * For most mapgens a 'suitable spawn point' is one with y between
+      `water_level` and `water_level + 16`, and in mgv7 well away from rivers,
+      so `nil` will be returned for many (x, z) co-ordinates.
+    * The spawn level returned is for a player spawn in unmodified terrain.
+    * The spawn level is intentionally above terrain level to cope with full-node
+      biome 'dust' nodes.
 
 ### Mod channels
 You can find mod channels communication scheme in `docs/mod_channels.png`.