API.md

   1 API documentation for Mana 1.0.1
   2 ================================
   3
   4 ## Introduction
   5 The API of the Mana mod allows you to set and receive
   6 the current and maxiumum mana reserves of a player,
   7 and to subtract and add mana.
   8
   9 ## The basic rules
  10 For integrity reasons, this mod will ensure that the following assumptions
  11 are true at all times for all players:
  12
  13 * Current and maximum mana can never be smaller than 0
  14 * The current value must not be greater than the maximum value
  15 * Only integer numbers are permitted for mana values
  16
  17 It should be not possible to break these rules using this API alone.
  18 If you somehow manage to break one ofthe rules, please report a bug.
  19
  20 If a real number is used as input for a value, it will be rounded
  21 (“round up half” rule).
  22
  23 ## Functions
  24 Of not specified otherwise, all functions return `nil`.
  25 `playername` always refers to the name of a player, as string.
  26 `value` always refers to a number and for most functions it must always be equal to or greater than 0.
  27
  28
  29 ### `mana.set(playername, value)`
  30 Sets the mana reserve of the specified player to `value`.
  31 If `value` is smaller than 0, the mana will be set to 0.
  32 If `value` is greater than the maximum, the mana will be set to the maximum.
  33
  34
  35 ### `mana.setmax(playername, value)`
  36 Sets the maximum of the player to `value`.
  37
  38 If the new maximum would become smaller than the current value,
  39 the current value will automatically be set to
  40 the new maximum.
  41
  42 ### `mana.setregen(playername, value)`
  43 Sets the mana regeneration per mana tick of the player to `value`.
  44 Negative values are not permitted.
  45 The length of one “mana tick” is specified as the server-wide setting
  46 `mana_default_regen` in seconds.
  47
  48
  49 ### `mana.get(playername)`
  50 Returns the current mana of the specified player as number.
  51
  52
  53 ### `mana.getmax(playername)`
  54 Returns the current maximum mana of the specified player as number.
  55
  56
  57 ### `mana.getregen(playername)`
  58 Returns the current mana regneration per mana tick of the specified
  59 player as number.
  60 The length of one “mana tick” is specified as the server-wide setting
  61 `mana_default_regen` in seconds.
  62
  63
  64 ### `mana.add(playername, value)`
  65 Adds the specified non-negative amount of mana to the player, but only
  66 if the sum would not be greater than the maximum,
  67
  68 #### Return value
  69 * `true` on success, all mana has been added
  70 * `false` on failure, no mana has been added
  71
  72
  73 ### `mana.subtract(playername, value)`
  74 Subtracts the specified non-negative amount of mana from the player,
  75 but only if the player has sufficient mana reservers.
  76
  77 #### Return value
  78 * `true` on success, all mana has been subtracted
  79 * `false` on failure, no mana has been subtraceed
  80
  81
  82 ### `mana.add_up_to(playername, value)`
  83 Adds the specified non-negative amount of mana to the player, but it will
  84 be capped at the maximum.
  85
  86 #### Return value
  87 * `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
  88 * `false` on failure (mana could not be added)
  89
  90
  91 ### `mana.subtract_up_to(playername, value)`
  92 Subtracts the specified non-negative amount of mana from the player,
  93 but if the difference is smaller than 0, the mana will be set to 0.
  94
  95 #### Return value
  96 * `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
  97 * `false` on failure (mana could not be subtracted)
  98
  99
 100 ## Appendix
 101 ### General recommendations
 102 If you want your mod to be portable, it is recommended that you balance your mod in such a way that it assumes
 103 that every player starts with the following default mana values:
 104
 105 * Max. mana: 200
 106 * Mana regeneration: 1 mana every 0.2 seconds
 107
 108 Also assume that the max. mana never changes.
 109 This should (hopefully) ensure that multiple independent mana-using mods are more or less balanced when using
 110 the default settings.
 111
 112 Also, to make life easier for subgame makers, define custom minetest.conf settings for your mod in order to
 113 overwrite the mana costs (and other relevant values) used by your mod. That way, subgame makers only have to edit
 114 minetest.conf, and not your mod.
 115
 116 You do not have to bother about default values if you want to directly integrate your mod in a subgame and do
 117 not plan to release the mod independently.
 118
 119 The best way to reliable balance the mana values used by several mods is to create a standalone subgame. It is
 120 highly recommended that you tweak the mana values of the mods to fit the subgame's needs.