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

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

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`.

src/script/lua_api/l_mapgen.cpp

@@ -757,6 +757,27 @@ int ModApiMapgen::l_get_mapgen_object(lua_State *L)
 }
 
 
+// get_spawn_level(x = num, z = num)
+int ModApiMapgen::l_get_spawn_level(lua_State *L)
+{
+	NO_MAP_LOCK_REQUIRED;
+
+	s16 x = luaL_checkinteger(L, 1);
+	s16 z = luaL_checkinteger(L, 2);
+
+	EmergeManager *emerge = getServer(L)->getEmergeManager();
+	int spawn_level = emerge->getSpawnLevelAtPoint(v2s16(x, z));
+	// Unsuitable spawn point
+	if (spawn_level == MAX_MAP_GENERATION_LIMIT)
+		return 0;
+
+	// 'findSpawnPos()' in server.cpp adds at least 1
+	lua_pushinteger(L, spawn_level + 1);
+
+	return 1;
+}
+
+
 int ModApiMapgen::l_get_mapgen_params(lua_State *L)
 {
 	NO_MAP_LOCK_REQUIRED;
@@ -1714,6 +1735,7 @@ void ModApiMapgen::Initialize(lua_State *L, int top)
 	API_FCT(get_humidity);
 	API_FCT(get_biome_data);
 	API_FCT(get_mapgen_object);
+	API_FCT(get_spawn_level);
 
 	API_FCT(get_mapgen_params);
 	API_FCT(set_mapgen_params);

src/script/lua_api/l_mapgen.h

@@ -44,6 +44,9 @@ private:
 	// returns the requested object used during map generation
 	static int l_get_mapgen_object(lua_State *L);
 
+	// get_spawn_level(x = num, z = num)
+	static int l_get_spawn_level(lua_State *L);
+
 	// get_mapgen_params()
 	// returns the currently active map generation parameter set
 	static int l_get_mapgen_params(lua_State *L);