Chronos | Time Management Framework

Resources Community Resources
#1

Chronos: A robust Time Management library for Roblox Studio

Introduction

Hello all! I decided to release my own first open-source library.
I hope this library will be helpful for any devs, even just a little bit.

Overview

I created this library since when I first started developing, working with time was really frustrating and difficult, and now that I have better skills, I have decided to come up with Chronos, a time management library for Roblox Studio.
I made it to be modular, and feature-rich that utilizes Robloxā€™s DateTime constructor (which I highly recommend you use for newer projects).
Whether you are scheduling events, creating countdown timers, managing cooldowns, or simply formatting time displays, Chronos provides a clean, consistent API to handle most if not all of your timing needs.

Features

Chronos is organized into 6 interconnected modules, each handling a specific aspect of time management:

Chronos

The parent module of all the other modules, providing quick and common functions:

  • Grabs and imports all child modules for use
  • Many common functions like a ā€˜Yieldā€™ function that has optional debugging built in it
  • Version info

Core

The foundation of Chronos, providing essential DateTime manipulation factors that other modules use:

  • Unix timestamp conversion (seconds and milliseconds)
  • DateTime creation and modifying
  • Time difference calculations
  • Quick Date formatting

Timer

Create countdown and countup timers with event callbacks:

  • Progress tracking (numerical and percentage)
  • Pause, resume and reset functionality
  • Customizable display formatting
  • Completion callbacks

Cooldown

Very simple but useful cooldown management:

  • Track cooldown status and remaining time
  • Get progress as percentage
  • Reset cooldowns manually
  • Adjust durations on the fly

Scheduler

Schedule one-time and recurring events:

  • Precise timing control
  • Reschedule or cancel events
  • Monitor active scheduled events
  • Debug utilities for complex scheduling

Format

Format time values for display:

  • MM & HH:MM formatting
  • Human-readable formatting (ā€œ2 hours, 5 minutesā€)
  • Compact formatting (2h 5m 10s)
  • DateTime range formatting

Performance Considerations

Chronos is designed with performance in mind, which uses efficient functions for time calculations and avoiding some unnecessary bloat-script.
Tips for taking performance into consideration:

  • Make sure to cache formatted time strings instead of regenerating them every frame or so
  • For UI updates, maybe consider reducing update frequency to about 0.1s intervals
  • Make sure to use the appropriate function based on what you need

Conclusion

Chronos is a library designed to make timing a bit easier for developers.
This is just a quick breakdown of what it includes, go check out the github for more details and examples plus how to actually import in your game: Github

Time management is a fundamental requirement in game design. Whether your making a round system, or combat system with cooldowns, your bound to run into handling time, and not everyone wants to play around with different time functions and data-types, when you could be doing other things.

Happy coding!

Note: This library is provided under the ā€˜MITā€™ license. Feel free to use it in your own projects, commercial or otherwise.
5 Likes
#2

Does this yield? Since Iā€™m planning to use this for Round Timer with precise server-client synchronization. But I was wondering if it yields and if is there a method to automatically cancel/stop the timer. Nevermind I looked and found a ā€œCancelā€, but Iā€™m still wondering if it yields and do I have to automatically decrease the countdown?

1 Like
#3

The Timer module automatically decreases the countdown, and shouldnā€™t affect any code from running in the thread or function.

Here is an example, note you do need to use :OnTick method, with a function, which gets called each time the timer decrements or increments. (Gets called every tick or second)

local Chronos = require(game:GetService("ReplicatedStorage").Chronos)

-- Creating a timer...
local myTimer = Chronos.Timer.new("countdown", 30) -- Starts a timer for 30 seconds

-- Manipulate the myTimer object in any way, in order for it to start counting up or down, :Start() must be called
myTimer:Start()

-- In order to constantly get progress, use :OnTick()
myTimer:OnTick(function()
	-- Whatever you need in here...
	print(myTimer:GetProgressPercent())
end)
print("Anything else can happen here")
1 Like
#5

Is this faster than the built-in Roblox time library? Is it more accurate?