player_monoids/API.md

#Player Monoids

The idea behind this library is that global player state (physics overrides,
armor values, etc.) changes from multiple mods should mesh nicely with each
other. This means they must be combinable in a sane way.

Monoids
=======
A player monoid covers a single kind of player state a mod might want to change.
These can be built-in player state, like speed multipliers or fly permissions,
or could be custom state introduced by mods, such as corruption or reputation
level. When you make a player monoid, you must choose some type of value to
represent state changes - for example, numbers for speed multipliers, or vectors
for "lucky direction". Each mod can contribute different changes, represented
by this type of value, and they are all combined together. This combined value
is interpreted and converted into actual effects on the player's state.
Privileges could be set, physics overrides would be used to effect speed
changes, and a mod might change some value to match the monoid.

Definition
----------
A player monoid definition is a table with the following:

  * ```combine(elem1, elem2)``` - An associative binary operation
  * ```fold({elems})``` - Equivalent to combining a whole list with ```combine```
  * ```identity``` - An identity element for ```combine```
  * ```apply(value, player)``` - Apply the effect represented by ```value```
  to ```player```
  * ```on_change(val1, val2, player)``` - Do something when the value on a
  player changes. (optional)

Additionally, you should document what values are valid representatives of
your monoid's effects. When something says that a value is "in a monoid", it
means that value is a valid representative of your monoid's effects.

combine and fold
----------------
```combine``` should take two values in your monoid and produce a third value in
your monoid. It should also be an associative operation. ```fold`` should take a
table containing elements of your monoid as input and combine them together in
key order. It should be equivalent to using ```combine``` to combine all the
values together. For example, ```combine``` could multiply two speed multipliers
together, and ```fold``` could multiply every value together.

If you only define one of the two, the undefined one will be defined in terms of
the one that is defined. However, it is better to define both for performance
reasons.

identity
--------
```identity```, when combined with any other value, should result in the 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.
For example, the identity of a speed monoid could be the multiplier ```1```.

apply
-----
```apply``` is the function that interprets a value in your monoid to do
something to the player's state. For example, you could set a speed multiplier
as the speed physics override for the player.

Functions
=========
```player_monoids.make_monoid(monoid_def)``` - Creates a new monoid that can be
used to make changes to the player state. Returns a monoid.

Monoid Methods
--------------
```monoid:add_change(player, value[, id])``` - Applies the change represented by
```value``` to ```player```. Returns an ID for the change. If the optional
argument ```id``` is supplied, that is used as the ID instead, and any existing
change with that ID is removed.

```monoid:del_change(id)``` - Removes the change with the given ID, if
it exists.

Monoid Properties
-----------------
```monoid.value``` - The current combined value of the monoid.