API.md

   1 API documentation for Mana 1.1.0
   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 Floating-point numbers are also permitted, in which the generation
  45 of 1 mana takes longer than 1 mana tick. I.e. `0.5`. means
  46 that 1 mana is generated every 2 mana ticks. A negative value means the
  47 player loses mana.
  48
  49
  50 The length of one “mana tick” is specified as the server-wide setting
  51 `mana_default_regen` in seconds.
  52
  53
  54 ### `mana.get(playername)`
  55 Returns the current mana of the specified player as number.
  56
  57
  58 ### `mana.getmax(playername)`
  59 Returns the current maximum mana of the specified player as number.
  60
  61
  62 ### `mana.getregen(playername)`
  63 Returns the current mana regneration per mana tick of the specified
  64 player as number.
  65 The length of one “mana tick” is specified as the server-wide setting
  66 `mana_default_regen` in seconds.
  67
  68
  69 ### `mana.add(playername, value)`
  70 Adds the specified non-negative amount of mana to the player, but only
  71 if the sum would not be greater than the maximum,
  72
  73 #### Return value
  74 * `true` on success, all mana has been added
  75 * `false` on failure, no mana has been added
  76
  77
  78 ### `mana.subtract(playername, value)`
  79 Subtracts the specified non-negative amount of mana from the player,
  80 but only if the player has sufficient mana reservers.
  81
  82 #### Return value
  83 * `true` on success, all mana has been subtracted
  84 * `false` on failure, no mana has been subtraceed
  85
  86
  87 ### `mana.add_up_to(playername, value)`
  88 Adds the specified non-negative amount of mana to the player, but it will
  89 be capped at the maximum.
  90
  91 #### Return value
  92 * `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
  93 * `false` on failure (mana could not be added)
  94
  95
  96 ### `mana.subtract_up_to(playername, value)`
  97 Subtracts the specified non-negative amount of mana from the player,
  98 but if the difference is smaller than 0, the mana will be set to 0.
  99
 100 #### Return value
 101 * `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
 102 * `false` on failure (mana could not be subtracted)
 103
 104
 105 ## Appendix
 106 ### General recommendations
 107 If you want your mod to be portable, it is recommended that you balance your mod in such a way that it assumes
 108 that every player starts with the following default mana values:
 109
 110 * Max. mana: 200
 111 * Mana regeneration: 1 mana every 0.2 seconds
 112
 113 Also assume that the max. mana never changes.
 114 This should (hopefully) ensure that multiple independent mana-using mods are more or less balanced when using
 115 the default settings.
 116
 117 Also, to make life easier for subgame makers, define custom minetest.conf settings for your mod in order to
 118 overwrite the mana costs (and other relevant values) used by your mod. That way, subgame makers only have to edit
 119 minetest.conf, and not your mod.
 120
 121 You do not have to bother about default values if you want to directly integrate your mod in a subgame and do
 122 not plan to release the mod independently.
 123
 124 The best way to reliable balance the mana values used by several mods is to create a standalone subgame. It is
 125 highly recommended that you tweak the mana values of the mods to fit the subgame's needs.