nalc
/
minetest_treasurer
forked from mtcontrib/minetest_treasurer
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
GROUPS_AND_PRECIOUSNESS
View File

@ -1,76 +1,75 @@
If you wish to register treasures to Treasurer, it is recommended to assign the treasurer to a Treasurer group. 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. 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. 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: Treasurer suggests to use the following standard Treasurer groups:
crafting_component: crafting_component:
generic group for components in crafting recipes. If it is primarily a component for food, use raw_food instead. 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 Preciousness is based roughly on the preciousness of items it can create.
fuel: fuel:
fuel for furnaces Fuel for furnaces.
preciousness is based on burning time Preciousness is based on burning time.
food: food:
can be eaten and restores health Can be eaten and restores health.
preciousness should equal the number of hearts restored, but not higher than 7. Preciousness should equal the number of hearts restored (restored HP divided by 2), but not higher than 7.
raw_food: 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: melee_weapon:
primarily used to damage close foes, i.e. a sword Primarily used to damage close foes, i.e. a sword.
preciousness is based on attack speed and damage Preciousness is based on attack speed and damage.
ranged_weapon: ranged_weapon:
primarily used to damage far away foes, Primarily used to damage far away foes,
preciousness is based on attack speed, damage and range Preciousness is based on attack speed, damage and range.
tool: tool:
a tool for other uses. A tool for other uses.
preciousness is hard to determine; at least is should base on the number of uses. Preciousness is hard to determine; at least is should base on the number of uses.
minetool: minetool:
a tool to destroy blocks. Includes pickaxes, axes, shovels, … A tool to destroy blocks. Includes pickaxes, axes, shovels, …
preciousness is based on power, number of uses and speed Preciousness is based on power, number of uses and speed.
deco: deco:
primarily just a decorational thing to place Primarily just a decorational thing to place.
preciousness is based on beauty, highly subjective Preciousness is based on beauty, highly subjective.
light: light:
is a light source Is a light source.
preciousness is based on the brightness. For the maximum brightness, preciousness should be 3. Preciousness is based on the brightness. For the maximum brightness (before sun brightness), preciousness should be 3.
building_block: building_block:
A block for buildings. Includes stairs, slabs, fences and similar things. A block for buildings. Includes stairs, slabs, fences and similar things.
Excludes all natural blocks. 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: seed:
seeds and saplings Seeds and saplings.
preciousness is based on the “usefulness” of what can grow from the seed. Preciousness is based on the percieved “usefulness” of what can grow from the seed.
transport_vehicle transport_vehicle
a vehicle to transport players and stuff, i.e. a cart or a boat A vehicle to transport players and stuff, i.e. a cart or a boat.
preciousness is hard to determine, maybe speed? Preciousness is hard to determine, maybe speed?
transport_structure transport_structure
a fixed structure which is neccessary for a transport vehicle to operate, i.e. rails A fixed structure which is neccessary for a transport vehicle to operate, i.e. rails.
preciousness is hard to dertermine … Preciousness is hard to dertermine …
ladder ladder
a ladder A ladder.
default: default:
This is the group your treasure get assigned to if you don’t specify a group. This is the group your treasure get assigned to if you don’t specify a group.

40
README.md
View File

@ -96,13 +96,15 @@ All other mods do NOT HAVE TO and SHOULD NOT depend on Treasurer.
=== On rarity and preciousness === === Treasure attributes ===
==== rarity ==== 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 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 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. 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. 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 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 “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 TSMs also can just completely ignore preciousness, then the given treasures base
on sheer luck. 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 ==== ==== Recap ====
Rarity determines the chance of a treasure, whereas preciousness determines Rarity determines the chance of a treasure, whereas preciousness determines
the difficulty to obtain it. the difficulty to obtain it. Group
== Overview of examples == == Overview of examples ==
- `trm_default_example` - registers items of default mod - `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. * `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. * `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. * `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 ===== ===== Return value =====
`true` on success, `false` on failure. `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. * `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. * `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. * `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 ===== ===== Return value =====
A table of `ItemStacks` (the requested treasures). It may be empty. A table of `ItemStacks` (the requested treasures). It may be empty.