forked from mtcontrib/minetest_treasurer
Delete old README
This commit is contained in:
Wuzzy
201
README
201
README
@@ -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
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user