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.add_child_monoid("parent_name", "child_name"[, convert])
Sets a monoid to be the child of another. When calculating the combined value
for the parent monoid, values of the child monoids will also be mixed in, to
the left of all "actual" values, in order of registration.

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_monoid_value("monoid_name", "player_name")
Gets the current combined value for a monoid and player.