From 003288bc80ffd56384f6e8aefd9f86c9f29683a4 Mon Sep 17 00:00:00 2001 From: emptyshore Date: Mon, 1 Apr 2024 00:30:06 +0000 Subject: [PATCH] Update comments in the nether portals script (#4227) Co-authored-by: Mateusz Uzdowski Reviewed-on: https://git.minetest.land/MineClone2/MineClone2/pulls/4227 Reviewed-by: the-real-herowl Co-authored-by: emptyshore Co-committed-by: emptyshore --- mods/ITEMS/mcl_portals/portal_nether.lua | 41 ++++++++++++++++++++---- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/mods/ITEMS/mcl_portals/portal_nether.lua b/mods/ITEMS/mcl_portals/portal_nether.lua index 033d58d84..64f54a080 100644 --- a/mods/ITEMS/mcl_portals/portal_nether.lua +++ b/mods/ITEMS/mcl_portals/portal_nether.lua @@ -18,6 +18,13 @@ local log = function(level, message) minetest.log(level, string.format("[mcl_portals] %s", message)) end +-- Resources + +-- Issue that has a lot of context: https://git.minetest.land/MineClone2/MineClone2/issues/4120 +-- Minecraft portal mechanics: https://minecraft.fandom.com/wiki/Tutorials/Nether_portals +-- Flow diagram: https://docs.google.com/drawings/d/1WIl4pVuxgOxI3Ncxk4g6D1pL4Fyll3bQ-fX6L9yyiLw/edit +-- Useful boundaries: https://git.minetest.land/MineClone2/MineClone2/wiki/World-structure%3A-positions%2C-boundaries%2C-blocks%2C-chunks%2C-dimensions%2C-barriers-and-the-void + -- Setup -- === CAUTION === @@ -34,19 +41,39 @@ end -- want to recalculate SEARCH_DISTANCE_* and W_MAX too. local NETHER_COMPRESSION = 8 -- Maximum distance from the ideal build spot where active parts of portals are --- allowed to be placed. This would ideally be smaller (16 as in MC), but for mapgen --- performance reasons, the search area is clipped by chunk, so if very unlucky --- the actual area could be a quarter of the expected size. +-- allowed to be placed. +-- There is a tradeoff here between the "walking" distance (distance to walk in +-- the overworld to get a new nether portal exit, which we want to be as similar +-- to Minecraft as possible, which is 136 [16*8+8]), and the area available for +-- exit search (which we want to maximise). +-- For our mapgen performance reasons, our search area is clipped by chunk, so +-- in the unlucky corner case the worst-case build area could be a quarter of +-- the expected size. +-- For MC build distance of 16, which gives a build area of 1,089 X-Z blocks +-- [(16+16+1)*(16+16+1)]. To guarantee this area here, we'd need to pick a build +-- distance of 32 [(32+32+1)*(32+32+1)/4]. But build distance of 32 implies +-- walking distance of 264 [32*8+8], which is already quite far, so need to pick +-- the right tradeoff: +-- +-- Build dist Minimum build area Minimum walk distance +-- 48 2,401 392 +-- 32 1,089 264 +-- 24 625 200 +-- 16 289 136 local BUILD_DISTANCE_XZ = 24 -- The following two values define distance to search existing portal exits for. --- Roughly corresponds to Minecraft's "8 chunks away" for the overworld (17 +-- For context, Minecraft search is "8 chunks away" for the overworld (17 -- chunks centered on the ideal position), and "1 chunk away" for the nether (3 -- chunks centered on the ideal position). +-- To prevent portal splitting on spawned portals, we add one to the build +-- distance: spawned portals are 2-wide, so we need to make sure that we can +-- reach the second exit block (which can spawn in the direction away from the +-- player). -- The search is boundary-inclusive, meaning for position 0 in the overworld, --- search will be from -128 to 128. +-- search will be from -N to N. -- If you change this, keep in mind our exits table keying divisor is 256, so --- small changes might have outsize performance impact. With 128, at most 4 --- buckets will be searched. +-- small changes might have outsize performance impact. At <=128, max 4 buckets +-- are searched, at 200 max 9 buckets are searched. local SEARCH_DISTANCE_NETHER = BUILD_DISTANCE_XZ + 1 -- 25 local SEARCH_DISTANCE_OVERWORLD = SEARCH_DISTANCE_NETHER * NETHER_COMPRESSION -- 200 -- Limits of portal sizes (includes the frame)