forked from minetest-mods/player_monoids
79 lines
3.5 KiB
Markdown
79 lines
3.5 KiB
Markdown
|
#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(player, id)``` - Removes the change with the given ID, if
|
||
|
|
it exists.
|
||
|
|
|
||
|
|
Monoid Properties
|
||
|
|
-----------------
|
||
|
|
```monoid.value()``` - The current combined value of the monoid.
|