text changes

Also a minor change to prevent surface portals from appearing in a grid pattern in MT 0.4

portal_api.txt

@@ -19,12 +19,12 @@ Portal code is more efficient when each type of portal uses a different type
 of node to build its frame out of, however it is possible to register more than
 one kind of portal with the same frame material — such as obsidian — provided
 the size of the PortalShape is distinct from any other type of portal that is
-using the same node as its frame, and portal sizes remain small.
+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 happens after the portal is
+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 the node's `on_destruct` being triggered.
+docoration functions without triggering the node's `on_destruct` handler.
 
 
 Realms
@@ -44,9 +44,10 @@ In contrast, the "Surface portal" - an example in portal_examples.lua, only
 uses one realm. Its `is_within_realm()` function always returns true so that
 any time a portal is opened it will use `find_surface_anchorPos()`.
 
-Note that "find_surface_anchorPos" is a Nether-centric misnomer, as different
+Note that the name "find_surface_anchorPos" is a Nether-centric misnomer, as
-types of portals are free to use different definitions of a realm such that
+different types of portals are free to use different definitions of a realm
-leaving the realm might not be synonymous with travelling to the surface.
+such that leaving the realm might not be synonymous with travelling to the 
+surface.
 
 
 Helper functions
@@ -56,6 +57,7 @@ Helper functions
     * use this when determining where to spawn a portal, to avoid overwriting 
       player builds. It checks the area for any nodes that aren't ground or 
       trees.
+      Water will fail this test, unless it is unemerged.
 
 * `nether.find_surface_target_y(target_x, target_z, portal_name)`: returns a 
   suitable anchorPos
@@ -64,7 +66,8 @@ Helper functions
       surface to be reused.
 
 * `nether.find_nearest_working_portal(portal_name, anchorPos, distance_limit, y_factor)`: returns 
-  an anchorPos, or nil if no portal was found within the the distance_limit.
+  (anchorPos, orientation), or nil if no portal was found within the
+  distance_limit.
     * A y_factor of 0 means y does not affect the distance_limit, a y_factor
       of 1 means y is included (the default if y_factor is nil), and a y_factor
       of 2 would squash the search-sphere by a factor of 2 on the y-axis, etc.
@@ -101,7 +104,6 @@ Call these functions only at load time:
       takes on when you are standing inside a portal. `post_effect_color` is the 
       only key/value that is needed in the nodedef_overrides table to achieve that,
       but the function allows any nodedef key/value to be specified/overridden.
-    * Invokes `minetest.register_node()`, so can only be called at mod load time.
     * After `register_wormhole_node()`, invoke `register_portal()` and include 
       `wormhole_node_name` in the portal_definition, assigning it the name of the 
       new wormhole node.

portal_examples.lua

@@ -4,7 +4,7 @@
 
   These portal API examples work independently of the Nether realm
   and Nether portal. To try these examples, enable them in:
-	  Mintest -> Settings -> All settings -> Mods -> nether
+	  Minetest -> Settings -> All settings -> Mods -> nether
   Once enabled, details on how to build them can be found in dungeon
   chests in the book of portals.
 
@@ -56,7 +56,7 @@ if minetest.settings:get_bool("nether_enable_portal_example_floatlands", ENABLE_
 		FLOATLAND_LEVEL = minetest.get_mapgen_setting("mgv7_floatland_level") or 1280
 
 		if FLOATLANDS_ENABLED then
-			floatlands_flavortext = S("There is a floating land of hills and forests up there, over the edges of which is a perilous drop all the way back down to sea level. We have not found how far these strange pristine lands extend. I have half a mind to retire there one day.")
+			floatlands_flavortext = "\n\n	" .. S("There is a floating land of hills and forests up there, over the edges of which is a perilous drop all the way back down to sea level. We have not found how far these pristine lands extend. I have half a mind to retire there one day.")
 		end
 	end
 
@@ -90,10 +90,8 @@ if minetest.settings:get_bool("nether_enable_portal_example_floatlands", ENABLE_
 	└─┼─┼─┼─┼─┘
 	      └─┴─┴─┘          two blocks deep
 
-	This portal is different to the others, rather than acting akin to a doorway it appears to the eye more like a small pool of water which can be stepped into. Upon setting foot in the portal we found ourselves at a great altitude.
+	This portal is different to the others, rather than acting akin to a doorway it appears to the eye more like a small pool of water which can be stepped into. Upon setting foot in the portal we found ourselves at a tremendous altitude.@1]],
-
+		floatlands_flavortext),
-	@1
-	]], floatlands_flavortext),
 
 		is_within_realm = function(pos) -- return true if pos is inside the Nether
 			return pos.y > FLOATLAND_LEVEL - 200
@@ -144,8 +142,9 @@ if minetest.settings:get_bool("nether_enable_portal_example_surfacetravel", ENAB
 		      └─╚═╤═╤═┼─┘          in a circular shape
 		            └─┴─┴─┘                standing vertically, like a doorway
 
-	These travel a distance along the ground, and even when constructed deep underground they link back up to the surface, but we were never able to predict where the matching twin portal would appear. Coudreau believes it works in epicycles, but I am not convinced.
+	These travel a distance along the ground, and even when constructed deep underground will link back up to the surface. They appear to favor a strange direction, with the exit portal linking back only for as long as the portal stays open — attempting to reopen a portal from the exit doorway leads to a new destination along this favored direction. It has stymied our ability to study the behavior of these portals because without constructing dual portals and keeping both open it's hard to step through more than one and still be able to return home.
-	]]),
+
+	Due to such difficulties, we never learned what determines the direction and distance a matching twin portal will appear, and I have lost my friend and protégé. In cavalier youth and with little more than a rucksack, Coudreau has decided to follow the chain as far as it goes, and has not been seen since. Coudreau believes it works in epicycles, but I am not convinced. Still, I cling to the hope that one day the portal will open and Coudreau will step out from whichever place leads to this one, perhaps with an epic tale to tell.]]),
 
 		is_within_realm = function(pos)
 			-- Always return true, because these portals always just take you around the surface
@@ -192,24 +191,24 @@ if minetest.settings:get_bool("nether_enable_portal_example_surfacetravel", ENAB
 				-- least adjust the coords a little so portals don't line up in a grid
 				local adj_x, adj_z = 0, 0
 
-				if minetest.get_spawn_level ~= nil then -- older versions of Minetest don't have this
+				-- Deterministically look for a location in the cell where get_spawn_level() can give
-					-- Deterministically look for a location in the cell where get_spawn_level() can give
+				-- us a surface height, since nether.find_surface_target_y() works *much* better when
-					-- us a surface height, since nether.find_surface_target_y() works *much* better when
+				-- it can use get_spawn_level()
-					-- it can use get_spawn_level()
+				local prng = PcgRandom( -- seed the prng so that all portals for these Moore Curve coords will use the same random location
-					local prng = PcgRandom( -- seed the prng so that all portals for these Moore Curve coords will use the same random location
+					moore_pos.x * 65732 +
-						moore_pos.x * 65732 +
+					moore_pos.y * 729   +
-						moore_pos.y * 729   +
+					minetest.get_mapgen_setting("seed") * 3
-						minetest.get_mapgen_setting("seed") * 3
+				)
-					)
 
-					local attemptLimit = 15 -- how many attempts we'll make at finding a good location
+				local attemptLimit = 15 -- how many attempts we'll make at finding a good location
-					for attempt = 1, attemptLimit do
+				for attempt = 1, attemptLimit do
-						adj_x = math.floor(prng:rand_normal_dist(-search_radius, search_radius, 2) + 0.5)
+					adj_x = math.floor(prng:rand_normal_dist(-search_radius, search_radius, 2) + 0.5)
-						adj_z = math.floor(prng:rand_normal_dist(-search_radius, search_radius, 2) + 0.5)
+					adj_z = math.floor(prng:rand_normal_dist(-search_radius, search_radius, 2) + 0.5)
-						if minetest.get_spawn_level(target_x + adj_x, target_z + adj_z)	~= nil then
+					if minetest.get_spawn_level == nil or minetest.get_spawn_level(target_x + adj_x, target_z + adj_z)	~= nil then
-							-- found a location which will be at ground level (unless a player has built there)
+						-- Found a location which will be at ground level - unless a player has built there.
-							break
+						-- Or this is MT 0.4 which does not have get_spawn_level(), so there's no point looking
-						end
+						-- at any further further random locations.
+						break
 					end
 				end