Version: 1.2.0 (This is a SemVer.)
For: Minetest 0.4.10 or later
License of everything: MIT License
Project page with README file: http://repo.or.cz/w/minetest_playereffects.git
List of known mods which use Player Effects:
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!)
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
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 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
Register a new effect type:
Code: Select all
playereffects.register_effect_type(internal_name, description, groups, apply, cancel)
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)