descriptionA Minetest mod which provides an API to add temporary status effects for players.
last changeSun, 13 Nov 2016 17:25:41 +0000 (13 18:25 +0100)
content tags

Player Effects


This is an framework for assigning temporary status effects to players. This mod is aimed to modders and maybe interested people. This framework is a work in progress and not finished.


Information for players

This mod alone is not aimed directly at players. Briefly, the point of this mod is to help other mods to implement temporary status effects for players in a clean and consistant way. Here is the information which may be relevant to you: Your current status effects are shown on the HUD on the right side, along with a timer which shows the time until the effect gets disabled. It is possible for the server to disable this feature entirely. Some status effects may also be hidden and are never exposed to the HUD.

You only have to install this mod iff you have a mod which implements Player Effects. Here is a list of known mods which do:

Information for server operators

By default, this mod stores the effects into the file in the current world path every 10 seconds. On a regular server shutdown, this file is also written to. The data in this file is read when the mod is started.

It is save to delete when the mod does currently not run. This simply erases all active and inactive effects when the server starts again.

You can disable the automatic saving in settings.lua.


Player Effects can be configured. Just edit the file settings.lua. You find everything you need to know in that file. Be careful to not delete the lines, just edit them.

Information for modders

This is a framework for other mods to depend on. It provides means to define, apply and remove temporary status effects to players in a (hopefully) unobstrusive way. A status effect is an effect for a player which changes some property of the player. This property can be practically everything. Currently, the framework supports one kind of effect, which I call “exclusive effects”. For each property (speed, gravity, whatver), there can be only one effect in place at the same time. Here are some examples for possible status effects:

The framework aims to provide means to define effect types and to apply and cancel effects to players. The framework aims to be a stable foundation stone. This means it needs a lot of testing.

Known bugs

Effect timers don’t stop when game gets paused

When you paused the game in singleplayer mode, the effect timers just continue as if nothing happened. Of course, all effect timers should be stopped while the game is paused, like everything else. Apparently this bug cannot be fixed with the current Lua API.

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. 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:

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.

Effect group

An effect group is basically a concept. Any effect type can be member of any number of effect groups. The main point of effect groups is to find effects which affect the same property. For example, an effect which makes you faster and another effect which makes you slower both affect the same property: speed. The group for that then would be the string "speed". See also examples.lua, which includes the effects high_speed and low_speed.

Currently, the main rule of Player Effects requires that there can only be one effect in place. Don’t worry, Player Effects already does that job for you. Back to the example: it is possible to be fast and it is possible to be slow. But it is not possible to be fast and slow at the same time. Player Effects ensures that by cancelling all conflicting concepts before applying a new one.

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. 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:

Internally, Player Effects also uses these fields:

You should normally not need to care about these internally used fields.


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.

apply function

The apply function is a callback function which is called by Player Effects. Here the modder can put all the gameplay-relevant code.

apply takes a player object as its only argument. This is the player to which the effect is applied to.

The function may return a table. This table will be added as the field metadata to the resulting effect.

The function may return false. This is used to tell Player Effects that the effect could, for whatever reason, not be successfully applied. Currently, this feature is experimental and possibly broken.

The function may also return just nil on a normal success without metadata.

cancel function

The cancel function is called by Player Effects when the effect is to be cancelled. Here the modder can do all the code which is needed to revert the changes an earlier apply call made.

cancel takes an effect as its first argument and a player object as its second argument. Remember, this effect may also contain a field called metadata, which may have been added by an earlier apply call. player is the player to which the effect is/was applied. This argument is just there for convenience reasons.

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

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:

On success, the function returns a number. This number is the effect ID of the effect which has been just created. This effect ID can be used later, for playereffects.cancel_effect, for example.


Cancels a single effect.

Return value

Always nil.

playereffects.cancel_effect_group(groupname, playername)

Cancels all a player’s effects which belong to a certain group.

Return value

Always nil.

playereffects.cancel_effect_type(effect_type_id, cancel_all, playername)

Cancels one or all player effect with a certain effect type Careful! This function has not been tested yet!

Return value

Always nil.


Returns the remaining time of an effect.

Return value

Iff the effect exists, the remaining effect time is returned in full seconds. Iff the effect does not exist, nil is returned.


Returns all active effects of a player.


playername: The name of the player from which the effects are requested.

Return value

A table of all effects which belong to the player. If the player does not exist, this function returns an empty table.

playereffects.has_effect_type(playername, effect_type_id)

Returns true iff the provided player has an effect of the specified effect type, false otherwise.



This mod comes with extensive examples. The examples are disabled by default. Edit settings.lua to enable the examples. See examples.lua to find out how they are programmed. The examples are only for demonstration purposes. They are not intended to be used in an actual game.

Chat commands

The examples are mainly accessible with chat commands. Since this is just an example, everyone can use these examples.

Apply effect

These commands apply (or try to) apply an effect to you. You will get a response in the chat which give you the effect_id on success. On failure, the example will tell you that it failed.

Cancel effects


2016-11-13 WuzzyAdd mod.confmaster
2016-11-13 WuzzyVersion 1.2.0
2016-11-12 WuzzyAdd MIT License
2016-08-11 WuzzyFix accidental using of global variable “all”
2016-08-11 WuzzyAdd playereffects.has_effect_type
2015-02-08 WuzzyRemove commented out lines
2015-02-08 WuzzyFix another leaking variable
2015-02-08 WuzzyIncrement patch version number
2015-02-08 WuzzyFix leaked local variable
2014-07-19 WuzzyBump version to 1.1.0
2014-07-18 WuzzyNew effect type: repeating effects
2014-07-18 WuzzyUpdate state of example in
2014-07-18 WuzzyCleanup settings, disable examples by default
2014-07-18 WuzzyBump version to 1.0.0.
2014-07-18 WuzzyBump version to 0.4.0
2014-07-17 WuzzyLess log file spam
16 months ago master
Cached version (1523s old)
minetest_playereffects/byakuren.git 3 years ago