Add documentation for Treasurer’s group system

GROUPS_AND_PRECIOUSNESS

@@ -1,76 +1,75 @@
 
 If you wish to register treasures to Treasurer, it is recommended to assign the treasurer to a Treasurer group.
-Treasurer also requires you to assign each
 
-It is not possible to assign a treasure to multiple groups. If you think a treasurer fits to two groups, create
+It is not possible to assign a treasure to multiple groups. If you think a treasure fits into two groups, create
 two seperate treasure definitions instead. But try to keep it as an exception.
 
-Think of treasurer groups as drawers for treasurers to put into.
+Think of treasurer groups as categories for treasurers to put into.
 
 This file contains some guidelines for Treasurer groups and there are even guidelines for preciousness levels.
-Keep in mind these are only guidelines
+Keep in mind these are only guidelines.
 
 Treasurer suggests to use the following standard Treasurer groups:
 
 crafting_component:
-	generic group for components in crafting recipes. If it is primarily a component for food, use raw_food instead.
-	preciousness is based roughly on the preciousness of items it can create
+	Generic group for components in crafting recipes. If it is primarily a component for food, use raw_food instead.
+	Preciousness is based roughly on the preciousness of items it can create.
 
 fuel:
-	fuel for furnaces
-	preciousness is based on burning time 
+	Fuel for furnaces.
+	Preciousness is based on burning time.
 
 food:
-	can be eaten and restores health
-	preciousness should equal the number of hearts restored, but not higher than 7.
+	Can be eaten and restores health.
+	Preciousness should equal the number of hearts restored (restored HP divided by 2), but not higher than 7.
 
 raw_food:
-	food which is not fully processed and is not (quite) ready to be eaten.
+	Food which is not fully processed and is not (quite) ready to be eaten.
 
 melee_weapon:
-	primarily used to damage close foes, i.e. a sword
-	preciousness is based on attack speed and damage
+	Primarily used to damage close foes, i.e. a sword.
+	Preciousness is based on attack speed and damage.
 
 ranged_weapon:
-	primarily used to damage far away foes, 
-	preciousness is based on attack speed, damage and range
+	Primarily used to damage far away foes, 
+	Preciousness is based on attack speed, damage and range.
 
 tool:
-	a tool for other uses.
-	preciousness is hard to determine; at least is should base on the number of uses.
+	A tool for other uses.
+	Preciousness is hard to determine; at least is should base on the number of uses.
 	
 
 minetool:
-	a tool to destroy blocks. Includes pickaxes, axes, shovels, …
-	preciousness is based on power, number of uses and speed
+	A tool to destroy blocks. Includes pickaxes, axes, shovels, …
+	Preciousness is based on power, number of uses and speed.
 
 deco:
-	primarily just a decorational thing to place
-	preciousness is based on beauty, highly subjective
+	Primarily just a decorational thing to place.
+	Preciousness is based on beauty, highly subjective.
 
 light:
-	is a light source
-	preciousness is based on the brightness. For the maximum brightness, preciousness should be 3.
+	Is a light source.
+	Preciousness is based on the brightness. For the maximum brightness (before sun brightness), preciousness should be 3.
 
 building_block:
 	A block for buildings. Includes stairs, slabs, fences and similar things.
 	Excludes all natural blocks.
-	preciousness should be rougly based on the “cost” to craft the block.
+	Preciousness should be roughly based on the “cost” to craft the block.
 
 seed:
-	seeds and saplings
-	preciousness is based on the “usefulness” of what can grow from the seed.
+	Seeds and saplings.
+	Preciousness is based on the percieved “usefulness” of what can grow from the seed.
 
 transport_vehicle
-	a vehicle to transport players and stuff, i.e. a cart or a boat
-	preciousness is hard to determine, maybe speed?
+	A vehicle to transport players and stuff, i.e. a cart or a boat.
+	Preciousness is hard to determine, maybe speed?
 
 transport_structure
-	a fixed structure which is neccessary for a transport vehicle to operate, i.e. rails
-	preciousness is hard to dertermine …
+	A fixed structure which is neccessary for a transport vehicle to operate, i.e. rails.
+	Preciousness is hard to dertermine …
 
 ladder
-	a ladder
+	A ladder.
 
 default:
 	This is the group your treasure get assigned to if you don’t specify a group.

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.