Druid Timer Component

Description

The Timer component provides a way to create and manage countdown or countup timers in your UI. It can be used for game timers, cooldowns, or any feature that requires time tracking with visual feedback.

Features

Countdown and countup timer modes
Customizable time format display
Pause, resume, and reset functionality
Events for timer updates and completion
Optional text component integration for visual display
Support for different time units (seconds, minutes, hours)

Basic Usage

-- Basic countdown timer (10 seconds)
local timer = self.druid:new_timer(10, true)

-- Start the timer
timer:start()

Parameters

time: The initial time value in seconds
is_countdown: (optional) Boolean indicating if this is a countdown timer (default: false)

Methods

-- Start the timer
timer:start()

-- Pause the timer
timer:pause()

-- Resume a paused timer
timer:resume()

-- Reset the timer to its initial value
timer:reset()

-- Set a new time value
timer:set_time(30) -- Set to 30 seconds

-- Get current time value
local current_time = timer:get_time()

-- Check if timer is running
local is_running = timer:is_running()

-- Set a text component to display the timer
local text = self.druid:new_text("timer_text")
timer:set_text(text)

-- Set custom time format
timer:set_format(function(self, time)
    local minutes = math.floor(time / 60)
    local seconds = math.floor(time % 60)
    return string.format("%02d:%02d", minutes, seconds)
end)

Events

-- Subscribe to timer tick event (called every frame while timer is running)
timer.on_tick:subscribe(function(self, value)
    print("Timer value: " .. value)
end)

-- Subscribe to timer completion event
timer.on_complete:subscribe(function(self)
    print("Timer completed!")
end)

Examples

-- Create a 5-minute countdown timer with text display
local timer = self.druid:new_timer(300, true) -- 300 seconds = 5 minutes
local text = self.druid:new_text("timer_text")
timer:set_text(text)
timer:set_format(function(self, time)
    local minutes = math.floor(time / 60)
    local seconds = math.floor(time % 60)
    return string.format("%02d:%02d", minutes, seconds)
end)
timer:start()

-- Create a stopwatch (countup timer)
local stopwatch = self.druid:new_timer(0, false)
local text = self.druid:new_text("stopwatch_text")
stopwatch:set_text(text)
stopwatch:start()

-- Create a game round timer with events
local round_timer = self.druid:new_timer(60, true) -- 60 second round
round_timer.on_tick:subscribe(function(self, value)
    if value <= 10 then
        -- Last 10 seconds, show warning
        print("Time is running out!")
    end
end)
round_timer.on_complete:subscribe(function(self)
    -- Round is over
    print("Round completed!")
end)
round_timer:start()

Notes

The timer component updates every frame while running
For countdown timers, the timer completes when it reaches 0
For countup timers, you need to manually check for completion or set a target time
The default time format is seconds with one decimal place (e.g., "10.0")
You can customize the time format to display hours, minutes, seconds, or any other format
The timer component can be paused, resumed, and reset at any time
When using with a text component, the timer automatically updates the text display
The timer value is in seconds, but you can convert it to other units in your format function

3.4 KiB Raw Blame History