API improvements

Improvements found while using the portals API in another mod (cloudlands):
* remote_portal_checkup() will check the whole portal and frame for mapgen overwrites.
* Allow find_realm_anchorPos() to return nil if no realm location could be found (portal will fail to ignite).
* Allow create_book_of_portals() to be invoked [indirectly] by other mods.

Also lowers nether_book_close.png to be 4bpp

README.md

@@ -1,10 +1,9 @@
-Nether Mod for Minetest, with Portal API.
+Nether Mod for Minetest, with Portals API.
 
 See portal_api.txt for how to create custom portals to your own realms.
 
-A Book of Portals item (nether:book_of_portals) is created which
-provides players with portal recipes, by default it can be found in
-dungeon chests.
+See settingtypes.txt or go to "Settings"->"All Settings"->"Mods"->"nether"
+in the game to view the options provided by this mod.
 
 
 ## License of source code:

portal_api.lua

@@ -1178,7 +1178,13 @@ local function remote_portal_checkup(elapsed, portal_definition, anchorPos, orie
 	local wormholePos = portal_definition.shape.get_wormholePos_from_anchorPos(anchorPos, orientation)
 	local wormhole_node = minetest.get_node_or_nil(wormholePos)
 
-	if wormhole_node == nil or wormhole_node.name ~= portal_definition.wormhole_node_name then
+	local portalFound, portalLit = false, false	
+	if wormhole_node ~= nil and wormhole_node.name == portal_definition.wormhole_node_name then 
+		-- a wormhole node was there, but check the whole frame is intact
+		portalFound, portalLit = is_portal_at_anchorPos(portal_definition, anchorPos, orientation, false)
+	end
+
+	if not portalFound or not portalLit then
 		-- ruh roh
 		local message = "Newly created portal at " .. minetest.pos_to_string(anchorPos) .. " was overwritten. Attempting to recreate. Issue spotted after " .. elapsed .. " seconds"
 		minetest.log("warning", message)
@@ -1312,22 +1318,27 @@ local function ignite_portal(ignition_pos, ignition_node_name)
 			if DEBUG and destination_orientation == nil then minetest.chat_send_all("No destination_orientation given") end
 			if destination_orientation == nil then destination_orientation = orientation end
 
-			local destination_wormholePos = portal_definition.shape.get_wormholePos_from_anchorPos(destination_anchorPos, destination_orientation)
-			if DEBUG then minetest.chat_send_all("Destination set to " .. minetest.pos_to_string(destination_anchorPos)) end
+			if destination_anchorPos == nil then
+				if DEBUG then minetest.chat_send_all("No portal destination available here!") end
+				return false
+			else
+				local destination_wormholePos = portal_definition.shape.get_wormholePos_from_anchorPos(destination_anchorPos, destination_orientation)
+				if DEBUG then minetest.chat_send_all("Destination set to " .. minetest.pos_to_string(destination_anchorPos)) end
 
-			-- ignition/BURN_BABY_BURN
-			set_portal_metadata_and_ignite(portal_definition, anchorPos, orientation, destination_wormholePos)
+				-- ignition/BURN_BABY_BURN
+				set_portal_metadata_and_ignite(portal_definition, anchorPos, orientation, destination_wormholePos)
 
-			if portal_definition.sounds.ignite ~= nil then
-				local local_wormholePos = portal_definition.shape.get_wormholePos_from_anchorPos(anchorPos, orientation)
-				minetest.sound_play(portal_definition.sounds.ignite, {pos = local_wormholePos, max_hear_distance = 20})
-			end
+				if portal_definition.sounds.ignite ~= nil then
+					local local_wormholePos = portal_definition.shape.get_wormholePos_from_anchorPos(anchorPos, orientation)
+					minetest.sound_play(portal_definition.sounds.ignite, {pos = local_wormholePos, max_hear_distance = 20})
+				end
 
-			if portal_definition.on_ignite ~= nil then
-				portal_definition.on_ignite(portal_definition, anchorPos, orientation)
-			end
+				if portal_definition.on_ignite ~= nil then
+					portal_definition.on_ignite(portal_definition, anchorPos, orientation)
+				end
 
-			return true
+				return true
+			end
 		end
 	end
 end
@@ -1737,7 +1748,7 @@ local function create_book_of_portals()
 
 
 	create_book(
-		"nether:book_of_portals",
+		":nether:book_of_portals",
 		S("Book of Portals"),
 		"nether_book_of_portals.png",
 		S("A definitive guide to Rifts and Portals"),
@@ -2160,6 +2171,8 @@ end
 -- portal_name is optional, providing it allows existing portals on the surface to be reused.
 function nether.find_surface_target_y(target_x, target_z, portal_name)
 
+	assert(target_x ~= nil and target_z ~= nil, "Arguments `target_x` and `target_z` cannot be nil when calling find_surface_target_y()")
+
 	-- default to starting the search at -16 (probably underground) if we don't know the
 	-- surface, like paramat's original code from before get_spawn_level() was available:
 	-- https://github.com/minetest-mods/nether/issues/5#issuecomment-506983676
@@ -2215,6 +2228,7 @@ function nether.find_nearest_working_portal(portal_name, anchorPos, distance_lim
 
 	local portal_definition = nether.registered_portals[portal_name]
 	assert(portal_definition ~= nil, "find_nearest_working_portal() called with portal_name '" .. portal_name .. "', but no portal is registered with that name.")
+	assert(anchorPos         ~= nil, "Argument `anchorPos` cannot be nil when calling find_nearest_working_portal()")
 
 	local contenders = list_closest_portals(portal_definition, anchorPos, distance_limit, y_factor)
 

portal_api.txt

@@ -22,11 +22,6 @@ one kind of portal with the same frame material — such as obsidian — provide
 the size of the PortalShape is distinct from any other type of portal that is
 using the same node for its frame, and portal sizes remain small.
 
-Stone is not a good choice for portal frame nodes as the Minetest engine may
-convert it into terrain nodes if the biome-pass occurs after the portal is
-created. Similarly, avoid using nodes which may be replaced by ABMs or
-docoration functions without triggering the node's `on_destruct` handler.
-
 
 Realms
 ------
@@ -200,7 +195,9 @@ Used by `nether.register_portal`.
 
         within_realm = function(pos),
         -- Required. Return true if a portal at pos is in the realm, rather
-           than the surface world.
+        -- than the surface world.
+        -- Ideally implementations are fast, as this function can be used to
+        -- sift through a list of portals.
 
         find_realm_anchorPos = function(surface_anchorPos),
         -- Required. Return a position in the realm that a portal created at

settingtypes.txt

@@ -15,5 +15,5 @@ nether_realm_enabled (Enable Nether realm & portal) bool true
 # Enables the Floatlands portal api code example
 nether_enable_portal_example_floatlands (Enable example portal: Floatlands) bool false
 
-# Enables the Surface travel portal api code example
-nether_enable_portal_example_surfacetravel (Enable example portal: Surface travel) bool false
+# Enables the Surface-travel portal api code example
+nether_enable_portal_example_surfacetravel (Enable example portal: Surface-travel) bool false