minetest_mana/API.md

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.setregen(playername, value)

Sets the mana regeneration per mana tick of the player to value. Negative values are not permitted. 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)