Update for 0.4.16 settings syntax
[minetest_mana.git] / API.md
1 API documentation for Mana 1.2.0
2 ================================
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.
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:
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
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.
20 If a real number is used as input for a value, it will be rounded
21 (“round up half” rule).
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.
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.
35 ### `mana.setmax(playername, value)`
36 Sets the maximum of the player to `value`.
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.
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.
50 The length of one “mana tick” is specified as the server-wide setting
51 `mana_default_regen` in seconds.
54 ### `mana.get(playername)`
55 Returns the current mana of the specified player as number.
58 ### `mana.getmax(playername)`
59 Returns the current maximum mana of the specified player as number.
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.
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,
73 #### Return value
74 * `true` on success, all mana has been added
75 * `false` on failure, no mana has been added
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.
82 #### Return value
83 * `true` on success, all mana has been subtracted
84 * `false` on failure, no mana has been subtraceed
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. 
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)
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.
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)
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:
110 * Max. mana: 200
111 * Mana regeneration: 1 mana every 0.2 seconds
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.
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.
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.
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.