Add documentation for Treasurer’s group system

README.md

@@ -96,13 +96,15 @@ All other mods do NOT HAVE TO and SHOULD NOT depend on Treasurer.
 
 
 
-=== On rarity and preciousness ===
-==== rarity ====
+=== Treasure attributes ===
+This section explains the various attributes a treasure can have.
+
+==== Rarity ====
 Rarity in Treasurer works in a pretty primitive way: The relative rarities of all
 treasures from the treasure pool are simply all added up. The probabilitiy of one
 certain treasure is then simply the rarity value divided by the sum.
 
-==== preciousness ====
+==== Preciousness ====
 How “precious” an item is, is highly subjective and also not always easy to categorize.
 Preciousness in Treasurer’s terms should be therefore viewed as “utility” or as
 “reward level” or “strength” or even “beauty” or whatever positive attributes you can
@@ -123,9 +125,36 @@ are easy to obtain, filter out precious treasures.
 TSMs also can just completely ignore preciousness, then the given treasures base
 on sheer luck.
 
+==== Treasurer groups ====
+Every treasure can be assigned to a group. These groups are specific to Treasurer only.
+The idea is that treasures which share a common property are member of the same group.
+All groups have a name by which they are identified.
+For example, if there are apples, plums, pears and oranges and those items can be
+eaten for health, all those treasures would be members of the group “food”.
+
+The group system can be used to further narrow down the treasure pool from which you
+want Treasurer to return treasures. This makes it more interesting than just using
+an one-dimensional preciousness scale.
+
+Using the groups system is entirely optional. If your TRM does not specify any group,
+your treasure will be assigned to the group “default”. It is not possible for a treasure
+to not belong to any group. If your TSM does not specify a group parameter, Treasurer
+will use all groups.
+While not using groups as a TSM may be perfectly okay, not using groups as a TRM is
+not recommended, because TSM which filter by groups may “overlook” your treasure,
+even if it would actually fit, simply because you didn’t assign it to a specific group.
+
+Note that Treasurer groups are completely distinct from Minetest’s group system.
+
+You can basically invent your own groups on the fly, but it is strongly recommended that you
+use the groups suggested in the text file `GROUPS_AND_PRECIOUSNESS` whenever possible, for
+maximum portability of your TSM. The text file also has a rough guideline for finding
+appropriate values for the preciousness.
+
+
 ==== Recap ====
 Rarity determines the chance of a treasure, whereas preciousness determines
-the difficulty to obtain it.
+the difficulty to obtain it. Group
 
 == Overview of examples ==
 - `trm_default_example` - registers items of default mod
@@ -154,6 +183,7 @@ rare, but it’s certainly also very unprecious.
 * `preciousness` : subjective preciousness on a scale from 0 to 10 (inclusive). higher = more precious.
 * `count`: optional value which specifies the multiplicity of the item. Default is 1. See `count` syntax help in this file.
 * `wear`: optional value which specifies the wear of the item. Default is 0, which disables the wear. See `wear` syntax help in this file.
+* `treasurer_groups`: an optional table of group names to assign this treasure to. If omitted, the treasure is added to the default group.
 
 ===== Return value =====		
 `true` on success, `false` on failure.
@@ -190,6 +220,8 @@ Request some treasures from treasurer.
 * `count`: (optional) amount of treasures. If this value is `nil`, Treasurer assumes a default of 1.
 * `minimal_preciousness`: (optional) don’t consider treasures with a lower preciousness. If `nil`, there’s no lower bound.
 * `maximum_preciousness`: (optional) don’t consider treasures with a higher preciousness. If `nil`, there’s no upper bound.
+* `treasurer_group`: (optional): Only consider treasures which are members of at least one of the members of the provided Treasurer group table. `nil` = consider all groups
+ 
 
 ===== Return value =====
 A table of `ItemStacks` (the requested treasures). It may be empty.