README

   1 = Treasurer’s README file for Treasurer version 0.1 =
   2 == Overview ==
   3 Name:           Treasurer
   4 Technical name: treasurer
   5 Purpose:        To provide an interface for mods which want to spawn ItemStacks randomly and
   6                 an interface for mods which create new items.
   7 Version:        0.1
   8 Dependencies:   none
   9 License:        WTFPL
  10
  11 == Introduction ==
  12 Problem:
  13 There are a bunch of mods which have cool items but they won’t appear in the world by
  14 themselves.
  15 There are some mods which randomly distribute treasures into the world. Sadly, these only
  16 distribute the items they know—which are just the items of the mod “default” most of the
  17 time. The items of the other mods are completely missed.
  18
  19 The reason for this is that the distributing mods can’t know what sort of items are available
  20 unless they explicitly depend on the mods that defines these. Viewed the other way round,
  21 the item-defining mods that also distribute these items into the world are limited in the
  22 sense that they only know one means of distributing items.
  23
  24 There is a gap between defining items and distributing them. Every time a mod does both,
  25 flexibility is limited and expansion becomes difficult.
  26
  27 To bridge this gap, Treasurer has been written. Treasurer makes it possible a) for mods to define
  28 treasures without bothering _how_ these are distributed into the world and b) for mods to distribute
  29 treasures around the world without knowledge about _what_ treasures exactly are distributed.
  30
  31 == Technical side of Treasurer ==
  32 === technical overview ===
  33 To get a working Treasurer architecture and actually get some treasures into the world,
  34 you need:
  35  * Treasurer
  36  * at least one treasure registration mod
  37  * at least one treasure spawning mod
  38
  39 === treasurer registration mod ===
  40 Firstly, there are the treasure registration mods (TRMs). The task of TRMs is to tell
  41 Treasurer which items does it have to offer, which relative appearance probabilities these
  42 treasures should have, how “precious” the treasure is considered (on a scale from 0 to 10)
  43 , optionally how big the stack of items should be and optionally how much worn out it is.
  44 TRMs must depend on at least two mods: On treasurer and on the mod or mods
  45 where the items are defined. Technically, a TRM consists of nothing more than a long
  46 list of “registration” function calls. While this seems trivial, the task of balancing
  47 out probabilties and balancing out preciousness levels of treasures is not trivial
  48 and it may take a long time to get right.
  49
  50 It is strongly recommended that a TRM really does nothing
  51 more than registering treasures (and not defining items, for example). If you want
  52 to make your mod compatible to Treasurer, don’t change your mod, write a TRM for
  53 it instead.
  54 There is an example TRM, called “trm_default_example”. It registers some items
  55 of the default as treasures. Unsurprisingly, it depends on treasurer and default.
  56
  57 === treasurer spawning mods ===
  58 Secondly, there are the treasure spawning mods (TSMs). The task of a TSM is to somehow
  59 distribute the available treasures into the world. This is also called “treasure
  60 spawning”. How exactly the TSM spawns the treasures is completely up the TSM. But a
  61 TSM has to request Treasurer to get some random treasures to distribute. A TSM may
  62 optionally request to filter out treasures outside certain preciousness levels, so
  63 it can be
  64 Treasurer can not guarantee to return the requestet amount of treasures, it may
  65 return an empty table, for two reasons:
  66 1) There is no TRM activated. There must be at least one to work
  67 2) The preciousness filter filtered out. This problem can be fixed by installing more
  68 TRMs or by balancing the existing TRMs to cover as many preciousness levels as
  69 possible. It also may be that the range specified by the TSM was too small. It is
  70 recommended to keep the requested range at least of a size of 1.
  71 Treasurer does, however, guarantee that the returned treasures are always in the
  72 requested boundsa.
  73 A TSM has to at least depend on Treasurer.
  74 Like for TRMs, it is strongly recommended that a TSM does nothing more than spawning
  75 treasures. This does not exclude the possibility that a TSM does not depend
  76 on any other mod.
  77 There are two example TSMs. The first one is a very basic one and called “tsm_gift_example”.
  78 It gives a “welcome gift” (1 random treasure) to players who just joined the server
  79 or who respawn. The preciousness filter is not used. It does only depend on Treasurer.
  80 The second one is called “tsm_chests_example” and pretty advanced for an example.
  81 It places chests of the mod “default” between 20 and 200 node lenghts below the water
  82 surface and puts 1-6 random treasures into these. The lower the chest, the higher
  83 the preciousness. It depends on treasurer and default (for the chests, of course).
  84
  85 === Recap ===
  86 TRMs define treasures, TSMs spawn them. Treasurer manages the pool of available treasures.
  87 TRMs and TSMs do not have to know anything from each other.
  88 TRMs and TSMs do not neccessarily have to change any line of code of other mods to function.
  89 Treasurer depends on nothing.
  90
  91 Important: It should always only be neccessary for TRMs and TSMs to depend on Treasurer.
  92 All other mods do NOT HAVE TO and SHOULD NOT depend on Treasurer.
  93
  94
  95
  96 === On rarity and preciousness ===
  97 ==== rarity ====
  98 Rarity in Treasurer works in a pretty primitive way: The relative rarities of all
  99 treasures from the treasure pool are simply all added up. The probabilitiy of one
 100 certain treasure is then simply the rarity value divided by the sum.
 101
 102 ==== preciousness ====
 103 How “precious” an item is, is highly subjective and also not always easy to categorize.
 104 Preciousness in Treasurer’s terms should be therefore viewed as “utility” or as
 105 “reward level” or “strength” or even “beauty” or whatever positive attributes you can
 106 think of for items.
 107 So, if you create a TRM and your treasure is something you want the player work
 108 hard for, assign it a high preciousness. Everyday items that are already easy to
 109 obtain in normal gameplay certainly deserve a lower precious than items that are
 110 expensive to craft.
 111 If your treasure consists of a powerful
 112 item, assign it a high preciousness. When in doubt, try to value gameplay over
 113 personal taste. Remember that TSMs can (and will!) filter out treasures based
 114 on their preciousness.
 115 For TSM authors, consider preciousness this way: If the trouble the player has
 116 to get through to in order to obtain the treasure is high, better filter
 117 out unprecious treasures. If your TSM distributes many treasures all over the world and these
 118 are easy to obtain, filter out precious treasures.
 119
 120 TSMs also can just completely ignore preciousness, then the given treasures base
 121 on sheer luck.
 122
 123 ==== Recap ====
 124 Rarity determines the chance of a treasure, whereas preciousness determines
 125 the difficulty to obtain it.
 126
 127 == Overview of examples ==
 128 - trm_default_example - registers items of default mod
 129 - tsm_chests_example - spawns chests (from the default mod)
 130 - tsm_gift_example - gives one treasure as a “welcome gift” to joined or respawned players
 131
 132 == Treasurer API documentation ==
 133 === API documentation for treasure registration mods ===
 134 The API consists of one function, which is called “treasurer.register_treasure”.
 135
 136         treasurer.register_treasure - registers a new treasure
 137                 (this means the treasure will be ready to be spawned by treasure spawning mods.
 138
 139         parameters:
 140                 name:   name of resulting ItemStack, e.g. “mymod:item”
 141                 rarity: rarity of treasure on a scale from 0 to 1 (inclusive). lower = rarer
 142                 preciousness: subjective preciousness on a scale from 0 to 10 (inclusive)
 143                         higher = more precious.
 144                 count:  optional value which specifies the multiplicity of the item. Default
 145                         is 1. See count syntax help in this file.
 146                 wear:   optional value which specifies the wear of the item. Default is 0,
 147                         which disables the wear. See wear syntax help in this file.
 148         note:
 149                 This function does some basic parameter checking to catch the most obvious
 150                 mistakes. If invalid parameters have been passed, the input is rejected and
 151                 the function returns false. However, it does not cover every possible
 152                 mistake, so some invalid treasures may slip through.
 153         note:
 154                 Rarity does not imply preciousness. A rare treasure may not neccessarily a
 155                 very precious one. A treasure chest with scorched stuff inside may be very
 156                 rare, but it’s certainly also very unprecious.
 157
 158         returns:
 159                 true on success,
 160                 false on failure
 161
 162 === data formats ===
 163 format of count type:
 164         A count can be a number or a table
 165
 166         count = number
 167                 --> it’s always number times
 168
 169         count = {min, max}
 170                 --> it’s pseudorandomly between min and max times, math.random() will be
 171                     used to chose the value
 172         count = {min, max, prob_func}
 173                 --> it’s between min and max times, and the value is given by
 174                     prob_func (see below)
 175
 176 format of wear type:
 177         completely analogous to count
 178
 179 format of prob_func function:
 180         prob_func = function()
 181         parameters:
 182                 (none)
 183         returns:
 184         --> a random or pseudorandom number between 0 (inclusive) and 1 (exclusive).
 185         notes:
 186                 prob_func is entirely optional, if it’s not used, treasurer will
 187                 default to math.random. You can use prob_func to define your own
 188                 random function, in case you don’t wish your values to be evenly
 189                 distributed.
 190
 191 === API documentation for treasure spawning mods
 192 The API consists of one function, called “treasurer.select_random_treasures”.
 193
 194         treasurer.select_random_treasures - request some treasures from treasurer
 195         parameters:
 196                 count: (optional) amount of treasures. If this value is nil, treasurer assumes a default of 1.
 197                 minimal_preciousness: (optional) don’t consider treasures with a lower preciousness. If nil, there’s no lower bound.
 198                 maximum_preciousness: (optional) don’t consider treasures with a higher preciousness. If nil, there’s no upper bound.
 199         returns:
 200                 a table of ItemStacks (the requested treasures) - may be empty
 201