add a proper settingtypes.txt

having to go all at once.  This purges the log sooner than before,
but without damaging the mapgen results.

API.txt

@@ -607,34 +607,7 @@ Although this project was intended to be used with minetest_game, it can be
 configured to work with something else instead.  All you need to do is provide
 the names of the nodes in your game you want biome_lib's internals to use.
 
-Put these settings in your game's minetest.conf (or your client's own config,
-if desired).  You'll need to set all of them.
+See settingtypes.txt for a list.  Any item listed there can be changed either
+by adding it to your minetest.conf, or by using the "all settings" menu in
+Minetest, whatever's appropriate for your particular setup.
 
-biome_lib_default_grow_through_nodes
-	Comma-separated list of things that a spawned node is allowed to grow
-	through.  Air is always added to whatever you specify.
-	Default:  air, default:snow
-
-biome_lib_default_water_nodes
-	Comma-separated list of nodes that should be treated as water for the sake
-	of looking for neighboring "wet" ground.
-	Default: default:water_source, default:water_flowing,
-		default:river_water_source, default:river_water_flowing
-
-biome_lib_default_wet_surfaces
-	Comma-separated list of nodes that should be considered "wet" if one of
-	the aforementioned water nodes is nearby.
-	Default: default:dirt, default:dirt_with_grass, default:sand
-
-biome_lib_default_grow_nodes
-	Comma-separated list of nodes that something must be sitting on to be
-	able to actively change from one thing to another (such as a sapling
-	growing into a tree), to be used for ALL growable nodes, if the calling
-	mod doesn't provide its own lists.
-	Default: "default:dirt_with_grass"
-
-biome_lib_default_ground_nodes
-	Comma-separated list of nodes to use as the "root" of something that can
-	gradually climb up a wall, to be used for ALL such nodes, if the calling
-	mod doesn't provide its own lists.
-	Default: "default:dirt_with_grass"

init.lua

@@ -76,12 +76,21 @@ local rr = tonumber(minetest.settings:get("biome_lib_queue_run_ratio")) or -100
 biome_lib.queue_run_ratio = 100 - rr
 biome_lib.entries_per_step = math.max(-rr, 1)
 
--- timer runs in microseconds, but I want the user to supply a time in seconds
-biome_lib.block_timeout = (tonumber(minetest.settings:get("biome_lib_block_timeout")) or 300) * 1000000
+-- the timer that manages the block timeout is in microseconds, but the timer
+-- that manages the queue wakeup call has to be in seconds, and works best if
+-- it takes a fraction of the block timeout interval.
+
+local t = tonumber(minetest.settings:get("biome_lib_block_timeout")) or 300
+
+biome_lib.block_timeout = t * 1000000
+
+-- we don't want the wakeup function to trigger TOO often,
+-- in case the user's block timeout setting is really low
+biome_lib.block_queue_wakeup_time = math.min(t/2, math.max(20, t/10))
 
 local time_speed = tonumber(minetest.settings:get("time_speed"))
 
-biome_lib.plantlife_seed_diff = 329	-- needs to be global so other mods can see it
+biome_lib.plantlife_seed_diff = 329 -- needs to be global so other mods can see it
 
 local perlin_octaves = 3
 local perlin_persistence = 0.6
@@ -556,26 +565,74 @@ minetest.register_globalstep(function(dtime)
 	end
 end)
 
+-- Periodically wake-up the queue to give old blocks a chance to time-out
+-- if the player isn't currently exploring (i.e. they're just playing in one area)
+
+function biome_lib.wake_up_queue()
+	if #biome_lib.block_recheck_list > 1
+	  and #biome_lib.block_log == 0 then
+		biome_lib.block_log[#biome_lib.block_log + 1] =
+			table.copy(biome_lib.block_recheck_list[#biome_lib.block_recheck_list])
+		biome_lib.block_recheck_list[#biome_lib.block_recheck_list] = nil
+		biome_lib.run_block_recheck_list = true
+		biome_lib.dbg("Woke-up the map queue to give old blocks a chance to time-out.", 3)
+	end
+	minetest.after(biome_lib.block_queue_wakeup_time, biome_lib.wake_up_queue)
+end
+
+biome_lib.wake_up_queue()
+
 -- Play out the entire log all at once on shutdown
 -- to prevent unpopulated map areas
 
+local function format_time(t)
+	if t > 59999999 then
+		return os.date("!%M minutes and %S seconds", math.ceil(t/1000000))
+	else
+		return os.date("!%S seconds", math.ceil(t/1000000))
+	end
+end
+
+function biome_lib.check_remaining_time()
+	if minetest.get_us_time() > (biome_lib.shutdown_last_timestamp + 10000000) then -- report progress every 10s
+		biome_lib.shutdown_last_timestamp = minetest.get_us_time()
+
+		local entries_remaining = #biome_lib.block_log + #biome_lib.block_recheck_list
+
+		local total_purged = biome_lib.starting_count - entries_remaining
+		local elapsed_time = biome_lib.shutdown_last_timestamp - biome_lib.shutdown_start_time
+		biome_lib.dbg(string.format("%i entries, approximately %s remaining.",
+			entries_remaining, format_time(elapsed_time/total_purged * entries_remaining)))
+	end
+end
+
 minetest.register_on_shutdown(function()
-	if #biome_lib.block_log + #biome_lib.block_recheck_list == 0 then
+	biome_lib.shutdown_start_time = minetest.get_us_time()
+	biome_lib.shutdown_last_timestamp = minetest.get_us_time()+1
+
+	biome_lib.starting_count = #biome_lib.block_log + #biome_lib.block_recheck_list
+
+	if biome_lib.starting_count == 0 then
 		return
 	end
 
-	biome_lib.dbg("[biome_lib] Stand by, playing out the rest of the mapblock log", 0)
-	biome_lib.dbg("(there are "..(#biome_lib.block_log + #biome_lib.block_recheck_list).." entries)...", 0)
+	biome_lib.dbg("Stand by, purging the mapblock log "..
+		"(there are "..(#biome_lib.block_log + #biome_lib.block_recheck_list).." entries) ...", 0)
+
 	while #biome_lib.block_log > 0 do
 		biome_lib.generate_block(true)
+		biome_lib.check_remaining_time()
 	end
 
 	if #biome_lib.block_recheck_list > 0 then
 		biome_lib.block_log = table.copy(biome_lib.block_recheck_list)
 		while #biome_lib.block_log > 0 do
 			biome_lib.generate_block(true)
+			biome_lib.check_remaining_time()
 		end
 	end
+	biome_lib.dbg("Log purge completed after "..
+		format_time(minetest.get_us_time() - biome_lib.shutdown_start_time)..".", 0)
 end)
 
 -- The spawning ABM
@@ -773,12 +830,18 @@ if biome_lib.debug_log_level >= 3 then
 
 	function biome_lib.show_pending_block_count()
 		if biome_lib.last_count ~= #biome_lib.block_log then
-			biome_lib.dbg("Pending block count: "..(#biome_lib.block_log + #biome_lib.block_recheck_list), 3)
+			biome_lib.dbg(string.format("Pending block counts - ready to process: %-8icurrently deferred: %i",
+				#biome_lib.block_log, #biome_lib.block_recheck_list), 3)
 			biome_lib.last_count = #biome_lib.block_log
 			biome_lib.queue_idle_flag = false
 		elseif not biome_lib.queue_idle_flag then
-			biome_lib.dbg("Mapblock queue only contains blocks that can't yet be processed.",  3)
-			biome_lib.dbg("Idling the queue until new mapblocks show up.",  3)
+			if #biome_lib.block_recheck_list > 0 then
+				biome_lib.dbg("Mapblock queue only contains blocks that can't yet be processed.",  3)
+				biome_lib.dbg("Idling the queue until new blocks arrive or the next wake-up call occurs.",  3)
+			else
+				biome_lib.dbg("Mapblock queue has run dry.",  3)
+				biome_lib.dbg("Idling the queue until new blocks arrive.",  3)
+			end
 			biome_lib.queue_idle_flag = true
 		end
 		minetest.after(1, biome_lib.show_pending_block_count)

settingtypes.txt

@@ -0,0 +1,48 @@
+# Comma-separated list of things that a spawned node is allowed to grow
+# through.  Air is always added to whatever else you specify here.
+biome_lib_default_grow_through_nodes (List of things a plant can grow through) string default:snow
+
+# Comma-separated list of nodes that should be treated as water or water-like
+# for the sake of looking for neighboring wet ground.
+biome_lib_default_water_nodes (List of "water-like" sources) string default:water_source,default:water_flowing,default:river_water_source,default:river_water_flowing
+
+# Comma-separated list of nodes that should be considered "wet" if one of
+# the configured "water-like" sources is nearby.
+biome_lib_default_wet_surfaces (List of "wet" nodes) string default:dirt,default:dirt_with_grass,default:sand
+
+# Comma-separated list of nodes that something must be sitting on to be
+# able to actively change from one thing to another (such as a sapling
+# growing into a tree), to be used if the mod that added that growable
+# thing didn't provide its own list of suitable surfaces.
+biome_lib_default_grow_nodes (List of default surfaces a plant can thrive on) string default:dirt_with_grass
+
+# Comma-separated list of nodes to use as the "root" of something that can
+# gradually climb up a wall (such as ivy), to be used if the mod that added
+# the climing thing didn't provide its own list.
+biome_lib_default_ground_nodes (List of default root nodes) string default:dirt_with_grass
+
+# biome_lib divides its workload into "actions", as dictated by the sum
+# total of all mods that use it, and this sets how much of that work is done
+# per globalstep tick.  If positive, a single action is executed on that
+# percentage of ticks, on average. If negative, it becomes positive, and
+# that many actions are executed on every single tick, skipping none.
+# More negative means more throughput, at the expense of lag.  On fast PC's,
+# a setting of between -500 and -2000 might be good.
+biome_lib_queue_run_ratio (Queue run ratio) int -100
+
+# Minetest's map generator allows neighboring areas to overflow into one
+# another, to create smooth terrain, but it often hands the map blocks that
+# comprise those areas to Lua (and hence, to biome_lib) before that overflow
+# function happens, which causes the mapgen to overwrite whatever Lua does
+# to them.  This setting (in seconds) makes biome_lib wait before adding its
+# normal output to those map blocks, to give the engine plenty of time to
+# run that overflow feature first.
+biome_lib_block_timeout (Deferred block timeout) int 300
+
+# This does just what it sounds like - it shows all debug output that's sent
+# with a level equal to or greater than this value.  A setting of 0 shows only
+# the bare necessities, such as the startup and shutdown messages, 1 adds
+# internal non-fatal errors to what's shown, 2 adds warnings, 3 adds other
+# basic info, 4 adds all the verbose debugging spew. 3 is perhaps the most
+# useful setting.
+biome_lib_debug_log_level (Debug log level) int 0