API documentation for 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
* Only integer numbers are permitted for mana values

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.

If a real number is used as input for a value, it will be rounded
(“round up half” rule).

## 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.setregen(playername, value)`
Sets the mana regeneration per mana tick of the player to `value`.
Floating-point numbers are also permitted, in which the generation
of 1 mana takes longer than 1 mana tick. I.e. `0.5`. means
that 1 mana is generated every 2 mana ticks. A negative value means the
player loses mana.


The length of one “mana tick” is specified as the server-wide setting
`mana_default_regen` in seconds.


### `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.getregen(playername)`
Returns the current mana regneration per mana tick of the specified
player as number.
The length of one “mana tick” is specified as the server-wide setting
`mana_default_regen` in seconds.


### `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)


## Appendix
### General recommendations
If you want your mod to be portable, it is recommended that you balance your mod in such a way that it assumes
that every player starts with the following default mana values:

* Max. mana: 200
* Mana regeneration: 1 mana every 0.2 seconds

Also assume that the max. mana never changes.
This should (hopefully) ensure that multiple independent mana-using mods are more or less balanced when using
the default settings.

Also, to make life easier for subgame makers, define custom minetest.conf settings for your mod in order to
overwrite the mana costs (and other relevant values) used by your mod. That way, subgame makers only have to edit
minetest.conf, and not your mod.

You do not have to bother about default values if you want to directly integrate your mod in a subgame and do
not plan to release the mod independently.

The best way to reliable balance the mana values used by several mods is to create a standalone subgame. It is
highly recommended that you tweak the mana values of the mods to fit the subgame's needs.