Egg Hatch Timer Luau Module

A transparent Roblox Studio Luau hatch timer module with start, remaining-time, active-state, and cancellation helpers for experiences you can edit.

Roblox Studio ModuleScript

What this script does

Create named hatch timers without polling every frame. A callback runs only if the same timer is still active when its duration ends.

Best for
Prototype egg incubation, crafting, cooldown, and build timers in a Studio project you own or can edit.
Language
Luau
Version
1.0.0
Validation
Luau checked · Studio integration required
Luau checked · Studio integration required

Official Luau 0.735 parsing and static analysis pass with Roblox host types stubbed. Test the actual Instance, service, or event integration in a separate Studio place before production use.

Included behavior

  • Named timers prevent duplicate callbacks
  • Remaining-time and active-state helpers
  • Cancellation without hidden background work
  • Strict Luau types and no dependencies

Install in the stated runtime

  1. 1
    Create a ModuleScript in ServerScriptService or ReplicatedStorage.
  2. 2
    Paste the complete source and name the module HatchTimer.
  3. 3
    Require it from a server Script and call start with your own egg id, duration, and callback.

Minimal usage example

local HatchTimer = require(game.ReplicatedStorage.HatchTimer)

HatchTimer.start("egg-42", 90, function(eggId)
	print(eggId .. " is ready to hatch")
end)

print(HatchTimer.remaining("egg-42"))

Example inputs and result

Supply
A unique Egg id, duration in seconds, and a completion callback.
Expect
start schedules that callback; remaining reads the time left for the same id.

These notes explain the example above. Read the complete source for every exported function and edge case before integrating it.

Complete source

No hidden import, minified block, or shortened loader.

--!strict
-- MIT License. For Roblox Studio experiences you own or can edit.
-- Pure timer module: no HTTP, remote loading, executor APIs, or client modification.

export type HatchTimer = {
	startedAt: number,
	durationSeconds: number,
	cancelled: boolean,
}

local HatchTimerModule = {}
local activeTimers: { [string]: HatchTimer } = {}

function HatchTimerModule.start(
	id: string,
	durationSeconds: number,
	onReady: (string) -> ()
): HatchTimer
	assert(id ~= "", "Timer id cannot be empty")
	assert(durationSeconds >= 0, "Duration must be zero or greater")
	assert(type(onReady) == "function", "onReady must be a function")

	HatchTimerModule.cancel(id)
	local timer: HatchTimer = {
		startedAt = os.clock(),
		durationSeconds = durationSeconds,
		cancelled = false,
	}
	activeTimers[id] = timer

	task.delay(durationSeconds, function()
		if timer.cancelled or activeTimers[id] ~= timer then
			return
		end
		activeTimers[id] = nil
		onReady(id)
	end)

	return timer
end

function HatchTimerModule.remaining(id: string): number
	local timer = activeTimers[id]
	if not timer or timer.cancelled then
		return 0
	end
	local elapsed = os.clock() - timer.startedAt
	return math.max(0, timer.durationSeconds - elapsed)
end

function HatchTimerModule.cancel(id: string): boolean
	local timer = activeTimers[id]
	if not timer then
		return false
	end
	timer.cancelled = true
	activeTimers[id] = nil
	return true
end

function HatchTimerModule.isActive(id: string): boolean
	return HatchTimerModule.remaining(id) > 0
end

return table.freeze(HatchTimerModule)
SHA-2562d5bdf711e12dfd458e9bd825e07a5c052de021d2755ab1338eb321f8daa3573

Outside this script’s scope

  • Connect to or inspect Steal An Egg
  • Automate another player or experience
  • Use HTTP, remote code, or executor APIs

Found a problem or a better approach?

Tell us what failed, what you expected, and whether the issue happened in the Luau CLI or Roblox Studio. Suggestions for clearer types, safer server checks, or a more useful API are welcome.

Do not submit credentials, private project files, or account data.