New effect type: repeating effects

3 files changed, 129 insertions, 23 deletions

diff --git a/README.md b/README.md
index d5acf0d..5dda127 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ When you paused the game in singleplayer mode, the effect timers just continue a
 ## API documentation
 ### Data types
 #### Effect type (`effect_type`)
-An effect type is a description of what is later to be concretely applied as an effect to a player. An effect type, however, is *not* assigned to a player.
+An effect type is a description of what is later to be concretely applied as an effect to a player. An effect type, however, is *not* assigned to a player. There are two kinds of effect types: Repeating and non-repeating. See the section on `effect` for more information.
 
 `effect_type` is a table with these fields:
 
@@ -57,6 +57,7 @@ An effect type is a description of what is later to be concretely applied as an
 * `icon`: This is optional. It can be the file name of a texture. Should have a size of 16px×16px. Will be exposed to the HUD, iff `hidden` is `false`.
 * `hidden`: Iff this is false, it will not be exposed to the HUD when this effect is active.
 * `cancel_on_death`: Iff this is true, the effect will be cancelled automatically when the player dies.
+* `repeat_interval` is an optional number. When specified, the effects of this type becomes a repeating effect. Repeating effects call `apply` an arbitrary number of times; non-repeating effects just call it once when the effect is created. The number specifies the interval in seconds between each call. Iff this parameter is `nil`, the effect type is a non-repeating effect.
 
 Normally you don’t need to read or edit fields of this table. Use `playereffects.register_effect_type` to add a new effect type to Player Effects.
 
@@ -70,7 +71,7 @@ The concept of groups may be changed or extended in the future.
 You can invent effect groups (like the groups in Minetest) on the fly. A group is just a string. Practically, you should use groups which other people use.
 
 #### Effect (`effect`)
-An effect is an current change of a player property (like speed, jump height, and so on). It is the realization of an effect type. All effects are temporary.
+An effect is an current change of a player property (like speed, jump height, and so on). It is the realization of an effect type. All effects are temporary. There are currently two types of effects: Repeating and non-repeating. Non-repeating effects call their `apply` callback once when they are created. Repeating effects call their apply callback multiple times with a specified interval. By default, effects are non-repeating.
 
 `effect` is a table with the following modding-relevant fields:
 
@@ -83,12 +84,13 @@ Internally, Player Effects also uses these fields:
 
 * `start_time`: The operating system time (from `os.time()`) of when the effect has been started.
 * `time_left`: The number of seconds left before the effect runs out. This number is only set when the effect starts or the effect is unfrozen because i.e. a player re-joins. You can’t use this field to blindly get the remaining time of the effect.
+* `repeat_interval_start_time` and `repeat_interval_time_left`: Same as `start_time` and `time_left`, but for repeating effects.
 
 You should normally not need to care about these internally used fields.
 
 
 ### Functions
-#### `playereffects.register_effect_type(effect_type_id, description, icon, groups, apply, cancel, hidden, cancel_on_death)`
+#### `playereffects.register_effect_type(effect_type_id, description, icon, groups, apply, cancel, hidden, cancel_on_death, repeat_interval)`
 Adds a new effect type for the Player Effects mods, so it can be later be applied to players.
 
 ##### Parameters
@@ -100,6 +102,7 @@ Adds a new effect type for the Player Effects mods, so it can be later be applie
 * `cancel`: See below.
 * `hidden` is an optional boolean value. Iff `true`, the effect description and icon will not be exposed to the player HUD. Otherwise, the effect is exposed. Default: `false`
 * `cancel_on_death` is an optional boolean value. Iff true, the effect will be cancelled automatically when the player dies. Default: `true`.
+* `repeat_interval` is an optional number. When specified, the effects of this type becomes a repeating effect. Repeating effects call `apply` an arbitrary number of times; non-repeating effects just call it once when the effect is created. The number specifies the interval in seconds between each call. Iff this parameter is `nil`, the effect type is a non-repeating effect.
 
 
 ###### `apply` function
@@ -123,13 +126,14 @@ Player Effects does not care about the return value of this function.
 ##### Return value
 Always `nil`.
 
-#### `playereffects.apply_effect_type(effect_type_id, duration, player)`
-Attempts to apply a new effect of a certain type for a certain duration to a certain player. This function can fail, although this should rarely happen.
+#### `playereffects.apply_effect_type(effect_type_id, duration, player, repeat_interval_time_left)`
+Attempts to apply a new effect of a certain type for a certain duration to a certain player. This function can fail, although this should rarely happen. This function handles non-repeating effects and repeating effects as well.
 
 ##### Parameters
 * `effect_type_id`: The identifier of the effect type. This is the name which was used in `playereffects.register_effect_type` and always a string.
-* `duration`: How long the effect. Please use only positive values and only integers.
+* `duration`: How long the effect. Please use only positive values and only integers. If a repeating effect type is specified, this number specifies the number of repetitions; for non-repeating effects this number specifies the effect duration in seconds.
 * `player`: The player object to which the new effect should be applied to.
+* `repeat_interval_time_left`: This parameter is optional and only for repeating effects. If it is a number, it specifies the time until the first call of the `apply` callback fires. By default, a full repeat interval is waited until the first call.
 
 ##### Return value
 The function either returns `false` or a number. Iff the function returns `false`, the effect was not successfully applied. The function may return `false` on these occasions:
@@ -202,6 +206,8 @@ These commands apply (or try to) apply an effect to you. You will get a response
 * `hfast`: Makes you faster for 10s. This is a hidden effect and is not exposed to the HUD.
 * `highjump`: Increases your jump height for 20s.
 * `fly`: Gives you the `fly` privilege for a minute. You keep the privilege even when you die. Better don’t mess around with this privilege manually when you use this.
+* `regen`: Gives you a half heart per second 10 times (5 hearts overall healing). This is an example of a repeating effect.
+* `slowregen`: Gives you a half heart every 15 seconds, 10 times (5 hearts overall healing). This is an example of a repeating effect.
 * `blind`: Tints the whole screen black for 5 seconds. This is highly experimental and will be drawn over many existing HUD elements. In other words, prepare your HUD to be messed up.
 * `null`: Tries to apply an effect which always fails. This demonstrates the failure of effects.
 
diff --git a/examples.lua b/examples.lua
index 0a510d8..93c4980 100644
--- a/examples.lua
+++ b/examples.lua
@@ -102,6 +102,23 @@ playereffects.register_effect_type("fly", "Fly mode available", "playereffects_e
 	false  -- do NOT cancel the effect on death
 )
 
+-- Repeating effect type: Adds 1 HP per second
+playereffects.register_effect_type("regen", "Regeneration", "heart.png", {"health"},
+	function(player)
+		player:set_hp(player:get_hp()+1)
+	end,
+	nil, nil, nil, 1
+)
+
+-- Repeating effect type: Adds 1 HP per 3 seconds
+playereffects.register_effect_type("slowregen", "Slow Regeneration", "heart.png", {"health"},
+	function(player)
+		player:set_hp(player:get_hp()+1)
+	end,
+	nil, nil, nil, 15
+)
+
+
 -- Dummy effect for the stree test
 playereffects.register_effect_type("stress", "Stress Test Effect", nil, {},
 	function(player)
@@ -111,6 +128,7 @@ playereffects.register_effect_type("stress", "Stress Test Effect", nil, {},
 )
 
 
+
 ------ Chat commands for the example effects ------
 -- Null effect (never succeeds)
 minetest.register_chatcommand("null", {
@@ -179,6 +197,26 @@ minetest.register_chatcommand("fly", {
 	end,
 })
 
+minetest.register_chatcommand("regen", {
+	params = "",
+	description = "Gives you 1 half heart per second 10 times, healing you by 5 hearts in total.",
+	privs = {},
+	func = function(name, param)
+		local ret = playereffects.apply_effect_type("regen", 10, minetest.get_player_by_name(name))
+		notify(name, ret)
+	end,
+})
+
+minetest.register_chatcommand("slowregen", {
+	params = "",
+	description = "Gives you 1 half heart every 3 seconds 10 times, healing you by 5 hearts in total.",
+	privs = {},
+	func = function(name, param)
+		local ret = playereffects.apply_effect_type("slowregen", 10, minetest.get_player_by_name(name))
+		notify(name, ret)
+	end,
+})
+
 --[[
 	Cancel all active effects
 ]]
diff --git a/init.lua b/init.lua
index 7ae45ec..7b58ffc 100644
--- a/init.lua
+++ b/init.lua
@@ -71,7 +71,7 @@ function playereffects.next_effect_id()
 end
 
 --[=[ API functions ]=]
-function playereffects.register_effect_type(effect_type_id, description, icon, groups, apply, cancel, hidden, cancel_on_death)
+function playereffects.register_effect_type(effect_type_id, description, icon, groups, apply, cancel, hidden, cancel_on_death, repeat_interval)
 	effect_type = {}
 	effect_type.description = description
 	effect_type.apply = apply
@@ -92,12 +92,13 @@ function playereffects.register_effect_type(effect_type_id, description, icon, g
 	else
 		effect_type.cancel_on_death = true
 	end
+	effect_type.repeat_interval = repeat_interval
 
 	playereffects.effect_types[effect_type_id] = effect_type
 	minetest.log("action", "[playereffects] Effect type "..effect_type_id.." registered!")
 end
 
-function playereffects.apply_effect_type(effect_type_id, duration, player)
+function playereffects.apply_effect_type(effect_type_id, duration, player, repeat_interval_time_left)
 	local start_time = os.time()
 	local is_player = false
 	if(type(player)=="userdata") then
@@ -118,16 +119,18 @@ function playereffects.apply_effect_type(effect_type_id, duration, player)
 		playereffects.cancel_effect_group(v, playername)
 	end
 
-	local status = playereffects.effect_types[effect_type_id].apply(player)
 	local metadata
-
-	if(status == false) then
-		minetest.log("action", "[playereffects] Attempt to apply effect type "..effect_type_id.." to player "..playername.." failed!")
-		return false
-	else
-		metadata = status
+	if(playereffects.effect_types[effect_type_id].repeat_interval == nil) then
+		local status = playereffects.effect_types[effect_type_id].apply(player)
+		if(status == false) then
+			minetest.log("action", "[playereffects] Attempt to apply effect type "..effect_type_id.." to player "..playername.." failed!")
+			return false
+		else
+			metadata = status
+		end
 	end
 
+
 	local effect_id = playereffects.next_effect_id()
 	local smallest_hudpos
 	local biggest_hudpos = -1
@@ -154,10 +157,18 @@ function playereffects.apply_effect_type(effect_type_id, duration, player)
 	else
 		free_hudpos = biggest_hudpos + 1
 	end
+
+	local repeat_interval = playereffects.effect_types[effect_type_id].repeat_interval
+	if(repeat_interval ~= nil) then
+		if(repeat_interval_time_left == nil) then
+			repeat_interval_time_left = repeat_interval
+		end
+	end
+
 	--[[ show no more than 20 effects on the screen, so that hud_update does not need to be called so often ]]
 	local text_id, icon_id
 	if(free_hudpos <= 20) then
-		text_id, icon_id = playereffects.hud_effect(effect_type_id, player, free_hudpos, duration)
+		text_id, icon_id = playereffects.hud_effect(effect_type_id, player, free_hudpos, duration, repeat_interval_time_left)
 		local hudinfo = {
 				text_id = text_id,
 				icon_id = icon_id,
@@ -173,18 +184,49 @@ function playereffects.apply_effect_type(effect_type_id, duration, player)
 			effect_id = effect_id,
 			effect_type_id = effect_type_id,
 			start_time = start_time,
+			repeat_interval_start_time = start_time,
 			time_left = duration,
+			repeat_interval_time_left = repeat_interval_time_left,
 			metadata = metadata,
 	}
 
 	playereffects.effects[effect_id] = effect
 
 --	minetest.log("action", "[playereffects] Effect type "..effect_type_id.." applied to player "..playername.." (effect_id = "..effect_id..").")
-	minetest.after(duration, function(effect_id) playereffects.cancel_effect(effect_id) end, effect_id)
+	if(repeat_interval ~= nil) then
+		minetest.after(repeat_interval_time_left, playereffects.repeater, effect_id, duration, player, playereffects.effect_types[effect_type_id].apply)
+	else
+		minetest.after(duration, function(effect_id) playereffects.cancel_effect(effect_id) end, effect_id)
+	end
 
 	return effect_id
 end
 
+function playereffects.repeater(effect_id, repetitions, player, apply)
+	local effect = playereffects.effects[effect_id]
+	if(effect ~= nil) then
+		local repetitions = effect.time_left
+		apply(player)
+		repetitions = repetitions - 1
+		effect.time_left = repetitions
+		if(repetitions <= 0) then
+			playereffects.cancel_effect(effect_id)
+		else
+			local repeat_interval = playereffects.effect_types[effect.effect_type_id].repeat_interval
+			effect.repeat_interval_time_left = repeat_interval
+			effect.repeat_interval_start_time = os.time()
+			minetest.after(
+				repeat_interval,
+				playereffects.repeater,
+				effect_id,
+				repetitions,
+				player,
+				apply
+			)
+		end
+	end
+end
+
 function playereffects.cancel_effect_type(effect_type_id, cancel_all, playername)
 	local effects = playereffects.get_player_effects(playername)
 	if(cancel_all==nil) then all = false end
@@ -272,12 +314,20 @@ function playereffects.save_to_file()
 		end
 	end
 	for id,effect in pairs(playereffects.effects) do
-		local new_duration = effect.time_left - os.difftime(save_time, effect.start_time)
+		local new_duration, new_repeat_duration
+		if(playereffects.effect_types[effect.effect_type_id].repeat_interval ~= nil) then
+			new_duration = effect.time_left
+			new_repeat_duration = effect.repeat_interval_time_left - os.difftime(save_time, effect.repeat_interval_start_time)
+		else
+			new_duration = effect.time_left - os.difftime(save_time, effect.start_time)
+		end
 		local new_effect = {
 			effect_id = effect.effect_id,
 			effect_type_id = effect.effect_type_id,
 			time_left = new_duration,
+			repeat_interval_time_left = new_repeat_duration,
 			start_time = effect.start_time,
+			repeat_interval_start_time = effect.repeat_interval_start_time,
 			playername = effect.playername,
 			metadata = effect.metadata
 		}
@@ -346,7 +396,7 @@ minetest.register_on_joinplayer(function(player)
 	if(playereffects.inactive_effects[playername] ~= nil) then
 		for i=1,#playereffects.inactive_effects[playername] do
 			local effect = playereffects.inactive_effects[playername][i]
-			playereffects.apply_effect_type(effect.effect_type_id, effect.time_left, player)
+			playereffects.apply_effect_type(effect.effect_type_id, effect.time_left, player, effect.repeat_interval_time_left)
 		end
 		playereffects.inactive_effects[playername] = nil
 	end
@@ -388,8 +438,14 @@ function playereffects.hud_update(player)
 				local effect = playereffects.effects[effect_id]
 				if(effect ~= nil and hudinfo.text_id ~= nil) then
 					local description = playereffects.effect_types[effect.effect_type_id].description
-					local time_left = os.difftime(effect.start_time + effect.time_left, now)
-					player:hud_change(hudinfo.text_id, "text", description .. " ("..tostring(time_left).." s)")
+					local repeat_interval = playereffects.effect_types[effect.effect_type_id].repeat_interval
+					if(repeat_interval ~= nil) then
+						local repeat_interval_time_left = os.difftime(effect.repeat_interval_start_time + effect.repeat_interval_time_left, now)
+						player:hud_change(hudinfo.text_id, "text", description .. " ("..tostring(effect.time_left).."/"..tostring(repeat_interval_time_left) .. "s )")
+					else
+						local time_left = os.difftime(effect.start_time + effect.time_left, now)
+						player:hud_change(hudinfo.text_id, "text", description .. " ("..tostring(time_left).." s)")
+					end
 				end
 			end
 		end
@@ -415,7 +471,7 @@ function playereffects.hud_clear(player)
 	end
 end
 
-function playereffects.hud_effect(effect_type_id, player, pos, time_left)
+function playereffects.hud_effect(effect_type_id, player, pos, time_left, repeat_interval_time_left)
 	local text_id, icon_id
 	local effect_type = playereffects.effect_types[effect_type_id]
 	if(playereffects.use_hud == true and effect_type.hidden == false) then
@@ -425,11 +481,17 @@ function playereffects.hud_effect(effect_type_id, player, pos, time_left)
 		else
 			color = 0xF0BAFF
 		end
+		local description = playereffects.effect_types[effect_type_id].description
+		if(repeat_interval_time_left ~= nil) then
+			text =  description .. " ("..tostring(time_left).."/"..tostring(repeat_interval_time_left) .. "s )"
+		else
+			text = description .. " ("..tostring(time_left).." s)"
+		end
 		text_id = player:hud_add({
 			hud_elem_type = "text",
 			position = { x = 1, y = 0.3 },
 			name = "effect_"..effect_type_id,
-			text = playereffects.effect_types[effect_type_id].description .. " ("..tostring(time_left).." s)",
+			text = text,
 			scale = { x = 170, y = 20},
 			alignment = { x = -1, y = 0 },
 			direction = 1,