Images instead of ASCII diagrams in Book of Portals

README.md

@@ -37,7 +37,7 @@ SOFTWARE.
  * `nether_portal_ignite.ogg` is a derivative of "Flame Ignition" by hykenfreak (https://freesound.org/people/hykenfreak), used under CC BY 3.0. "Nether Portal ignite" is licensed under CC BY 3.0 by Treer.
 
 ### [Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)](https://creativecommons.org/licenses/by-sa/4.0/)
- * `nether_book_`* (files starting with "nether_book"): Treer, 2019
+ * `nether_book_`* (files starting with "nether_book"): Treer, 2019-2020
  * `nether_portal_ignition_failure.ogg`: Treer, 2019
  * `nether_particle_anim`* (files starting with "nether_particle_anim"): Treer, 2019
 

init.lua

@@ -75,24 +75,12 @@ if nether.NETHER_REALM_ENABLED then
 		shape               = nether.PortalShape_Traditional,
 		frame_node_name     = "default:obsidian",
 		wormhole_node_color = 0, -- 0 is magenta
+		title = S("Nether Portal"),
+		book_of_portals_pagetext = S([[Construction requires 14 blocks of obsidian, which we found deep underground where water had solidified molten rock. The finished frame is four blocks wide, five blocks high, and stands vertically, like a doorway.
 
-		-- Warning: "Four per Em" spaces have been used to align the diagram in this text, rather
+This opens to a truly hellish place, though for small mercies the air there is still breathable. There is an intriguing dimensional mismatch happening between this realm and ours, as after opening the second portal into it we observed that 10 strides taken in the Nether appear to be an equivalent of @1 in the natural world.
-		-- than ASCII spaces. If Minetest changes font this may need to be updated.
-		book_of_portals_pagetext = S([[      ──══♦♦♦◊   The Nether   ◊♦♦♦══──
 
-	Requiring 14 blocks of obsidian, which we found deep underground where water had solidified molten rock. The frame must be constructed in the following fashion:
+The expedition parties have found no diamonds or gold, and after an experienced search party failed to return from the trail of a missing expedition party, I must conclude this is a dangerous place.]], 10 * nether.FASTTRAVEL_FACTOR),
-
-	┌═╤═╤═╤═╗
-	├─╥─┴─┼─╢
-	├─╢         ├─╢
-	├─╢         ├─╢     four blocks wide
-	├─╚═╤═╡─╢     five blocks high
-	└─┴─┴─┴─┘     Standing vertically, like a doorway
-
-	This opens to a truly hellish place, though for small mercies the air there is still breathable. There is an intriguing dimensional mismatch happening between this realm and ours, as after opening the second portal into it we observed that 10 strides taken in the Nether appear to be an equivalent of @1 in the natural world.
-
-	The expedition parties have found no diamonds or gold, and after an experienced search party failed to return from the trail of a missing expedition party, I must conclude this is a dangerous place.
-	]], 10 * nether.FASTTRAVEL_FACTOR),
 
 		is_within_realm = function(pos) -- return true if pos is inside the Nether
 			return pos.y < nether.DEPTH

portal_api.lua

@@ -123,8 +123,10 @@ nether.PortalShape_Traditional = {
 	name = "Traditional",
 	size = vector.new(4, 5, 1), -- size of the portal, and not necessarily the size of the schematic,
 	                            -- which may clear area around the portal.
-	schematic_filename = nether.path .. "/schematics/nether_portal.mts",
+	schematic_filename    = nether.path .. "/schematics/nether_portal.mts",
-	is_horizontal  = false, -- whether the wormhole is a vertical or horizontal surface
+	is_horizontal         = false, -- whether the wormhole is a vertical or horizontal surface
+	diagram_image_texture = "nether_book_diagram_traditional.png", -- The diagram to be shown in the Book of Portals
+	diagram_image_aspect  = 2.11, -- gives the vertical size of the image when multiplied by the width
 
 	-- returns the coords for minetest.place_schematic() that will place the schematic on the anchorPos
 	get_schematicPos_from_anchorPos = function(anchorPos, orientation)
@@ -271,8 +273,10 @@ nether.PortalShape_Circular = {
 	name = "Circular",
 	size = vector.new(7, 7, 1), -- size of the portal, and not necessarily the size of the schematic,
 	                            -- which may clear area around the portal.
-	schematic_filename = nether.path .. "/schematics/nether_portal_circular.mts",
+	schematic_filename    = nether.path .. "/schematics/nether_portal_circular.mts",
-	is_horizontal  = false, -- whether the wormhole is a vertical or horizontal surface
+	is_horizontal         = false, -- whether the wormhole is a vertical or horizontal surface
+	diagram_image_texture = "nether_book_diagram_circular.png", -- The diagram to be shown in the Book of Portals
+	diagram_image_aspect  = 1.62, -- gives the vertical size of the image when multiplied by the width
 
 	-- returns the coords for minetest.place_schematic() that will place the schematic on the anchorPos
 	get_schematicPos_from_anchorPos = function(anchorPos, orientation)
@@ -401,8 +405,10 @@ nether.PortalShape_Platform = {
 	name = "Platform",
 	size = vector.new(5, 2, 5), -- size of the portal, and not necessarily the size of the schematic,
 	                            -- which may clear area around the portal.
-	schematic_filename = nether.path .. "/schematics/nether_portal_platform.mts",
+	schematic_filename    = nether.path .. "/schematics/nether_portal_platform.mts",
-	is_horizontal  = true, -- whether the wormhole is a vertical or horizontal surface
+	is_horizontal         = true, -- whether the wormhole is a vertical or horizontal surface
+	diagram_image_texture = "nether_book_diagram_platform.png", -- The diagram to be shown in the Book of Portals
+	diagram_image_aspect  = 0.65, -- gives the vertical size of the image when multiplied by the width
 
 	-- returns the coords for minetest.place_schematic() that will place the schematic on the anchorPos
 	get_schematicPos_from_anchorPos = function(anchorPos, orientation)
@@ -1379,7 +1385,7 @@ function run_wormhole(timerPos, time_elapsed)
 end
 
 
-local function create_book(item_name, inventory_description, inventory_image, title, author, page1_text, page2_text)
+local function create_book(item_name, inventory_description, inventory_image, title, author, chapters)
 
 	local display_book = function(itemstack, user, pointed_thing)
 		local player_name = user:get_player_name()
@@ -1388,15 +1394,55 @@ local function create_book(item_name, inventory_description, inventory_image, ti
 
 		local formspec =
 		"size[18,12.122]" ..
+		"background[0,0;18,11;nether_book_background.png;true]"..
+		"image_button_exit[17.3,0;0.8,0.8;nether_book_close.png;;]"..
 
 		"label[3.1,0.5;" .. minetest.formspec_escape(title) .. "]" ..
-		"label[3.6,0.9;" .. author .. "]" ..
+		"label[3.6,0.9;" .. author .. "]"
 
-		"textarea[ 0.9,1.7;7.9,12.0;;" .. minetest.formspec_escape(page1_text) .. ";]" ..
+		local image_x_adj = -0.4
-		"textarea[10.1,0.8;7.9,12.9;;" .. minetest.formspec_escape(page2_text) .. ";]" ..
+		local image_width = 1.6
+		local image_padding = 0.06
 
-		"background[0,0;18,11;nether_book_background.png;true]"..
+		for i, chapter in ipairs(chapters) do
-		"image_button_exit[17.3,0;0.8,0.8;nether_book_close.png;;]"
+			local left = 0.9
+			local top = 1.7
+			local width = 7.9
+			local height = 12.0
+			local item_number = i
+			local items_on_page = math.floor(#chapters / 2)
+			if i > items_on_page then
+				-- page 2
+				left = 10.1
+				top = 0.8
+				height = 12.9
+				item_number = i - items_on_page
+				items_on_page = #chapters - items_on_page
+			end
+
+			local available_height = (height - top) / items_on_page
+			local y = top + (item_number - 1) * available_height
+
+			-- add chapter title
+			local title_height = 0
+			if chapter.title ~= nil then
+				title_height = 0.6
+				formspec = formspec .. "label[".. left + 1.5 .. ","
+					.. y .. ";      ──══♦♦♦◊   " .. minetest.formspec_escape(chapter.title) .. "   ◊♦♦♦══──]"
+			end
+
+			-- add chapter image
+			local x_offset = 0
+			if chapter.image ~= nil then
+				x_offset = image_width + image_x_adj + image_padding
+				formspec = formspec .. "image[" .. left + image_x_adj .. "," .. y + title_height .. ";" .. image_width .. ","
+					.. image_width * chapter.aspect .. ";" .. chapter.image .. "]"
+			end
+
+			-- add chapter text
+			formspec = formspec .. "textarea[" .. left + x_offset .. "," .. y + title_height .. ";" .. width - x_offset .. ","
+					.. available_height - title_height .. ";;" .. minetest.formspec_escape(chapter.text) .. ";]"
+		end
 
 		minetest.show_formspec(player_name, item_name, formspec)
 	end
@@ -1438,14 +1484,14 @@ end
 -- A book the player can read to lean how to build the different portals
 local function create_book_of_portals()
 
-	local page1_text
+	local chapters = {}
-	local page2_text = ""
 
+	local intro_text
 	-- tell the player how many portal types there are
 	if nether.registered_portals_count == 1 then
-		page1_text = S("In all my travels, and time spent in the Great Libraries, I have encountered no shortage of legends surrounding preternatural doorways said to open into other worlds, yet only one can I confirm as being more than merely a story.")
+		intro_text = S("In all my travels, and time spent in the Great Libraries, I have encountered no shortage of legends surrounding preternatural doorways said to open into other worlds, yet only one can I confirm as being more than merely a story.")
 	else
-		page1_text = S("In all my travels, and time spent in the Great Libraries, I have encountered no shortage of legends surrounding preternatural doorways said to open into other worlds, yet only @1 can I confirm as being more than merely stories.", nether.registered_portals_count)
+		intro_text = S("In all my travels, and time spent in the Great Libraries, I have encountered no shortage of legends surrounding preternatural doorways said to open into other worlds, yet only @1 can I confirm as being more than merely stories.", nether.registered_portals_count)
 	end
 
 	-- tell the player how to ignite portals
@@ -1453,27 +1499,31 @@ local function create_book_of_portals()
 	if ignition_item_name ~= nil and minetest.registered_items[ignition_item_name] ~= nil then
 		ignition_item_description = minetest.registered_items[ignition_item_name].description
 	end
-	page1_text = page1_text ..
+	intro_text = intro_text ..
-		S("\n\nThe key to opening such a doorway is to strike the frame with a @1, at which point the very air inside begins to crackle and glow.\n\n\n", string.lower(ignition_item_description))
+		S("\n\nThe key to opening such a doorway is to strike the frame with a @1, at which point the very air inside begins to crackle and glow.", string.lower(ignition_item_description))
+
+	chapters[#chapters + 1] = {text = intro_text}
 
 	-- Describe how to create each type of portal, or perhaps just give clues or flavor text,
 	-- but ensure the Nether is always listed first on the first page so other definitions can
 	-- refer to it (pairs() returns order based on a random hash).
-	local i = 1
+	local portalDefs_in_order = {}
 	if nether.registered_portals["nether_portal"] then
-		page1_text = page1_text .. nether.registered_portals["nether_portal"].book_of_portals_pagetext .. "\n\n\n"
+		portalDefs_in_order[#portalDefs_in_order + 1] = nether.registered_portals["nether_portal"]
-		i = i + 1
 	end
 	for portalName, portalDef in pairs(nether.registered_portals) do
 		if portalName ~= "nether_portal" then
-			if i <= nether.registered_portals_count / 2 then
+			portalDefs_in_order[#portalDefs_in_order + 1] = portalDef
-				page1_text = page1_text .. portalDef.book_of_portals_pagetext .. "\n\n\n"
-			else
-				page2_text = page2_text .. portalDef.book_of_portals_pagetext .. "\n\n\n"
-			end
-			i = i + 1
 		end
 	end
+	for _, portalDef in ipairs(portalDefs_in_order) do
+		chapters[#chapters + 1] = {
+			text   = portalDef.book_of_portals_pagetext,
+			image  = portalDef.shape.diagram_image_texture,
+			aspect = portalDef.shape.diagram_image_aspect,
+			title  = portalDef.title
+		}
+	end
 
 	local previouslyRegistered = minetest.registered_items["nether:book_of_portals"] ~= nil
 
@@ -1481,10 +1531,9 @@ local function create_book_of_portals()
 		"nether:book_of_portals",
 		S("Book of Portals"),
 		"nether_book_of_portals.png",
-		S("A treatise on Rifts and Portals"),
+		S("A definitive guide to Rifts and Portals"),
 		"Riccard F. Burton", -- perhaps a Richard F. Burton of an alternate universe
-		page1_text,
+		chapters
-		page2_text
 	)
 
 	if not previouslyRegistered and nether.PORTAL_BOOK_LOOT_WEIGHTING > 0 and nether.registered_portals_count > 0 then
@@ -1563,7 +1612,7 @@ function register_frame_node(frame_node_name)
 	extended_node_def.on_blast = function(pos, intensity)
 		if DEBUG then minetest.chat_send_all("portal frame material: blast") end
 		extinguish_portal(pos, frame_node_name, extended_node_def.replaced_by_portalapi.on_blast == nil)
-		if extended_node_def.replaced_by_portalapi.on_blast ~= nil then 
+		if extended_node_def.replaced_by_portalapi.on_blast ~= nil then
 			extended_node_def.replaced_by_portalapi.on_blast(pos, intensity)
 		else
 			minetest.remove_node(pos)
@@ -1745,6 +1794,8 @@ end
 
 -- The fallback defaults for registered portaldef tables
 local portaldef_default = {
+	title                        = S("Untitled portal"),
+	book_of_portals_pagetext     = S("We know almost nothing about this portal"),
 	shape                        = nether.PortalShape_Traditional,
 	wormhole_node_name           = "nether:portal",
 	wormhole_node_color          = 0,

portal_api.txt

@@ -5,8 +5,8 @@ The portal system used to get to the Nether can be used to create portals
 to other realms.
 
 Pick a node type to have your portals built from, a shape in which the
-portals must be built, and provide 3 functions for portals to find their 
+portals must be built, and provide 3 functions for portals to find their
-destination with: 
+destination with:
  * `find_realm_anchorPos(surface_anchorPos)`
  * `find_surface_anchorPos(realm_anchorPos)`
  * `is_within_realm(pos)`
@@ -16,7 +16,7 @@ Optionally decorate by choosing portal colors, particles, media etc.
 See `init.lua` and `portal_examples.lua` for examples of 3 different portals.
 
 Portal code is more efficient when each type of portal uses a different type
-of node to build its frame out of - consider creating your own node for 
+of node to build its frame out of - consider creating your own node for
 players to build portals from. 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
@@ -24,15 +24,15 @@ 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 
+created. Similarly, avoid using nodes which may be replaced by ABMs or
 docoration functions without triggering the node's `on_destruct` handler.
 
 
 Realms
 ------
 
-This API uses the concept of a "realm" for each type of portal. If a portal is 
+This API uses the concept of a "realm" for each type of portal. If a portal is
-outside its realm then it links to a portal inside the realm, if a portal is 
+outside its realm then it links to a portal inside the realm, if a portal is
 inside its realm then it links to the outside.
 
 You get to decide what consitutes your realm by implementing the function
@@ -47,7 +47,7 @@ any time a portal is opened it will use `find_surface_anchorPos()`.
 
 Note that the name "find_surface_anchorPos" is a Nether-centric misnomer, as
 different types of portals are free to use different definitions of a realm
-such that leaving the realm might not be synonymous with travelling to the 
+such that leaving the realm might not be synonymous with travelling to the
 surface.
 
 
@@ -55,18 +55,18 @@ Helper functions
 ----------------
 
 * `nether.volume_is_natural(minp, maxp)`: returns a boolean
-    * use this when determining where to spawn a portal, to avoid overwriting 
+    * 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 
+      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 
+* `nether.find_surface_target_y(target_x, target_z, portal_name)`: returns a
   suitable anchorPos
     * Can be used when implementing custom find_surface_anchorPos() functions
     * portal_name is optional, providing it allows existing portals on the
       surface to be reused.
 
-* `nether.find_nearest_working_portal(portal_name, anchorPos, distance_limit, y_factor)`: returns 
+* `nether.find_nearest_working_portal(portal_name, anchorPos, distance_limit, y_factor)`: returns
   (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
@@ -83,7 +83,7 @@ API functions
 Call these functions only at load time:
 
 * `nether.register_portal(name, portal_definition)`
-    * Returns true on success. Can return false if the portal definition 
+    * Returns true on success. Can return false if the portal definition
       clashes with a portal already registered by another mod, e.g. if the size
       and frame node is not unique.
       A false return value should be handled, you could:
@@ -95,18 +95,18 @@ Call these functions only at load time:
     * Unregisters the portal from the engine, and deletes the entry with key
       `name` from `nether.registered_portals` and associated internal tables.
     * Returns true on success
-    * You will probably never need to call this, it exists only for completeness. 
+    * You will probably never need to call this, it exists only for completeness.
 * `nether.register_portal_ignition_item(name, ignition_failure_sound)`
-    * ignition_failure_sound is optional, it plays any time an attempt to use 
+    * ignition_failure_sound is optional, it plays any time an attempt to use
       the item occurs if a portal is not ignited.
 * `nether.register_wormhole_node(name, nodedef_overrides)`
     * Can be used to register wormhole nodes with a different post_effect_color
       from the "nether:portal" node. "Post effect color" is the tint the world
-      takes on when you are standing inside a portal. `post_effect_color` is the 
+      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.
-    * After `register_wormhole_node()`, invoke `register_portal()` and include 
+    * After `register_wormhole_node()`, invoke `register_portal()` and include
-      `wormhole_node_name` in the portal_definition, assigning it the name of the 
+      `wormhole_node_name` in the portal_definition, assigning it the name of the
       new wormhole node.
 
 
@@ -117,10 +117,10 @@ Used by `nether.register_portal`.
 
     {
         frame_node_name     = "default:obsidian",
-        -- Required. For best results, have your portal constructed of a 
+        -- Required. For best results, have your portal constructed of a
         -- material nobody else is using.
 
-        shape = nether.PortalShape_Traditional, 
+        shape = nether.PortalShape_Traditional,
         -- Optional.
         -- Shapes available are:
         --     nether.PortalShape_Traditional (default)
@@ -135,7 +135,7 @@ Used by `nether.register_portal`.
 
         wormhole_node_color = 0,
         -- Optional. Defaults to 0/magenta.
-        -- A value from 0 to 7 corresponding to the color of pixels in 
+        -- A value from 0 to 7 corresponding to the color of pixels in
         -- nether_portals_palette.png:
         --     0 traditional/magenta
         --     1 black
@@ -151,8 +151,8 @@ Used by `nether.register_portal`.
         -- if not specified.
 
         particle_texture    = "image.png",
-        -- Optional. Hardware colouring (i.e. particle_color) is applied to 
+        -- Optional. Hardware colouring (i.e. particle_color) is applied to
-        -- this texture, use particle_texture_colored instead if you want to 
+        -- this texture, use particle_texture_colored instead if you want to
         -- use the colors of the image.
         -- Animation and particle scale may also be specified, e.g:
         -- particle_texture = {
@@ -164,7 +164,7 @@ Used by `nether.register_portal`.
         --          length = 1,
         --      },
         --      scale = 1.5
-        --  },      
+        --  },
         -- See lua_api.txt for Tile Animation definition
         -- Some animated and non-animated textures are provided by this mod:
         --     nether_particle.png          (original)
@@ -173,10 +173,23 @@ Used by `nether.register_portal`.
         --     nether_particle_anim3.png    (sparks)
         --     nether_particle_anim4.png    (particles)
 
+        title = "Gateway to Moria",
+        -- Optional. Provides a title for the portal.
+        -- Currently this title is only used by the Book of Portals.
+
+        book_of_portals_pagetext = "Everything I need the player to know",
+        -- Optional. Provides the text for the portal in the Book of Portals.
+        -- The Book of Portals is a book that can be found in chests, and
+        -- provides players with instructions on how to build and use the
+        -- portal, so be sure to mention the node type the frame must be built
+        -- from.
+        -- This can also provide flavortext or details about where the portal
+        -- will take the player.
+
         sounds = {
-            ambient    = <SimpleSoundSpec>, 
+            ambient    = <SimpleSoundSpec>,
-            -- if the ambient SimpleSoundSpec is a table it can also contain a 
+            -- if the ambient SimpleSoundSpec is a table it can also contain a
-            -- "length" int, which is the number of seconds to wait before 
+            -- "length" int, which is the number of seconds to wait before
             -- repeating the ambient sound. Default is 3.
             ignite     = <SimpleSoundSpec>,
             extinguish = <SimpleSoundSpec>,
@@ -185,7 +198,7 @@ Used by `nether.register_portal`.
         -- sounds is optional
 
         within_realm = function(pos),
-        -- Required. Return true if a portal at pos is in the realm, rather 
+        -- Required. Return true if a portal at pos is in the realm, rather
            than the surface world.
 
         find_realm_anchorPos = function(surface_anchorPos),
@@ -207,7 +220,7 @@ Used by `nether.register_portal`.
         -- are free to use different definitions of a realm such that leaving
         -- the realm might not be synonymous with travelling to the surface.
         -- If orientation is not specified then the orientation of the realm
-        -- portal will be used. 
+        -- portal will be used.
         -- If the location of an existing portal is returned then include the
         -- orientation, otherwise the existing portal could be overwritten by
         -- a new one with the orientation of the realm portal.

portal_examples.lua

@@ -75,22 +75,10 @@ if minetest.settings:get_bool("nether_enable_portal_example_floatlands", ENABLE_
 			},
 			scale = 1.5
 		},
-		book_of_portals_pagetext = S([[      ──══♦♦♦◊   The Floatlands   ◊♦♦♦══──
+		title = S("Floatlands Portal"),
+		book_of_portals_pagetext = S([[Requiring 21 blocks of ice, and constructed in the shape of a 3 × 3 platform with walls, or like a bowl. A finished platform is 2 blocks high, and 5 blocks wide at the widest in both directions.
 
-	Requiring 21 blocks of ice, and constructed in the shape of a 3 × 3 platform with walls, or like a bowl:
+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]],
-
-	      ┌─┬─┬─┐
-	┌─┼─┴─┴─┼─┐    Plan view (looking down from above)
-	├─┤               ├─┤
-	├─┤               ├─┤    five blocks wide
-	└─┼─┬─┬─┼─┘    in both directions
-	      └─┴─┴─┘
-
-	┌─┬─┬─┬─┬─┐    Side view (looking from either side)
-	└─┼─┼─┼─┼─┘
-	      └─┴─┴─┘          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 tremendous altitude.@1]],
 		floatlands_flavortext),
 
 		is_within_realm = function(pos) -- return true if pos is inside the Nether
@@ -129,22 +117,12 @@ if minetest.settings:get_bool("nether_enable_portal_example_surfacetravel", ENAB
 		shape               = nether.PortalShape_Circular,
 		frame_node_name     = "default:tinblock",
 		wormhole_node_color = 4, -- 4 is cyan
-		book_of_portals_pagetext = S([[      ──══♦♦♦◊   Surface portal   ◊♦♦♦══──
+		title = S("Surface Portal"),
+		book_of_portals_pagetext = S([[Requiring 16 blocks of tin and constructed in a circular fashion, a finished frame is seven blocks wide, seven blocks high, and stands vertically like a doorway.
 
-	Requiring 16 blocks of tin, the frame must be constructed in the following fashion:
+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 where the 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.]]),
-		      ┌═┼─┴─┴─┼═╗
-		┌═┼─┘               └─┼═╗
-		├─╢                           ├─╢
-		├─╢                           ├─╢    seven blocks wide
-		└─╚═╗               ┌═╡─┘    seven blocks high
-		      └─╚═╤═╤═┼─┘          in a circular shape
-		            └─┴─┴─┘                standing vertically, like a doorway
-
-	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