Tweak world cycle, add documentation

lib/api.lua

@@ -1,12 +1,17 @@
+-- initialize API interface
 local api = {}
 
-api.SHORT_CYCLE		= 0.03	-- for particles and fast animations
-api.DEFAULT_CYCLE	=  0.1	-- for most effect types
-api.MEDIUM_CYCLE	=	 2.0	-- for ressource intensive tasks
-api.LONG_CYCLE		=  5.0	-- for write operations and skybox changes
+-- define various standard effect cycle lengths
+api.SHORT_CYCLE		=	0		-- for particles and fast animations (use GSCYCLE)
+api.DEFAULT_CYCLE	=	0.1	-- for most effect types
+api.MEDIUM_CYCLE	=	2.0	-- for ressource intensive tasks
+api.LONG_CYCLE		=	5.0	-- for write operations and skybox changes
 
+-- register new weather presets (like rain)
+-- @param name <string> Unique preset name, ideally prefixed
+-- @param conditions <table> A collection of required influences
+-- @param effects <table> A <table> containing all applied effects as keys and parameters as values
 function api.register_weather(name, conditions, effects)
-	-- TODO: check and sanitize
 	climate_mod.weathers[name] = {
 		conditions = conditions,
 		effects = effects,
@@ -14,6 +19,10 @@ function api.register_weather(name, conditions, effects)
 	}
 end
 
+-- register new weather effects (like particles)
+-- @param name <string> Unique effect name, ideally prefixed
+-- @param handler <function> A function to be called when the effect is active
+-- @param htype <string: start|tick|stop>  Determines when the function is called
 function api.register_effect(name, handler, htype)
 	-- check for valid handler types
 	if htype ~= "start" and htype ~= "tick" and htype ~= "stop" then
@@ -29,18 +38,32 @@ function api.register_effect(name, handler, htype)
 	table.insert(climate_mod.effects[name][htype], handler)
 end
 
+-- set cycle length of given effect
+-- @param name <string> Name of the affected effect
+-- @param cycle <number> Duration between function calls
 function api.set_effect_cycle(name, cycle)
 	climate_mod.cycles[name].timespan = cycle
 end
 
+-- register new environment influence that is independent of position
+-- @param name <string> Unique influence name
+-- @param func <function> Returns current influence value for entire world
 function api.register_global_influence(name, func)
 	climate_mod.global_influences[name] = func
 end
 
+-- register new environment influence based on position
+-- @param name <string> Unique influence name
+-- @param func <function> Returns current influence value for given position
 function api.register_influence(name, func)
 	climate_mod.influences[name] = func
 end
 
+-- register new Active Block Modifier dependent on weather status
+-- Uses same config as Minetest.register_abm() but also adds
+-- conditions similiar to weather presets and provides local environment
+-- to action event handler as third parameter.
+-- @param config <table> ABM configuration with additional information
 function api.register_abm(config)
 	if not climate_mod.settings.block_updates then return end
 
@@ -48,16 +71,21 @@ function api.register_abm(config)
 	local action = config.action
 	local pos_override = config.pos_override
 
+	-- override action handler to inject weather status
 	local override = function(pos, node)
-		local env = climate_mod.trigger.get_position_environment(pos)
 		if type(pos_override) == "function" then
 			pos = pos_override(pos)
+			node = minetest.get_node(pos)
 		end
 
+		-- get environment influences for current position
+		local env = climate_mod.trigger.get_position_environment(pos)
+
 		if conditions == nil then
 			return action(pos, node, env)
 		end
 
+		-- check if all conditions are met
 		for condition, goal in pairs(conditions) do
 			local is_applicable = climate_mod.trigger.test_condition(condition, env, goal)
 			if not is_applicable then return end
@@ -65,9 +93,11 @@ function api.register_abm(config)
 		return action(pos, node, env)
 	end
 
+	-- register overridden abm setup
 	config.conditions = nil
 	config.action = override
 	minetest.register_abm(config)
 end
 
+-- return supplied API endpoint
 return api

lib/commands.lua

@@ -1,3 +1,5 @@
+-- parse heat values into readable format
+-- also convert to Celsius if configured
 local function parse_heat(heat)
 	local indicator = "°F"
 	if not climate_mod.settings.fahrenheit then
@@ -8,11 +10,14 @@ local function parse_heat(heat)
 	return heat .. indicator
 end
 
+
+-- register weather privilege in order to modify the weather status
 minetest.register_privilege("weather", {
 	description = "Make changes to the current weather",
 	give_to_singleplayer = false
 })
 
+-- display general information on current weather
 minetest.register_chatcommand("weather", {
 	description ="Display weather information",
 	func = function(playername)
@@ -49,6 +54,7 @@ minetest.register_chatcommand("weather", {
 	end
 })
 
+-- set base heat to increase or decrease global climate temperatures
 minetest.register_chatcommand("set_heat", {
 	params = "<heat>",
 	description = "Override the weather algorithm's base heat",
@@ -63,6 +69,7 @@ minetest.register_chatcommand("set_heat", {
 	end
 })
 
+-- set base heat to increase or decrease global climate humidity
 minetest.register_chatcommand("set_humidity", {
 	params = "<humidity>",
 	description = "Override the weather algorithm's base humidity",
@@ -77,6 +84,7 @@ minetest.register_chatcommand("set_humidity", {
 	end
 })
 
+-- override wind direction and speed with given values
 minetest.register_chatcommand("set_wind", {
 	params = "<wind>",
 	description = "Override the weather algorithm's windspeed",
@@ -103,6 +111,7 @@ minetest.register_chatcommand("set_wind", {
 	end
 })
 
+-- display current mod config
 minetest.register_chatcommand("weather_settings", {
 	description = "Print the active Climate API configuration",
 	func = function(playername)
@@ -113,6 +122,7 @@ minetest.register_chatcommand("weather_settings", {
 	end
 })
 
+-- force a weather preset or disable it
 minetest.register_chatcommand("set_weather", {
 	params ="<weather> <status>",
 	description ="Turn the specified weather preset on or off for all players or reset it to automatic",
@@ -141,6 +151,7 @@ minetest.register_chatcommand("set_weather", {
 	end
 })
 
+-- list all weather presets and whether they have been forced or disabled
 minetest.register_chatcommand("weather_status", {
 	description = "Prints which weather presets are enforced or disabled",
 	func = function(playername)
@@ -157,6 +168,7 @@ minetest.register_chatcommand("weather_status", {
 	end
 })
 
+-- show all environment influences and their values for the executing player
 minetest.register_chatcommand("weather_influences", {
 	description = "Prints which weather influences cause your current weather",
 	func = function(playername)

lib/datastorage.lua

@@ -7,7 +7,7 @@ if not state:contains("noise_timer") then
 		humidity_base = 50,
 		wind_x = 0.5,
 		wind_z = 0.5,
-		noise_timer = math.random(0, 300000)
+		noise_timer = 0
 	})
 end
 

lib/main.lua

@@ -1,5 +1,5 @@
-local GSCYCLE = 0.03	* climate_mod.settings.tick_speed
-local WORLD_CYCLE = 2	* climate_mod.settings.tick_speed
+local GSCYCLE			=  0.03	* climate_mod.settings.tick_speed	-- only process event loop after this time amount
+local WORLD_CYCLE = 15.00	* climate_mod.settings.tick_speed	-- only update global environment influences after this time amount
 
 local gs_timer = 0
 local world_timer = 0

lib/trigger.lua

@@ -122,7 +122,6 @@ function trigger.call_handlers(name, effect, prev_effect)
 			has_ticks = true
 			ticks.current[player] = sources
 			ticks.prev[player] = prev_effect[player]
-			--prev_effect[player] = nil -- remove any found entries
 		else
 			has_starts = true
 			starts[player] = sources