mirror of
git://repo.or.cz/minetest_treasurer.git
synced 2024-12-04 12:53:49 +01:00
Delete old README
This commit is contained in:
Wuzzy
parent
7c29fd3368
commit
3b62cb8a2c
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user