mirror of
git://repo.or.cz/minetest_treasurer.git
synced 2024-10-31 23:40:16 +01:00
197 lines
9.8 KiB
Markdown
197 lines
9.8 KiB
Markdown
|
= 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.
|
|||
|
|