bug fixes

DEPTH_FLOOR_LAYERS initial value fixed.
find_surface_anchorPos() no longer assumes y=0 will be outside the nether.
Nil-reference fixed when a mods tries to register a portal after mods are finished loading, but the portal shape+material was already registered by another mod.
Documentation improvements.

init.lua

@@ -88,7 +88,7 @@ nether.DEPTH = nether.DEPTH_CEILING -- Deprecated, use nether.DEPTH_CEILING inst
 -- for its ceiling Y, so there is room to shift edge-case biomes), then set
 -- nether.DEPTH_FLOOR_LAYERS to reflect the mod's floor Y value, and call
 -- shift_existing_biomes() with DEPTH_FLOOR_LAYERS as the floor_y argument.
-nether.DEPTH_FLOOR_LAYERS = nether.DEPTH_CEILING
+nether.DEPTH_FLOOR_LAYERS = nether.DEPTH_FLOOR
 
 -- A debug-print function that understands vectors etc. and does not
 -- evaluate when debugging is turned off.
@@ -176,7 +176,7 @@ The expedition parties have found no diamonds or gold, and after an experienced
 			local destination_pos = vector.divide(surface_anchorPos, nether.FASTTRAVEL_FACTOR)
 			destination_pos.x = math.floor(0.5 + destination_pos.x) -- round to int
 			destination_pos.z = math.floor(0.5 + destination_pos.z) -- round to int
-			destination_pos.y = nether.DEPTH_CEILING - 1000 -- temp value so find_nearest_working_portal() returns nether portals
+			destination_pos.y = nether.DEPTH_CEILING - 1 -- temp value so find_nearest_working_portal() returns nether portals
 
 			-- a y_factor of 0 makes the search ignore the altitude of the portals (as long as they are in the Nether)
 			local existing_portal_location, existing_portal_orientation =
@@ -201,7 +201,7 @@ The expedition parties have found no diamonds or gold, and after an experienced
 			local destination_pos = vector.multiply(realm_anchorPos, nether.FASTTRAVEL_FACTOR)
 			destination_pos.x = math.min(30900, math.max(-30900, destination_pos.x)) -- clip to world boundary
 			destination_pos.z = math.min(30900, math.max(-30900, destination_pos.z)) -- clip to world boundary
-			destination_pos.y = 0 -- temp value so find_nearest_working_portal() doesn't return nether portals
+			destination_pos.y = nether.DEPTH_CEILING + 1 -- temp value so find_nearest_working_portal() doesn't return nether portals
 
 			-- a y_factor of 0 makes the search ignore the altitude of the portals (as long as they are outside the Nether)
 			local existing_portal_location, existing_portal_orientation =

nether_api.txt

@@ -24,6 +24,14 @@ The Nether mod exposes some of its functions and data via the lua global
   `nether.DEPTH_FLOOR_LAYERS` to reflect the mod's floor Y value, and call
   `shift_existing_biomes()` with DEPTH_FLOOR_LAYERS as the `floor_y` argument.
 
+* `nether.NETHER_REALM_ENABLED`: [read-only] Gets the value of the "Enable
+  Nether realm & portal" setting the nether mod exposes in Minetest's
+  "All Settings" -> "Mods" -> "nether" options.
+  When false, the entire nether mapgen is disabled (not run), and the portal
+  to it is not registered. Reasons someone might disable the Nether realm
+  include if a nether-layer mod was to be used as the Nether instead, or if
+  the portal mechanic was desired in a game without the Nether, etc.
+
 * `nether.useBiomes`: [read-only] When this is false, the Nether interop
   functions below are not available (nil).
   Indicates that the biomes-enabled mapgen is in use. The Nether mod falls back
@@ -34,7 +42,8 @@ The Nether mod exposes some of its functions and data via the lua global
 Mapgen functions available when nether.useBiomes is true
 --------------------------------------------------------
 
-The following functions are nil when `nether.useBiomes` is false
+The following functions are nil if `nether.useBiomes` is false,
+and also nil if `nether.NETHER_REALM_ENABLED` is false.
 
 * `nether.mapgen.shift_existing_biomes(floor_y, ceiling_y)` Move any existing
   biomes out of the y-range specified by `floor_y` and `ceiling_y`.
@@ -53,4 +62,17 @@ The following functions are nil when `nether.useBiomes` is false
   the Nether's cavern noise.
 
 * `nether.mapgen.get_cave_perlin_at(pos)`: Returns the Nether cavern noise
-  value at a given 3D position.
+  value at a given 3D position.
+
+
+Other mapgen functions
+-------------------------------------------
+
+If the Nether realm is enabled, then this function will be available
+regardless of whether `nether.useBiomes` is true:
+
+* `nether.find_nether_ground_y(target_x, target_z, start_y, player_name)`
+  Uses knowledge of the nether mapgen algorithm to return a suitable ground
+  level for placing a portal.
+    * `player_name` is optional, allowing a player to spawn a remote portal
+      in their own protected areas.

portal_api.lua

@@ -2073,7 +2073,7 @@ function nether.register_portal(name, portaldef)
 	end
 
 	portaldef.name     = name
-	portaldef.mod_name = minetest.get_current_modname()
+	portaldef.mod_name = minetest.get_current_modname() or "<mod name not recorded>"
 
 	-- use portaldef_default for any values missing from portaldef or portaldef.sounds
 	if portaldef.sounds ~= nil then setmetatable(portaldef.sounds, {__index = portaldef_default.sounds}) end

portal_api.txt

@@ -250,16 +250,16 @@ Used by `nether.register_portal`.
         -- player_name may be "", e.g. if the portal was ignited by a mesecon,
         -- and is provided for use with volume_is_natural_and_unprotected() etc.
 
-        on_run_wormhole      = function(portalDef, anochorPos, orientation),
+        on_run_wormhole      = function(portalDef, anchorPos, orientation),
         -- invoked once per second per portal
-        on_extinguish        = function(portalDef, anochorPos, orientation),
+        on_extinguish        = function(portalDef, anchorPos, orientation),
         -- invoked when a portal is extinguished, including when the portal
         -- it connected to was extinguished.
         on_player_teleported = function(portalDef, player, oldPos, newPos),
         -- invoked immediately after a player is teleported
-        on_ignite            = function(portalDef, anochorPos, orientation)
+        on_ignite            = function(portalDef, anchorPos, orientation)
         -- invoked when a player or mesecon ignites a portal
-        on_created           = function(portalDef, anochorPos, orientation)
+        on_created           = function(portalDef, anchorPos, orientation)
         -- invoked when a portal creates a remote twin, this is usually when
         -- a player travels through a portal for the first time.
     }