mirror of
https://repo.or.cz/minetest_playereffects.git
synced 2025-01-08 10:20:15 +01:00
New effect type: repeating effects
This commit is contained in:
Wuzzy
parent
aa5f78ef95
commit
87699ab3b2
18
README.md
18
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.
|
||||
|
||||
|
||||
38
examples.lua
38
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
|
||||
]]
|
||||
|
||||
96
init.lua
96
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,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user