Version: 1.2.0 (This is a SemVer.)
For: Minetest 0.4.10 or later
License of everything: MIT License
Download: download/file.php?mode=view&id=7980
Project page with README file: http://repo.or.cz/w/minetest_playereffects.git
List of known mods which use Player Effects:
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.
- high walking speed (speed property)
- high jump height (jump property)
- low player gravity (gravity property)
- high player gravity (gravity property)
- having the X privilege granted (binary “do I have the property?” property) (yes, this is weird, but it works!)
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.
This is what the mod had achieved for now:
- Showing all active effects in the HUD (with timer)
- Letting you define your own status effect types
- Letting you define effect groups to automatically eliminate effect conflicts (fast vs slow, low vs high gravity, etc.)
- Letting you apply effects to player
- Letting you remove effects to player
- Doing a lot of important “plumbing” and “behind-the-stages” work:
- Remembering effects when a player leaves and freeze the timer
- Restoring them when the player is back
- Remembering all effects when the server shuts down
- Restoring them as frozen effects when the server is back
- Cancelling all active player’s effects when he/she/it dies
The HUD shows a list of active effects and looks like this:
Many things have been achiveved, but I do not guarantee a stable API yet. Until version 1.0, I intend this thread to be a discussion thread for comments, ideas, test reports, and whatever.
List of important goals for later versions:
- Additive effects: A whole new class of effects which is different from the exclusive effects. They too use effect groups, but they do not cancel each other out. Instead, they add to each other. Let’s say you take 2 potion of speed, maybe both are not of the same strength. Under exclusive effects, the old effect is simply gone. But under additive effects, the speed of both potions would add up. It is also planned to add optional limits, so a player could not jack up a property towards absurdly high values.
The mod comes with several example effect types for testing; they are enabled by default and I hope they should be helpful for modders as well. As soon as I think this mod is stable, I disable the examples by default, simply to avoid cluttering the modspace. ;-)
The examples are simply chatcommands available to everyone (effect groups are in brackets)
* /fast: You become faster (speed)
* /slow: You become slower (speed)
* /highjump: You can jump a bit higher (jump)
* /fly: You get the fly privilege temporarily (fly)
Try /fast and /slow quickly after each other. There should be no overlap at all. Using status effects to handle privileges sounds weird and it IS weird. But it is also funny somehow. If you really want to manipulate privileges with this mods, just make sure nobody messes around with the affected privileges manually.
The relevant stuff for modders:
To use this framework, do this:
- create a mod
- make it depend on playereffects
- register effect types
- decide when to apply said effect types and apply them
The important functions:
Register a new effect type:
- Code: Select all
playereffects.register_effect_type(internal_name, description, groups, apply, cancel)
Where:
internal_name is the name which is internally used by the mod. Please use only alphanumeric ASCII characters.
description is the text which is exposed to the GUI and visible to the player.
groups is a table of strings to which the effect type is assigned to. I explain the concept of effect groups later.
apply is a function which takes a player object. It is the player object to which the effect is applied to. This function isused by the framework to start the effect; it should only contain the gameplay-relevant stuff, the framework does the rest for you.
cancel is a function which takes an effect table. It is the effect which is to be cancelled. This function is called by the framework when the effect expires or is explicitly cancelled by other means.
Apply an existing effect type to a player:
- Code: Select all
playereffects.apply_effect_type(internal_name, duration, player)
This applies the effect type with the internal name internal_name for duration seconds to player.