New effect type: repeating effects

This commit is contained in:
Wuzzy 2014-07-19 00:59:19 +02:00
parent aa5f78ef95
commit 87699ab3b2
3 changed files with 129 additions and 23 deletions

View File

@ -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 dont 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 cant 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 dont 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.

View File

@ -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
]]

View File

@ -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,