From 3b62cb8a2cf41d169b839bfabe3c4d0543cad11e Mon Sep 17 00:00:00 2001 From: Wuzzy Date: Fri, 25 Jul 2014 12:48:55 +0200 Subject: [PATCH] Delete old README --- README | 201 --------------------------------------------------------- 1 file changed, 201 deletions(-) delete mode 100644 README diff --git a/README b/README deleted file mode 100644 index 63d1936..0000000 --- a/README +++ /dev/null @@ -1,201 +0,0 @@ -= Treasurer’s README file for Treasurer version 0.1 = -== 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.1 -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: -1) There is no TRM activated. There must be at least one to work -2) 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. - - 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. - note: - 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. - note: - 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. - - returns: - true on success, - false on failure - -=== data formats === -format of count type: - A count can be a number or a table - - count = number - --> it’s always number times - - count = {min, max} - --> it’s pseudorandomly between min and max times, math.random() will be - used to chose the value - count = {min, max, prob_func} - --> it’s between min and max times, and the value is given by - prob_func (see below) - -format of wear type: - completely analogous to count - -format of prob_func function: - prob_func = function() - parameters: - (none) - returns: - --> a random or pseudorandom number between 0 (inclusive) and 1 (exclusive). - notes: - prob_func is entirely optional, if it’s not used, treasurer will - default to math.random. You can use prob_func to define your own - random 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. - returns: - a table of ItemStacks (the requested treasures) - may be empty -