126 lines
5.1 KiB
Plaintext
126 lines
5.1 KiB
Plaintext
The idea behind this framework is that player status effects, both permanent
|
|
and temporary, should mesh nicely with each other. This means they need to be
|
|
able to be combined.
|
|
|
|
Effect Monoids
|
|
==============
|
|
An effect monoid covers a single kind of player state a status effect might
|
|
affect. These are things like flying ability, speed multiplier, or
|
|
fighting ability. Each kind of state can be represented by a certain type of
|
|
value: a boolean for flying ability, or a number for speed or fighting ability.
|
|
Each effect that contributes to an effect monoid supplies one of these data
|
|
values, and then all of these are combined together. The combined value is
|
|
then interpreted and converted into effects on the world state. Flying privs
|
|
would be set, and physics overrides would be used to change a player's speed.
|
|
Something like fighting points might not have an immediate effect, but
|
|
your mod could later get the current value and do things with it, for example
|
|
augmenting the power of a player's punches in a punch callback.
|
|
|
|
Definition
|
|
----------
|
|
An effect monoid definition needs the following:
|
|
|
|
combine(elem1, elem2) - associative binary operation (explained below)
|
|
fold({elems}) - combine a whole list (explained below)
|
|
identity - (explained below)
|
|
apply(value, player) - explained below
|
|
on_change(val1, val2, player) - explained below (optional)
|
|
|
|
Additionally, you should document what values are valid for effects to
|
|
contribute to this monoid.
|
|
|
|
combine and fold
|
|
- - - - - - - -
|
|
combine should take two valid effect values and produce a third value, that is
|
|
also valid. combine should also be associative. fold should take a table and
|
|
combine the values together, in key order, and should be equivalent to using
|
|
combine to combine all the values.
|
|
|
|
If you only define one of the two, the undefined one will be defined in terms
|
|
of one that is defined. However, you are highly encouraged to define both, for
|
|
performance reasons.
|
|
|
|
identity
|
|
- - - -
|
|
identity, when combined with any other value, should result in that other value.
|
|
It also represents the "default" or "neutral" state of the player, and will be
|
|
used when there are no status effects active for a particular monoid.
|
|
|
|
apply
|
|
- - -
|
|
apply is the function that interprets the current combined value in the monoid,
|
|
and applies its effects to the player.
|
|
|
|
on_change
|
|
- - - - -
|
|
This function is called whenever there is a change in the monoid value for a
|
|
player that is online. This can be used to show special effects such as sounds,
|
|
particles, or messages. It should not change the state controlled by this monoid.
|
|
The two values passed in are not guaranteed to be different, so plan accordingly.
|
|
|
|
|
|
Effect Types
|
|
============
|
|
An effect type is a description of an effect, that can be applied later in an
|
|
individual effect.
|
|
|
|
Definition
|
|
----------
|
|
An effect type is defined with a table with the following properties (defaults
|
|
in parens):
|
|
|
|
disp_name - Display name
|
|
dynamic - A bool for whether an effect of this type can have its values
|
|
changed (false)
|
|
tags - A set of tags ({})
|
|
monoids - The set of monoids this effect type affects
|
|
hidden - A boolean for whether it should be shown to the affected (false)
|
|
cancel_on_death - A boolean for whether this effect should be removed from the
|
|
player when they die.
|
|
values - A table mapping monoid names to associated values. These are the
|
|
values that will be combined in the monoid.
|
|
icon - A texture string (if nil, no icon is shown)
|
|
|
|
|
|
Functions
|
|
=========
|
|
monoidal_effects.register_monoid("name", monoid_def)
|
|
Registers a new effect monoid. name needs to be unique across all mods, so
|
|
you should prepend your mod name, as in nodes/craftitems.
|
|
|
|
monoidal_effects.register_type("name", type_def)
|
|
Registers a new effect type. name needs to be unique.
|
|
|
|
monoidal_effects.apply_effect("effect_type", duration, "player_name"[, values])
|
|
Applies a new effect of the specified type. duration should be a positive
|
|
integer number of seconds or the string "perm". values is an optional table
|
|
mapping monoid names to values, and is used with dynamic effect types to
|
|
initialize the effect with custom values. Has no effect on static effect types.
|
|
Returns an effect id.
|
|
|
|
monoidal_effects.cancel_effect(effect_id)
|
|
Cancels the given effect.
|
|
|
|
monoidal_effects.cancel_monoid("monoid_name"[, "player_name"])
|
|
Cancels all effects from a particular monoid on a player.
|
|
|
|
monoidal_effects.cancel_effect_type("effect_type", "player_name")
|
|
Cancels all effects from a player that are a certain effect_type. If player_name
|
|
is nil, it cancels all matching effects from all players.
|
|
|
|
monoidal_effects.cancel_tag("tag"[, "player_name"])
|
|
Cancels all effects from a player with the given tag. If player_name is nil,
|
|
it cancels all matching effects from all players.
|
|
|
|
monoidal_effects.get_remaining_time(effect_id)
|
|
Gets the remaining time of an effect, in seconds, or "perm".
|
|
|
|
monoidal_effects.get_player_effects("player_name")
|
|
Gets a set of effects applied to the given player
|
|
|
|
monoidal_effects.get_values(uid)
|
|
Returns the value table associated with an effect, if it exists
|
|
|
|
monoidal_effects.get_monoid_value("monoid_name", "player_name")
|
|
Gets the current combined value for a monoid and player.
|