Change the add and subtract functions, add new

API.md

@@ -27,7 +27,7 @@ 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.
+`value` always refers to a number and for most functions it must always be equal to or greater than 0.
 
 
 ### `mana.set(playername, value)`
@@ -53,20 +53,39 @@ Returns the current maximum mana of the specified player as number.
 
 
 ### `mana.add(playername, value)`
-Adds the specified amount of mana to the player, but it will be capped
+Adds the specified non-negative amount of mana to the player, but only
-at the maximum. 
+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)`
-### `mana.subtract(playername, value)`
+Subtracts the specified non-negative amount of mana from the player, 
-Subtracts the specified amount of mana from the player, but only
+but if the difference is smaller than 0, the mana will be set to 0.
-if the player has sufficient mana reservers.
 
 #### Return value
-* `true` on success, all mana has been subtracted
+* `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, no mana has been subtraceed
+* `false` on failure (mana could not be subtracted)
+
+
+

init.lua

@@ -63,15 +63,16 @@ function mana.getmax(playername)
 end
 
 --[[
-Adds the specified amount of mana to the player, but will
+Adds up to the specified amount of mana to the player.
-respect the player's maximum.
+If the sum would be greater than the maximum, the new
+mana amount will be capped at the maximum.
 
 returns:
 - true, excess on success, where excess is the amount of mana which
   was no
 - false on failure
 ]]
-function mana.add(playername, value)
+function mana.add_up_to(playername, value)
 	local t = mana.playerlist[playername]
 	if(t ~= nil and value >= 0) then
 		local excess
@@ -90,12 +91,31 @@ function mana.add(playername, value)
 end
 
 
+--[[
+Adds the specified amount of mana to the player,
+iff it would not exceed the maximum.
+
+returns:
+- true on success, all mana has been added
+- false on failure, no mana has been added
+]]
+function mana.add(playername, value)
+	local t = mana.playerlist[playername]
+	if(t ~= nil and ((t.mana + value) <= t.maxmana) and value >= 0) then
+		t.mana = t.mana + value 
+		mana.hud_update(playername)
+		return true
+	else
+		return false
+	end
+end
+
 --[[
 Subtracts the specified amount of mana from the player,
 iff the player has enough mana reserves.
 
 returns:
-- true on success, mana has been subtracted
+- true on success, all mana has been subtracted
 - false on failure, no mana has been subtracted
 ]]
 function mana.subtract(playername, value)
@@ -110,6 +130,35 @@ function mana.subtract(playername, value)
 end
 
 
+--[[
+Subtracts up to the specified amount of mana from the player.
+
+returns:
+- true, missing on success, where missing is the amount of mana which could not been subtracted
+- false on failure, no mana has been subtracted
+]]
+function mana.subtract_up_to(playername, value)
+	local t = mana.playerlist[playername]
+	if(t ~= nil and value >= 0) then
+		local missing
+		if((t.mana - value) < 0) then
+			missing = math.abs(t.mana - value)
+			t.mana = 0
+		else
+			missing = 0
+			t.mana = t.mana - value
+		end
+		mana.hud_update(playername)
+		return true, missing
+	else
+		return false
+	end
+end
+
+
+
+
+
 --[===[
 	File handling, loading data, saving data, setting up stuff for players.
 ]===]