From 7c29fd33680992f259c4d0b034e51a687a8bc0a9 Mon Sep 17 00:00:00 2001 From: Wuzzy Date: Fri, 25 Jul 2014 12:48:11 +0200 Subject: [PATCH] Convert README file to Markdown format --- README.md | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b2bdb7e --- /dev/null +++ b/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. +