diff options
| -rw-r--r-- | README.md | 18 | ||||
| -rw-r--r-- | examples.lua | 38 | ||||
| -rw-r--r-- | init.lua | 96 |
3 files changed, 129 insertions, 23 deletions
@@ -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 ]] @@ -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, |