Add documentation for Treasurer’s group system

This commit is contained in:
Wuzzy 2014-10-04 04:31:02 +02:00
parent 3b62cb8a2c
commit 88ca8bafbf
2 changed files with 66 additions and 35 deletions

@ -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 dont specify a group.

@ -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 Treasurers 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 didnt assign it to a specific group.
Note that Treasurer groups are completely distinct from Minetests 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 its 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) dont consider treasures with a lower preciousness. If `nil`, theres no lower bound.
* `maximum_preciousness`: (optional) dont consider treasures with a higher preciousness. If `nil`, theres 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.