Timer.start
luastra/timerTimer.start(options: StartOptions): RequestId
Registers a one-shot timer under the supplied stable string ID and returns an acknowledgement RequestId. After the delay, Luastra sends handle("timer", id, value); it does not call app.resolve for expiry.
Before you use it
Add luastra/timer to this module's dependencies in luastra.json, then import it with require("luastra/timer"). Declare timer.control in luastra.json and implement app.handle for timer events. The maximum delay is 60,000 ms.
How it fits
start, restart, and cancel return an acknowledgement RequestId, but timer.control completions are intentionally not delivered to app.resolve. A one-shot expiry arrives later as app.handle("timer", timerId, value).
When to use it
Use Timer.start for delayed transitions, temporary feedback, debouncing, or advancing a game after the user has had time to see a result. Choose a stable purpose-specific ID and handle repeated starts deliberately rather than creating unbounded timers.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| options | StartOptions | Stable timer ID, bounded delay in milliseconds, and optional event value. |
| options.id | string | Stable lowercase path ID delivered with the one-shot timer event. |
| options.delayMs | integer (0..60000) | Delay before delivery, in milliseconds. |
| options.value | string? | Optional bounded value delivered with the timer event. |
Returns
RequestId — an opaque acknowledgement token for the timer control request. Timer acknowledgements do not enter app.resolve; an uncancelled expiry arrives through app.handle.
What happens next
The requested timer operation is acknowledged; an uncancelled start or restart later emits one timer event.
Failures and fixes
Missing timer.control, an invalid lowercase timer id, a delay outside 0..60000, or an oversized value fails before a timer event is scheduled. Treat late events as stale if the owning state has already changed.
Availability
Public-source alpha API in 0.5.0-alpha; exact background timing remains host-dependent.
Focused example
local Timer = require("luastra/timer")
Timer.start { id = "game/next-card", delayMs = 1500, value = "advance" }Continue with a complete recipe
This checked recipe uses Timer.start inside complete authored files with the required manifest, test, and run steps.
Open run a delayed action recipe