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

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

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 6fe14472f1022d412c120be621bf8ccd0ba18d8a..0bbf9c79b5e8bdb99f51b6dad243d05c1c397b93 100644 (file)
--- 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`.

diff --git a/src/script/lua_api/l_mapgen.cpp b/src/script/lua_api/l_mapgen.cpp
index 11d963b4d89cf41f0505f55f1b974194b076c566..f5c76ec6e827e49a6cac0facf64c8e2598ccee87 100644 (file)
--- a/src/script/lua_api/l_mapgen.cpp
+++ b/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);

diff --git a/src/script/lua_api/l_mapgen.h b/src/script/lua_api/l_mapgen.h
index 713069633b1831f1be1abc72c9aa5f990d38ff7a..aebbcbac6c13e064dcaea048d55b1bbdee325bc4 100644 (file)
--- a/src/script/lua_api/l_mapgen.h
+++ b/src/script/lua_api/l_mapgen.h
@@ -44,6 +44,9 @@ class ModApiMapgen : public ModApiBase
        // 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);