---

Why

Roblox gives you task.delay, task.wait, and RunService.Heartbeat. They work, but every non-trivial codebase ends up rebuilding the same things on top: cancellation tokens, scope-based cleanup, pause/resume, time-scaling for slow motion, profiling hot callbacks. chrono is that layer, written once.

local chrono = require(path.to.chrono)

local scope = chrono.scope()

scope:every(5, function()
    print("every 5 seconds")
end)

scope:after(2, function()
    print("once, in 2 seconds")
end)

scope:frame(function(dt)
    camera.CFrame *= CFrame.Angles(0, dt, 0)
end)

-- later: one call cleans up everything
scope:destroy()

---

Features

---

Installation

Wally

Add to your wally.toml:

[dependencies]
chrono = "iamthebestts/chrono@0.1.0"

Then run wally install.

pesde

Add to your pesde.toml:

[dependencies]
chrono = { name = "iamthebestts/chrono", version = "^0.1.0" }

Then run pesde install.

Roblox model

Grab the .rbxm from Releases or the Creator Store and drop it into ReplicatedStorage.

---

Quick start

local chrono = require(ReplicatedStorage.Packages.chrono)

-- 1. Create a scope
local scope = chrono.scope()

-- 2. Run something once after a delay
scope:after(3, function()
    print("3 seconds later!")
end)

-- 3. Run something every N seconds (fires immediately, then repeats)
local handle = scope:every(5, function()
    print("heartbeat every 5s")
end)

-- 4. Run every frame
scope:frame(function(dt)
    part.Position += Vector3.new(0, speed * dt, 0)
end)

-- 5. Fixed-rate physics at 60 Hz
scope:tick(60, function(dt)
    player.Position += player.Velocity * dt
end)

-- 6. Pause / resume
scope:pause()   -- freezes all timers; frame fires with dt=0
scope:resume()  -- picks up where it left off, no backlog

-- 7. Slow motion
scope:setTimeScale(0.5)

-- 8. Cancel a single task
handle:cancel()

-- 9. Destroy the scope — cancels everything
scope:destroy()

---

API

Full documentation at iamthebestts.github.io/chrono

Module

Scope

Handle

Config

All scheduling methods accept an optional config table:

scope:after(1, fn, { name = "respawn_timer" })
scope:tick(60, fn, { name = "physics", maxCatchup = 4 })

---

Profiler

local data = chrono.profile()

for name, entry in data do
    print(name, "avg:", entry.avgMs, "max:", entry.maxMs, "p99:", entry.p99Ms)
end

-- entry shape:
-- {
--     name: string,
--     count: number,
--     avgMs: number,
--     maxMs: number,
--     p99Ms: number,
--     totalMs: number,
-- }

chrono.reset_profiler() -- clear all data

---

Integration

With Trove

local trove = Trove.new()
local scope = chrono.scope()

trove:Add(scope) -- Trove calls scope:Destroy() on cleanup

With Signals

local scope = chrono.scope()

scope:every(5, function()
    mySignal:Fire("tick")
end)

Alongside RunService

chrono uses a single RunService.Heartbeat connection internally. Your own connections work independently — no conflicts.

---

Contributing

See CONTRIBUTING.md for setup, conventions, and workflow.

---

License

Released under the MIT License.