From e765f5f504ef7960a8d3c2d0ab4cf29f31bfa9bd Mon Sep 17 00:00:00 2001 From: Treer Date: Thu, 9 Jan 2020 00:27:43 +1100 Subject: [PATCH] text/docs/formatting changes --- init.lua | 11 ++++++++--- portal_api.txt | 42 +++++++++++++++++++++++++++++++++--------- 2 files changed, 41 insertions(+), 12 deletions(-) diff --git a/init.lua b/init.lua index ba5dce5..a5255a3 100644 --- a/init.lua +++ b/init.lua @@ -106,7 +106,9 @@ if nether.NETHER_REALM_ENABLED then destination_pos.y = nether.DEPTH - 1000 -- 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 = nether.find_nearest_working_portal("nether_portal", destination_pos, 8, 0) + local existing_portal_location, existing_portal_orientation = + nether.find_nearest_working_portal("nether_portal", destination_pos, 8, 0) + if existing_portal_location ~= nil then return existing_portal_location, existing_portal_orientation else @@ -119,7 +121,8 @@ if nether.NETHER_REALM_ENABLED then find_surface_anchorPos = function(realm_anchorPos) -- A portal definition doesn't normally need to provide a find_surface_anchorPos() function, -- since find_surface_target_y() will be used by default, but Nether portals also scale position - -- to create fast-travel. Defining a custom function also means we can look for existing nearby portals: + -- to create fast-travel. + -- Defining a custom function also means we can look for existing nearby portals. -- Multiply x and z by a factor of 8 to implement Nether fast-travel local destination_pos = vector.multiply(realm_anchorPos, nether.FASTTRAVEL_FACTOR) @@ -128,7 +131,9 @@ if nether.NETHER_REALM_ENABLED then destination_pos.y = 0 -- 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.find_nearest_working_portal("nether_portal", destination_pos, 8 * nether.FASTTRAVEL_FACTOR, 0) + local existing_portal_location, existing_portal_orientation = + nether.find_nearest_working_portal("nether_portal", destination_pos, 8 * nether.FASTTRAVEL_FACTOR, 0) + if existing_portal_location ~= nil then return existing_portal_location, existing_portal_orientation else diff --git a/portal_api.txt b/portal_api.txt index a906bcf..59ac4b0 100644 --- a/portal_api.txt +++ b/portal_api.txt @@ -23,8 +23,8 @@ using the same node as 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 -created. Similarly, avoid using nodes which may be replaced by ABMs etc. in the -game without the node's on_destruct being triggered. +created. Similarly, avoid using nodes which may be replaced by ABMs or +docoration functions without the node's `on_destruct` being triggered. Realms @@ -37,7 +37,16 @@ inside its realm then it links to the outside. You get to decide what consitutes your realm by implementing the function `is_within_realm(position)`. -The Nether realm, for example, is defined as existing at a certain depth. +For example, the Nether realm is defined as existing at a certain depth and +anything above that depth is considered outside the Realm. + +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 +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 surface. Helper functions @@ -104,8 +113,17 @@ Portal definition Used by `nether.register_portal`. { - shape = PortalShape_Traditional, - -- Optional. Defaults to PortalShape_Traditional + frame_node_name = "default:obsidian", + -- Required. For best results, have your portal constructed of a + -- material nobody else is using. + + shape = nether.PortalShape_Traditional, + -- Optional. + -- Shapes available are: + -- nether.PortalShape_Traditional (default) + -- nether.PortalShape_Circular + -- nether.PortalShape_Platform + -- New shapes can be created, but are beyond the scope of this guide. wormhole_node_name = "nether:portal", -- Optional. Allows a custom wormhole node to be specified. @@ -145,10 +163,12 @@ Used by `nether.register_portal`. -- scale = 1.5 -- }, -- See lua_api.txt for Tile Animation definition - - frame_node_name = "default:obsidian", - -- Required. For best results, have your portal constructed of a - -- material nobody else is using. + -- Some animated and non-animated textures are provided by this mod: + -- nether_particle.png (original) + -- nether_particle_anim1.png (stars) + -- nether_particle_anim2.png (bubbles) + -- nether_particle_anim3.png (sparks) + -- nether_particle_anim4.png (particles) sounds = { ambient = , @@ -179,6 +199,10 @@ Used by `nether.register_portal`. -- Optional. If you don't implement this then a position near the -- surface will be picked. -- Return an anchorPos or (anchorPos, orientation) + -- The name of this function is a Nether-centric misnomer. It should + -- return a position outside the realm, and 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 surface. -- If orientation is not specified then the orientation of the realm -- portal will be used. -- If the location of an existing portal is returned then include the