forked from mtcontrib/minetest_mana
73 lines
2.2 KiB
Markdown
73 lines
2.2 KiB
Markdown
|
API documentation for Mana 0.2.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.
|
||
|
|
|
||
|
|
|
||
|
|
### `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 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(playername, value)`
|
||
|
|
Subtracts the specified 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
|