stubs

API.md

@@ -0,0 +1,79 @@
+#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.

COPYING

@@ -0,0 +1,13 @@
+Copyright 2015-2016 raymoo
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

description.txt

@@ -0,0 +1,2 @@
+player_monoids is a library for managing global player state, such as physics
+overrides or player visual size.

init.lua

@@ -0,0 +1 @@
+-- Nothing yet

mod.conf

@@ -0,0 +1 @@
+name=player_monoids