Convert README file to Markdown format

README.md

@@ -0,0 +1,196 @@
+= Treasurer’s README file for Treasurer version 0.2.0 =
+== Overview ==
+* Name: Treasurer
+* Technical name: `treasurer`
+* Purpose: To provide an interface for mods which want to spawn ItemStacks randomly and an interface for mods which create new items.
+* Version: 0.2.0
+* Dependencies: none
+* License: WTFPL
+
+== Introduction ==
+Problem:
+There are a bunch of mods which have cool items but they won’t appear in the world by
+themselves.
+There are some mods which randomly distribute treasures into the world. Sadly, these only
+distribute the items they know—which are just the items of the mod “default” most of the
+time. The items of the other mods are completely missed.
+
+The reason for this is that the distributing mods can’t know what sort of items are available
+unless they explicitly depend on the mods that defines these. Viewed the other way round,
+the item-defining mods that also distribute these items into the world are limited in the
+sense that they only know one means of distributing items.
+
+There is a gap between defining items and distributing them. Every time a mod does both,
+flexibility is limited and expansion becomes difficult.
+
+To bridge this gap, Treasurer has been written. Treasurer makes it possible a) for mods to define
+treasures without bothering _how_ these are distributed into the world and b) for mods to distribute
+treasures around the world without knowledge about _what_ treasures exactly are distributed.
+
+== Technical side of Treasurer ==
+=== technical overview ===
+To get a working Treasurer architecture and actually get some treasures into the world,
+you need:
+* Treasurer
+* at least one treasure registration mod
+* at least one treasure spawning mod
+
+=== treasurer registration mod ===
+Firstly, there are the treasure registration mods (TRMs). The task of TRMs is to tell
+Treasurer which items does it have to offer, which relative appearance probabilities these
+treasures should have, how “precious” the treasure is considered (on a scale from 0 to 10)
+, optionally how big the stack of items should be and optionally how much worn out it is.
+TRMs must depend on at least two mods: On treasurer and on the mod or mods
+where the items are defined. Technically, a TRM consists of nothing more than a long
+list of “registration” function calls. While this seems trivial, the task of balancing
+out probabilties and balancing out preciousness levels of treasures is not trivial
+and it may take a long time to get right.
+
+It is strongly recommended that a TRM really does nothing
+more than registering treasures (and not defining items, for example). If you want
+to make your mod compatible to Treasurer, don’t change your mod, write a TRM for
+it instead.
+
+There is an example TRM, called “`trm_default_example`”. It registers some items
+of the default as treasures. Unsurprisingly, it depends on `treasurer` and `default`.
+
+=== treasurer spawning mods ===
+Secondly, there are the treasure spawning mods (TSMs). The task of a TSM is to somehow
+distribute the available treasures into the world. This is also called “treasure
+spawning”. How exactly the TSM spawns the treasures is completely up the TSM. But a
+TSM has to request Treasurer to get some random treasures to distribute. A TSM may
+optionally request to filter out treasures outside certain preciousness levels, so
+it can be 
+Treasurer can not guarantee to return the requestet amount of treasures, it may
+return an empty table, for two reasons:
+
+* There is no TRM activated. There must be at least one to work
+* The preciousness filter filtered out. This problem can be fixed by installing more
+TRMs or by balancing the existing TRMs to cover as many preciousness levels as
+possible. It also may be that the range specified by the TSM was too small. It is
+recommended to keep the requested range at least of a size of 1.
+Treasurer does, however, guarantee that the returned treasures are always in the
+requested boundsa.
+
+A TSM has to at least depend on Treasurer.
+Like for TRMs, it is strongly recommended that a TSM does nothing more than spawning
+treasures. This does not exclude the possibility that a TSM does not depend
+on any other mod.
+
+There are two example TSMs. The first one is a very basic one and called “`tsm_gift_example`”.
+It gives a “welcome gift” (1 random treasure) to players who just joined the server
+or who respawn. The preciousness filter is not used. It does only depend on Treasurer.
+The second one is called “`tsm_chests_example`” and pretty advanced for an example.
+It places chests of the mod “default” between 20 and 200 node lenghts below the water
+surface and puts 1-6 random treasures into these. The lower the chest, the higher
+the preciousness. It depends on treasurer and default (for the chests, of course).
+
+=== Recap ===
+TRMs define treasures, TSMs spawn them. Treasurer manages the pool of available treasures.
+TRMs and TSMs do not have to know anything from each other.
+TRMs and TSMs do not neccessarily have to change any line of code of other mods to function.
+Treasurer depends on nothing.
+
+Important: It should always only be neccessary for TRMs and TSMs to depend on Treasurer.
+All other mods do NOT HAVE TO and SHOULD NOT depend on Treasurer.
+
+
+
+=== On rarity and preciousness ===
+==== 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 ====
+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
+think of for items.
+So, if you create a TRM and your treasure is something you want the player work
+hard for, assign it a high preciousness. Everyday items that are already easy to
+obtain in normal gameplay certainly deserve a lower precious than items that are
+expensive to craft.
+If your treasure consists of a powerful
+item, assign it a high preciousness. When in doubt, try to value gameplay over
+personal taste. Remember that TSMs can (and will!) filter out treasures based
+on their preciousness.
+For TSM authors, consider preciousness this way: If the trouble the player has
+to get through to in order to obtain the treasure is high, better filter
+out unprecious treasures. If your TSM distributes many treasures all over the world and these
+are easy to obtain, filter out precious treasures.
+
+TSMs also can just completely ignore preciousness, then the given treasures base
+on sheer luck.
+
+==== Recap ====
+Rarity determines the chance of a treasure, whereas preciousness determines
+the difficulty to obtain it.
+
+== Overview of examples ==
+- `trm_default_example` - registers items of default mod
+- `tsm_chests_example` - spawns chests (from the default mod)
+- `tsm_gift_example` - gives one treasure as a “welcome gift” to joined or respawned players
+
+== Treasurer API documentation ==
+=== API documentation for treasure registration mods ===
+The API consists of one function, which is called “`treasurer.register_treasure`”.
+
+==== `treasurer.register_treasure` ====
+Registers a new treasure (this means the treasure will be ready to be spawned by treasure spawning mods).
+
+This function does some basic parameter checking to catch the most obvious
+mistakes. If invalid parameters have been passed, the input is rejected and
+the function returns false. However, it does not cover every possible
+mistake, so some invalid treasures may slip through.
+		
+Rarity does not imply preciousness. A rare treasure may not neccessarily a
+very precious one. A treasure chest with scorched stuff inside may be very
+rare, but it’s certainly also very unprecious.
+
+===== Parameters =====
+* `name`: name of resulting `ItemStack`, e.g. “`mymod:item`”
+* `rarity`: rarity of treasure on a scale from 0 to 1 (inclusive). lower = rarer
+* `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.
+
+===== Return value =====		
+`true` on success, `false` on failure.
+
+=== data formats ===
+format of count type:
+==== `count` ====
+A `count` can be a number or a table 
+
+* `number`: it’s always so many times
+* `{min, max}`: it’s pseudorandomly between `min` and `max` times, `math.random` will be used to chose the value
+* `{min, max, prob_func}`: it’s between `min` and `max` times, and the value is given by `prob_func` (see below)
+
+==== `wear` ====
+Completely analogous to `count`.
+
+==== Format of `prob_func` function ====
+There are no parameters.
+
+It returns a random or pseudorandom number between 0 (inclusive) and 1 (exclusive).
+
+`prob_func` is entirely optional, if it’s not used, treasurer will
+default to using `math.random`. You can use `prob_func` to define your own
+“randomness” function, in case you don’t wish your values to be evenly
+distributed.
+
+=== API documentation for treasure spawning mods ===
+The API consists of one function, called “`treasurer.select_random_treasures`”.
+
+==== `treasurer.select_random_treasures` ====
+Request some treasures from treasurer.
+
+===== Parameters =====
+* `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.
+
+===== Return value =====
+A table of `ItemStacks` (the requested treasures). It may be empty.
+