Detailed Comparison of Open Source Timer Libraries for Love2D Games

So, I’ve been diving into LÖVE2D game development and wanted to get a handle on how to manage animations and tweens. I checked out a few timer libraries that I found online and decided to break them down for my own good.

For those new to animations, timer libraries play a crucial role by providing precise control over the timing and sequencing of animated elements. They can make your life much easier by managing complex animation sequences and are essential for easing and interpolation.

I’m just getting started in my LÖVE journey so take all the advice below with a grain of salt :)

TL;DR

I’ll be comparing  Trigger.lua, Timer.lua, and  Hump.timer. In case you just want the summary here a fancy table:

Functionality	Trigger.lua	Timer.lua	Hump.timer
One-time timer	✅	✅	✅
Recurring timer	❌	✅	✅
Continuous timer	❌	✅	✅
Cancel timer	❌	✅	✅
Clear all timers	✅	✅	✅
Pause/Resume timer	❌	❌	✅
Timer callbacks with args	❌	✅	✅
Elapsed time tracking	❌	✅	✅

If you want to get the details keep reading. For an even longer list of libraries check out this awesome-love2d list of tweening libraries.

Overview

Trigger.lua (SNKRX timer version)

This helper library was used in the game SNKRX. The author released the source code to the public, and has very detailed notes on the implementation of this game and others.

Link: Trigger.lua (288 lines, 11.8 KB)

Key Characteristics

1. Structure:
   • The library defines a Trigger class that manages callbacks for timed events.
   • It primarily handles adding and updating timers.
2. Functions and Methods:
   • add: Adds a new timer with a specified duration and callback.
   • update: Updates all timers, decreasing their time and calling the callbacks when the time elapses.
   • clear: Clears all active timers.
3. Implementation:
   • The timers are stored in a table called timers.
   • The update method iterates over the timers, reduces their time, and triggers the callback when the timer reaches zero.
   • Once a timer finishes, it is removed from the active timers list.

Timer.lua (Emoji-merge timer version)

By the same author of SNKRX, this (newer) version was used for the game Emoji-merge. The source code was also released to the public.

Link: Timer.lua (230 lines, 10.9 KB)

Key Characteristics

1. Enhanced Structure:
   • The latest version uses a more modular approach, separating concerns and adding more functionality.
   • Defines a Timer class with more advanced features and a cleaner structure.
2. Functions and Methods:
   • every: Adds a recurring timer that triggers a callback at regular intervals.
   • after: Adds a one-time timer that triggers a callback after a specified duration.
   • during: Adds a timer that triggers a callback continuously for a specified duration.
   • cancel: Cancels a specific timer.
   • clear: Clears all timers.
3. Implementation:
   • The timers are managed in a more sophisticated manner using a table self.timers to store active timers.
   • Timers are now objects themselves, with properties such as time, callback, and repeats for recurring timers.
   • The update method is more robust, handling different types of timers (one-time, recurring, continuous) and their respective callbacks.
   • Enhanced error handling and better separation of concerns.

Hump.timer

Hump is “a small collection of tools for developing games with LÖVE”. Among its libraries is this timer, and another well-known class implementation.

Link: Hump.timer (215 lines, 6.63 KB)

Key Characteristics

1. Structure:
   • Hump.timer is part of the larger Hump library, which provides various utilities for LÖVE.
   • It offers a comprehensive timer management system with a focus on simplicity and power.
2. Functions and Methods:
   • after: Adds a timer that calls a function after a specified delay.
   • every: Adds a recurring timer.
   • durning: Adds a function that is called continuously for a duration.
   • cancel: Cancels a timer.
   • clear: Clears all timers.
3. Implementation:
   • Uses a table to store all timers, similar to the other libraries.
   • Supports multiple types of timers: single execution, recurring, and continuous.
   • The update method processes all timers, decreasing their time and executing their callbacks when appropriate.
   • Provides a mechanism for pausing and resuming timers.

Side by Side Detailed Comparison

1. Structure:
   • Trigger.lua: Basic structure with limited functionality.
   • Timer.lua: Enhanced modular structure with advanced features.
   • Hump.timer: Comprehensive and part of a larger utility library, well-structured for various timer needs.
2. Functionality:
   • Trigger.lua: Basic add and update for timers.
   • Timer.lua: Rich functionality with every, after, and during methods.
   • Hump.timer: Similar to Timer.lua but includes additional features like pause and resume for timers.
3. Code Complexity:
   • Trigger.lua: Simplest and least complex.
   • Timer.lua: More complex due to additional features and modularity.
   • Hump.timer: Comparable to Timer.lua but integrated into a larger library, offering more utility functions.
4. Maintenance and Extensibility:
   • Trigger.lua: Easiest to maintain for small projects.
   • Timer.lua: Good balance of complexity and functionality for larger projects.
   • Hump.timer: Highly maintainable and extensible, suitable for complex projects.

Code Examples

Trigger.lua Example

local Trigger = require 'Trigger'

-- Usage example
local trigger = Trigger:new()

-- Add a timer that triggers after 2 seconds
trigger:add(2, function() print("2 seconds passed") end)

function love.update(dt) 
 trigger:update(dt) 
end

Timer.lua Example

local Timer = require 'Timer'

-- Usage example
local timer = Timer:new()

-- Add a timer that triggers after 2 seconds
timer:after(2, function() print("2 seconds passed") end)

-- Add a recurring timer that triggers every 1 second
timer:every(1, function() print("1 second interval") end)

-- Add a timer that triggers continuously for 5 seconds
local duringTimer = timer:during(5, function() print("During 5 seconds") end)

-- To cancel a timer
timer:cancel(duringTimer)

function love.update(dt)
    timer:update(dt)
end

Hump.timer Example

local Timer = require "hump.timer"

-- Usage example
local timer = Timer.new()

-- Add a timer that triggers after 2 seconds
timer:after(2, function() print("2 seconds passed") end)

-- Add a recurring timer that triggers every 1 second
timer:every(1, function() print("1 second interval") end)

-- Add a timer that triggers continuously for 5 seconds
timer:during(5, function() print("During 5 seconds") end)

-- Create a timer that can be paused and resumed
local pausableTimer = timer:after(10, function() print("10 seconds passed") end)

-- Pause timer
pausableTimer:pause()

-- Resume timer
pausableTimer:resume()

-- To cancel a timer
pausableTimer:cancel()

function love.update(dt)
    timer:update(dt)
end

Recap

Functionality	Trigger.lua	Timer.lua	Hump.timer
One-time timer	✅	✅	✅
Recurring timer	❌	✅	✅
Continuous timer	❌	✅	✅
Cancel timer	❌	✅	✅
Clear all timers	✅	✅	✅
Pause/Resume timer	❌	❌	✅
Timer callbacks with args	❌	✅	✅
Elapsed time tracking	❌	✅	✅

Notes

• One-time timer: A timer that triggers a callback once after a specified duration.
• Recurring timer: A timer that triggers a callback repeatedly at specified intervals.
• Continuous timer: A timer that triggers a callback continuously for a specified duration.
• Cancel timer: The ability to cancel a specific timer before it completes.
• Clear all timers: The ability to clear all active timers at once.
• Pause/Resume timer: The ability to pause and resume timers.
• Timer callbacks with arguments: Support for passing arguments to the callback function.
• Elapsed time tracking: Support for tracking the elapsed time of a timer.

Conclusion

Each timer library has its strengths and is suited to different needs:

• Trigger.lua: Ideal for simple projects requiring basic timer functionality.
• Timer.lua: A more advanced and feature-rich option, suitable for more complex projects.
• Hump.timer: Comprehensive and part of a larger utility library, offering additional features like pausing and resuming timers.

Depending on the complexity and requirements of your game, you can choose the library that best fits your needs.

Final Words

I have yet to go in depth with all the libraries. My best advice to find the right tool for you is to experiment with each one of them in a small test project to get a feel for how they work and how they integrate into your workflow.

• For Beginners and Simple Projects: Start with Trigger.lua for its simplicity.
• For Intermediate to Advanced Projects: Use Timer.lua for a good balance of features and complexity, or Hump.timer if you need advanced capabilities like pausing/resuming timers and prefer a library with extensive documentation and community support.

I am probably going to move from Trigger.lua to Timer.lua to Hump.timer as I feel comfortable with LÖVE.

Good luck! <3

Bonus: Tick

Ok, one more library for you, related to time but not a timer per-se: Tick is a “fixed timestep library for LÖVE”. This is stuff for quite some advanced needs.

Link: Tick (70 lines, 1.49 KB)