forked from mtcontrib/minetest_mana
92 lines
3.0 KiB
Markdown
92 lines
3.0 KiB
Markdown
API documentation for Mana 0.3.0
|
|
================================
|
|
|
|
**Warning:** This API is not considered stable yet.
|
|
Future releases will not enture backwards compability until the
|
|
release of version 1.0.0 of the Mana mod.
|
|
|
|
|
|
## Introduction
|
|
The API of the Mana mod allows you to set and receive
|
|
the current and maxiumum mana reserves of a player,
|
|
and to subtract and add mana.
|
|
|
|
## The basic rules
|
|
For integrity reasons, this mod will ensure that the following assumptions
|
|
are true at all times for all players:
|
|
|
|
* Current and maximum mana can never be smaller than 0
|
|
* The current value must not be greater than the maximum value
|
|
|
|
It should be not possible to break these rules using this API alone.
|
|
If you somehow manage to break one ofthe rules, please report a bug.
|
|
|
|
Furthermore, real numbers may be used as values, but it is not
|
|
recommended.
|
|
|
|
## Functions
|
|
Of not specified otherwise, all functions return `nil`.
|
|
`playername` always refers to the name of a player, as string.
|
|
`value` always refers to a number and for most functions it must always be equal to or greater than 0.
|
|
|
|
|
|
### `mana.set(playername, value)`
|
|
Sets the mana reserve of the specified player to `value`.
|
|
If `value` is smaller than 0, the mana will be set to 0.
|
|
If `value` is greater than the maximum, the mana will be set to the maximum.
|
|
|
|
|
|
### `mana.setmax(playername, value)`
|
|
Sets the maximum of the player to `value`.
|
|
|
|
If the new maximum would become smaller than the current value,
|
|
the current value will automatically be set to
|
|
the new maximum.
|
|
|
|
|
|
### `mana.get(playername)`
|
|
Returns the current mana of the specified player as number.
|
|
|
|
|
|
### `mana.getmax(playername)`
|
|
Returns the current maximum mana of the specified player as number.
|
|
|
|
|
|
### `mana.add(playername, value)`
|
|
Adds the specified non-negative amount of mana to the player, but only
|
|
if the sum would not be greater than the maximum,
|
|
|
|
#### Return value
|
|
* `true` on success, all mana has been added
|
|
* `false` on failure, no mana has been added
|
|
|
|
|
|
### `mana.subtract(playername, value)`
|
|
Subtracts the specified non-negative amount of mana from the player,
|
|
but only if the player has sufficient mana reservers.
|
|
|
|
#### Return value
|
|
* `true` on success, all mana has been subtracted
|
|
* `false` on failure, no mana has been subtraceed
|
|
|
|
|
|
### `mana.add_up_to(playername, value)`
|
|
Adds the specified non-negative amount of mana to the player, but it will
|
|
be capped at the maximum.
|
|
|
|
#### Return value
|
|
* `true, excess` on success, where `excess` is the amount of Mana which could not be added because it would have exceeded the maximum. `excess` equals `0` if all mana has been added
|
|
* `false` on failure (mana could not be added)
|
|
|
|
|
|
### `mana.subtract_up_to(playername, value)`
|
|
Subtracts the specified non-negative amount of mana from the player,
|
|
but if the difference is smaller than 0, the mana will be set to 0.
|
|
|
|
#### Return value
|
|
* `true, missing` on success, where `missing` is the amount of Mana which could not be subtracted because it would have exceeded 0. `missing` equals `0` if all mana has been subtracted
|
|
* `false` on failure (mana could not be subtracted)
|
|
|
|
|
|
|