Update mcl_time to v2

mods/CORE/mcl_time/README.md

@@ -1,4 +1,4 @@
-# mcl_time
+# mcl_time v2.0
 ## by kay27 for MineClone 5
 ---------------------------
 This mod counts time when all players sleep or some area is inactive.
@@ -15,13 +15,15 @@ Usually this value grow smoothly. But when you skip the night being in the bed,
 
 ### mcl_time.get_number_of_times(last_time, interval, chance)
 -------------------------------------------------------------
-Handy to process AMBs.
+Returns the number of how many times something would probably happen if the area was active and we didn't skip the nights.
 
-You pass `last_time` - last known value of `seconds_irl`, also ABM `interval` and ABM `chance`.
+Arguments:
+ * `last_time` - you pass last known for you value of `seconds_irl`
+ * `interval` and `chance` - interval and chance like from ABM setup
 
 Returns:
- * Integer number of how many times ABM function should be called if the area was active all the time and you didn't skip the night.
- * Integer value of realtime (not in-game) seconds since world creation.
+ * Integer number of how many times something would probably happen if the area was active all the time and we didn't skip the nights.
+ * Integer value of in-real-life (not in-game) seconds since world creation.
 
 ### mcl_time.touch(pos)
 -----------------------
@@ -29,24 +31,76 @@ This function 'toches' node at position `pos` by writing `_t` meta variable of `
 
 ### mcl_time.get_number_of_times_at_pos(pos, interval, chance)
 --------------------------------------------------------------
-Much more handy to call from LBM on area load, than `mcl_time.get_number_of_times()`!
+Returns the number of how many times something would probably happen for node at pos `pos` if the area was active and we didn't skip the nights.
+It reads and updates meta variable `_t` from position `pos` and uses it as previous `seconds_irl`, so we don't need to remember it.
 
-It reads meta variable `_t` from position `pos` and uses it as previous `seconds_irl`, which then pass as first argument into `mcl_time.get_number_of_times()`.
-After calling this, it also 'touches' the node at `pos` by writing `seconds_irl` into meta variable `_t`.
+Argunments:
+ * `pos` - node position
+ * `interval` and `chance` - interval and chance like from ABM setup
 
 Returns:
- * Integer number of how many times ABM function should be called if the area was active all the time and you didn't skip the night.
- * Integer value of realtime (not in-game) seconds since world creation.
-
-*Warning!* This function can return 0. So it's better not to use it for regular ABMs - use `mcl_time.get_number_of_times_at_pos_or_1()` instead.
+ * Integer number of how many times something would happen to the node at position `pos` if the area was active all the time and we didn't skip the nights.
+ * For unclear conditions, like missing meta or zero `time_speed`, this function will return `0`.
 
 ### mcl_time.get_number_of_times_at_pos_or_1(pos, interval, chance)
 -------------------------------------------------------------------
-Much more handy to process ABMs than `mcl_time.get_number_of_times()` and `mcl_time.get_number_of_times_at_pos()`!
+Returns the number of how many times something would probably happen for node at pos `pos` if the area was active and we didn't skip the nights.
+It reads and updates meta variable `_t` from position `pos` and uses it as previous `seconds_irl`, so we don't need to remember it.
 
-It just calls `mcl_time.get_number_of_times_at_pos()` but doesn't return 0, the minimum number it can return is 1,
-which is the most suitable for regular ABM processing function.
+Argunments:
+ * `pos` - node position
+ * `interval` and `chance` - interval and chance like from ABM setup
 
 Returns:
- * Integer number of how many times ABM function should be called if the area was active all the time and you didn't skip the night.
- * Integer value of realtime (not in-game) seconds since world creation.
+ * Integer number of how many times something would happen to the node at position `pos` if the area was active all the time and we didn't skip the nights.
+ * For unclear conditions, like missing meta or zero `time_speed`, this function will return `1`.
+
+### mcl_time.get_number_of_times_at_pos_or_nil(pos, interval, chance)
+---------------------------------------------------------------------
+Returns the number of how many times something would probably happen for node at pos `pos` if the area was active and we didn't skip the nights.
+It reads and updates meta variable `_t` from position `pos` and uses it as previous `seconds_irl`, so we don't need to remember it.
+
+Argunments:
+ * `pos` - node position
+ * `interval` and `chance` - interval and chance like from ABM setup
+
+Returns:
+ * Integer number of how many times something would happen to the node at position `pos` if the area was active all the time and we didn't skip the nights.
+ * For unclear conditions, like missing meta or zero `time_speed`, this function will return `nil`.
+
+### mcl_time.get_irl_seconds_passed_at_pos(pos)
+-----------------------------------------------
+Returns the number of how many in-real-life seconds would be passed for the node at position `pos`, if the area was active all the time and we didn't skip the nights.
+It uses node meta variable `_t` to calculate this value.
+
+Argunments:
+ * `pos` - node position
+
+Returns:
+ * Integer number of how many in-real-life seconds would be passed for the node at position `pos, if the area was active all the time and we didn't skip the nights.
+ * For unclear conditions, like missing meta or zero `time_speed`, this function will return `0`.
+
+### mcl_time.get_irl_seconds_passed_at_pos_or_1(pos)
+----------------------------------------------------
+Returns the number of how many in-real-life seconds would be passed for the node at position `pos`, if the area was active all the time and we didn't skip the nights.
+It uses node meta variable `_t` to calculate this value.
+
+Argunments:
+ * `pos` - node position
+
+Returns:
+ * Integer number of how many in-real-life seconds would be passed for the node at position `pos, if the area was active all the time and we didn't skip the nights.
+ * For unclear conditions, like missing meta or zero `time_speed`, this function will return `1`.
+
+### mcl_time.get_irl_seconds_passed_at_pos_or_nil(pos)
+----------------------------------------------------
+Returns the number of how many in-real-life seconds would be passed for the node at position `pos`, if the area was active all the time and we didn't skip the nights.
+It uses node meta variable `_t` to calculate this value.
+
+Argunments:
+ * `pos` - node position
+
+Returns:
+ * Integer number of how many in-real-life seconds would be passed for the node at position `pos, if the area was active all the time and we didn't skip the nights.
+ * For unclear conditions, like missing meta or zero `time_speed`, this function will return `nil`.
+

mods/CORE/mcl_time/init.lua

@@ -76,14 +76,14 @@ local function time_runner()
 end
 
 function mcl_time.get_number_of_times(last_time, interval, chance)
-	if not last_time then return 0 end
-	if seconds_irl_public < 2 then return 0 end
-	if not interval then return 0 end
-	if not chance then return 0 end
-	if interval < 1 then return 0 end
-	if chance < 1 then return 0 end
+	if not last_time then return 0, seconds_irl_publicend end
+	if seconds_irl_public < 2 then return 0, seconds_irl_public end
+	if not interval then return 0, seconds_irl_public end
+	if not chance then return 0, seconds_irl_public end
+	if interval < 1 then return 0, seconds_irl_public end
+	if chance < 1 then return 0, seconds_irl_public end
 	local number_of_intervals = (seconds_irl_public - last_time) / interval
-	if number_of_intervals < 1 then return 0 end
+	if number_of_intervals < 1 then return 0, seconds_irl_public end
 	local average_chance = (1 + chance) / 2
 	local number_of_times = math.floor(number_of_intervals / average_chance)
 	return number_of_times, seconds_irl_public
@@ -98,45 +98,56 @@ end
 
 function mcl_time.get_number_of_times_at_pos(pos, interval, chance)
 	if not pos then return 0 end
+	if not time_speed_is_ok then return 0 end
 	local meta = minetest.get_meta(pos)
 	local last_time = meta:get_int(meta_name)
-	local number_of_times = (last_time == 0) and 0 or get_number_of_times(last_time, interval, chance)
 	meta:set_int(meta_name, seconds_irl_public)
-	return number_of_times, seconds_irl_public
+	local number_of_times = (last_time == 0) and 0 or get_number_of_times(last_time, interval, chance)
+	return number_of_times
 end
 
 local get_number_of_times_at_pos = mcl_time.get_number_of_times_at_pos
 
 function mcl_time.get_number_of_times_at_pos_or_1(pos, interval, chance)
-	return math.max(get_number_of_times_at_pos(pos, interval, chance), 1), seconds_irl_public
+	return math.max(get_number_of_times_at_pos(pos, interval, chance), 1)
+end
+
+function mcl_time.get_number_of_times_at_pos_or_nil(pos, interval, chance)
+	local number_of_times_at_pos = get_number_of_times_at_pos(pos, interval, chance)
+	if number_of_times_at_pos > 0 then
+		return number_of_times_at_pos
+	end
 end
 
 function mcl_time.get_irl_seconds_passed_at_pos(pos)
 	if not pos then return 0 end
+	if not time_speed_is_ok then return 0 end
 	local meta = minetest.get_meta(pos)
 	local last_time = meta:get_int(meta_name)
-	local irl_seconds_passed = (last_time == 0) and 0 or (seconds_irl_public - last_time)
 	meta:set_int(meta_name, seconds_irl_public)
+	local irl_seconds_passed = (last_time == 0) and 0 or (seconds_irl_public - last_time)
 	return irl_seconds_passed
 end
 
 function mcl_time.get_irl_seconds_passed_at_pos_or_1(pos)
 	if not pos then return 1 end
+	if not time_speed_is_ok then return 1 end
 	local meta = minetest.get_meta(pos)
 	local last_time = meta:get_int(meta_name)
-	local irl_seconds_passed = (last_time == 0) and 1 or (seconds_irl_public - last_time)
 	meta:set_int(meta_name, seconds_irl_public)
+	local irl_seconds_passed = (last_time == 0) and 1 or (seconds_irl_public - last_time)
 	return irl_seconds_passed
 end
 
 function mcl_time.get_irl_seconds_passed_at_pos_or_nil(pos)
 	if not pos then return end
+	if not time_speed_is_ok then return end
 	local meta = minetest.get_meta(pos)
 	local last_time = meta:get_int(meta_name)
+	meta:set_int(meta_name, seconds_irl_public)
 	if last_time == 0 then return end
 	local delta_time = seconds_irl_public - last_time
 	if delta_time <= 0 then return end
-	meta:set_int(meta_name, seconds_irl_public)
 	return delta_time
 end