Timer Module

Roblox Timer Module Documentation

This module provides a simple and versatile timer functionality for your Roblox scripts. It allows creating timers with minutes and seconds, pausing/resuming them, and receiving notifications when the timer finishes.

Features:

• Create timers with minutes and seconds.
• Optional progress callback to track remaining time during countdown.
• Pause and resume timers.
• Reset timers back to their original duration.
• Fire a custom event (optional) when the timer finishes.

How to Use:

1. Place the following script inside a ModuleScript in ReplicatedStorage.

Timer.lua:

local module = {}

local function getFormattedTime(seconds)
  local minutes = math.floor(seconds / 60)
  local secondsLeft = seconds - minutes * 60
  return minutes .. "m " .. secondsLeft .. "s"
end

local function timerThread(timer)
  while timer.running do
    wait(1)
    if not timer.paused then
      timer.remainingTime = timer.remainingTime - 1
      if timer.remainingTime <= 0 then
        timer.running = false
        timer.finishedEvent:Fire()
      elseif timer.progressCallback then
        timer.progressCallback(timer.remainingTime)
      end
    end
  end
end

function module.new(minutes, seconds, finishedCallback, progressCallback, eventName)
  local totalSeconds = minutes * 60 + seconds
  local timer = {
    remainingTime = totalSeconds,
    running = true,
    paused = false,
    finishedEvent = eventName and Instance.new("BindableEvent", eventName) or Instance.new("BindableEvent"),
    progressCallback = progressCallback,
  }
  if finishedCallback then
    timer.finishedEvent:Connect(finishedCallback)
  end
  task.delay(0, function()
    timerThread(timer)
  end)
  return timer
end

function module.getTimeLeft(timer)
  if not timer.running then
    return "Timer Finished"
  end
  return getFormattedTime(timer.remainingTime)
end

function module.pauseTimer(timer)
  if timer.running then
    timer.paused = true
  end
end

function module.resumeTimer(timer)
  if timer.paused then
    timer.paused = false
  end
end

function module.resetTimer(timer)
  timer.remainingTime = timer.originalTime or 0 -- Consider adding an optional originalTime argument to new
  timer.paused = false
end

return module

1. In any script, require the module:

local Timer = require(game.ReplicatedStorage.Timer)

Example Script:

local function onTimerFinish()
  print("Timer finished!")
end

local function onProgress(timeLeft)
  print("Time remaining: " .. Timer.getTimeLeft(myTimer))
end

local myTimer = Timer.new(
  1, -- Minutes
  30, -- Seconds
  onTimerFinish, -- Finished Callback (Optional)
  onProgress,  -- Progress Callback (Optional)
  "MyCustomFinishedEvent" -- Custom Event Name (Optional)
)

-- After 1 minute and 30 seconds:
--  * onTimerFinish function will be called.
--  * onProgress function will be called periodically with remaining time.
--  * "MyCustomFinishedEvent" will fire (if provided).

-- You can pause, resume, and reset the timer:
Timer.pauseTimer(myTimer)
wait(30) -- Wait for 30 seconds
Timer.resumeTimer(myTimer)

-- Reset the timer back to 1 minute 30 seconds
Timer.resetTimer(myTimer)

Additional Notes:

• The finishedCallback and progressCallback are optional arguments in the new function.
• If no custom event name is provided, a default BindableEvent is created.
• Use Timer.getTimeLeft(timer) to get the remaining time in a formatted string or "Timer Finished" if the timer has stopped.

This documentation provides a basic overview of the module. You can explore the source code (Timer.lua) for a detailed understanding of each function and its behavior.