Improve timer, fixing #643 and adding display formatting options.

Scripts/Timer.lua

@@ -1,14 +1,23 @@
 -----
 --- Basic timer - after a specified number of seconds, the specified thing happens.
--- Usage:
+-- Example usage:
 --	local Timer = require("Timer")
 --
+--	-- This will be called when the timer runs out
 --	LevelFuncs.FinishTimer = function(healthWhenStarted, victoryMessage)
+--		-- Open a door, display a message, make an explosion... whatever you wish
 --		DoSomething(healthWhenStarted, victoryMessage)
 --	end
 --	
+--	-- This function triggers the timer
 --	LevelFuncs.TriggerTimer = function(obj) 
---		local myTimer = Timer.Create("my_timer", 5.0, false, true, "FinishTimer", Lara:GetHP(), "Well done!")
+--		local myTimer = Timer.Create("my_timer",
+--			5.0,
+--			false,
+--			{minutes = false, seconds = true, deciseconds = true},
+--			"FinishTimer",
+--			Lara:GetHP(),
+--			"Well done!")
 --		myTimer:Start()
 --	end
 --
@@ -22,20 +31,41 @@ LevelVars.__TEN_timer = {timers = {}}
 
 local Timer
 
-local unpausedColor = Color(255, 255, 255)
-local pausedColor = Color(255, 255, 0)
+local unpausedColor = TEN.Color(255, 255, 255)
+local pausedColor = TEN.Color(255, 255, 0)
 local str = TEN.Strings.DisplayString("TIMER", 0, 0, unpausedColor, false, {TEN.Strings.DisplayStringOption.CENTER, TEN.Strings.DisplayStringOption.SHADOW} )
 
 Timer = {
 	--- Create (but do not start) a new timer.
+	--
+	-- You have the option of displaying the remaining time on the clock. Timer format details:
+	--	-- deciseconds are 1/10th of a second
+	--	
+	--	-- mins:secs
+	--	local myTimeFormat1 = {minutes = true, seconds = true, deciseconds = false}
+	--
+	--	-- also mins:secs
+	--	local myTimeFormat2 = {minutes = true, seconds = true}
+	--	
+	--	-- secs:decisecs
+	--	local myTimeFormat3 = {seconds = true, deciseconds = true}
+	--
+	--	-- secs; also what is printed if you pass true instead of a table
+	--	local myTimeFormat4 = {seconds = true}
+	--
+	--__At any given time, only one timer can show its countdown__.
+	--
+	--Use this sparingly; in the classics, timed challenges did not have visible countdowns. For shorter timers, the gameplay benefit from showing the remaining time might not be necessary, and could interfere with the atmosphere of the level.
+	--
 	-- @string name A label to give this timer; used to retrieve the timer later
 	-- @number totalTime The duration of the timer, in seconds
 	-- @bool loop if true, the timer will start again immediately after the time has elapsed
-	-- @bool showString if true, the remaining time, rounded up, will show at the bottom of the screen. __At any given time, only one timer can show its remaining time__.
-	-- @string func The name of the LevelFunc member to call when the time is up
-	-- @param funcArgs the arguments with which the above function will be called
+	-- @tparam ?table|bool timerFormat If a table is given, the remaining time will be shown as a string, formatted according to the values in the table. If true, the remaining seconds, rounded up, will show at the bottom of the screen. If false, the remaining time will not be shown on screen. 
+	-- @string func The name of the LevelFunc member to call when the time is upssss
+	-- @param[opt] ... a variable number of arguments with which the above function will be called
 	-- @return The timer in its paused state
-	Create = function(name, totalTime, loop, showString, func, ...)
+	--
+	Create = function(name, totalTime, loop, timerFormat, func, ...)
 		local obj = {}
 		local mt = {}
 		mt.__index = Timer
@@ -45,7 +75,6 @@ Timer = {
 		LevelVars.__TEN_timer.timers[name] ={} 
 		local thisTimer = LevelVars.__TEN_timer.timers[name]
 		thisTimer.name = name
-		thisTimer.showString = showString
 		thisTimer.totalTime = totalTime
 		thisTimer.remainingTime = totalTime
 		thisTimer.func = func
@@ -53,6 +82,11 @@ Timer = {
 		thisTimer.loop = loop
 		thisTimer.active = false
 		thisTimer.paused = true
+		if type(timerFormat) == "table" then
+			thisTimer.timerFormat = timerFormat
+		elseif timerFormat then
+			thisTimer.timerFormat = {seconds = true}
+		end
 		return obj
 	end;
 
@@ -89,9 +123,9 @@ Timer = {
 			thisTimer.active = true
 		end
 
-		LevelVars.__TEN_timer.timers[t.name].paused = false
+		thisTimer.paused = false
 
-		if thisTimer.showString then
+		if thisTimer.timerFormat then
 			str:SetColor(unpausedColor)
 		end
 	end;
@@ -101,7 +135,7 @@ Timer = {
 	Pause = function(t)
 		local thisTimer = LevelVars.__TEN_timer.timers[t.name]
 		thisTimer.paused = true
-		if thisTimer.showString then
+		if thisTimer.timerFormat then
 			str:SetColor(pausedColor)
 		end
 	end,
@@ -112,6 +146,20 @@ Timer = {
 		LevelVars.__TEN_timer.timers[t.name].active = false
 	end,
 	
+	--- Get whether or not the timer is active
+	-- @param t the timer in question
+	-- @return true if the timer is active, false if otherwise
+	IsActive = function(t)
+		return LevelVars.__TEN_timer.timers[t.name].active
+	end,
+
+	--- Get whether or not the timer is paused
+	-- @param t the timer in question
+	-- @return true if the timer is paused, false if otherwise
+	IsPaused = function(t)
+		return LevelVars.__TEN_timer.timers[t.name].paused
+	end,
+
 	--- Get the remaining time for a timer.
 	-- @param t the timer in question
 	-- @return the time in seconds remaining on the clock
@@ -173,11 +221,68 @@ Timer = {
 				end
 			end
 
-			if t.showString then
+			if t.timerFormat then
 				TEN.Strings.HideString(str)
-				str:SetKey(tostring(math.ceil(t.remainingTime)))
+
+				local fmt = ""
+				local remaining = math.max(t.remainingTime, 0)
+
+				local round = math.floor
+				local subSecond = remaining - math.floor(remaining)
+
+				local fmtBefore = false
+
+				-- deciseconds
+				if t.timerFormat.deciseconds then
+					fmt = math.floor(10*subSecond)
+					fmtBefore = true
+				end
+
+				-- seconds
+				if t.timerFormat.seconds then
+					if not fmtBefore then
+						round = math.ceil
+					else
+						round = math.floor
+						fmt = ":" .. fmt
+					end
+					local roundedSeconds = round(remaining)
+					local toBeDisplayed = roundedSeconds
+					if t.timerFormat.minutes then
+						toBeDisplayed = roundedSeconds % 60
+					end
+					fmt = string.format("%02d", toBeDisplayed) .. fmt
+
+					remaining = roundedSeconds 
+					fmtBefore = true
+				end
+
+				-- minutes
+				if t.timerFormat.minutes then
+					if not fmtBefore then
+						round = math.ceil
+					else
+						round = math.floor
+						fmt = ":" .. fmt
+					end
+
+					local roundedMinutes = round(remaining/60)
+					local toBeDisplayed = roundedMinutes
+
+					fmt = string.format("%02d", toBeDisplayed) .. fmt
+					fmtBefore = true
+				end
+
+				str:SetKey(fmt)
 				local myX, myY = PercentToScreen(50, 90)
 				str:SetPosition(myX, myY)
+
+				-- Do this again in case the player has loaded while the timer was paused already
+				-- Need a better solution for this
+				if t.paused then
+					str:SetColor(pausedColor)
+				end
+
 				TEN.Strings.ShowString(str, 1)
 			end