Chronos | Time Management Framework

[RobloxJrTrainer]

Chronos: A Robust Time Management library for Roblox Studio (V0.1.1)

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.
The Github is broken right now, you can get the rbxm here:
Chronos.v0.1.1.rbxm (11.1 KB)

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.

Note: This library is provided under the ‘MIT’ license. Feel free to use it in your own projects, commercial or otherwise.

[weakroblox35]

@RobloxJrTrainer

Create countdown and countup timers with event callbacks:

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?

[RobloxJrTrainer]

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")

[lyrnu]

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

[RobloxJrTrainer]

This module is purely to streamline the process of handling time;
whether you need some type of Cooldown, a Timer, or Scheduling recurring or one time events.
The time operations build upon the built-in time library, so about the same accuracy.

[Neuroticxs (Ace)]

There is a hidden memory leak I’d like to point out on this library. First of all I love this library easy to make timers, schedules etc.

I almost rewrote my entire game because of this. The game gets slower overtime without me realizing it only to find out that my players started to complain after 24 hours ALWAYS after a new update comes out that they said the game is so slow.

I looked the statistics on the creator page and indeed that server memory usage by age keeps increasing indefinitely.

I can’t seem to find it I checked all my code that that I make sure all connections, tables, references are always cleaned up. But after doing all that It’s still happening.

but then I learned how to use LuauHeap on the console and saw Chronos Scheduler keeps increasing in bytes and never goes down.

and checked the updateSchedulerStatus() Callback since all of the timers are handled there and at first I also didn’t notice and I saw that updateConnection is getting disconnected when no events are created.

But you forgot to also return if there is an event and a connection to heartbeart is already connected.

here is the fix:

[RobloxJrTrainer]

Thanks for pointing that out and giving out the fix!

[BabanizPROcuk (EmpressCrimson)]

The github repository link is broken

[RobloxJrTrainer]

I updated the post, for now just use the .rbxm.