schedule
Timers that fire callbacks, advanced from your update.
Games are full of things that should happen later or on a beat. Spawn a wave
every few seconds, flash a message for half a second, fire a shot after a
short wind-up, blink a cursor. Wiring each of those up as its own countdown
variable is repetitive. A Scheduler keeps the counters for you. You hand it
a delay and a callback, advance it once per frame from update, and it calls
the callback when the time comes.
after runs a callback once after a delay. every runs one on a repeat, for
a set number of times or forever. during calls a callback every frame for a
stretch of time, handing it the frame's dt, which suits an effect that has
to run continuously for a moment, like a shake or a fade. Each returns a
TimerId you can hand to cancel, and clear drops every timer at once.
The callbacks are ordinary closures, so they capture whatever they need from around them, and a callback may schedule or cancel more timers, including itself. A timer added from inside a callback waits until the next update to run.
This is an opt-in module, imported on its own with import nim2d/schedule.
The core engine does not pull it in.
type TimerId = int
Identifies a scheduled timer, handed back by after, every
and during and accepted by cancel.
type Scheduler = ref object
Holds the live timers. Make one with newScheduler
and advance it every frame with update.
newScheduler ¶
proc newScheduler(): Scheduler
An empty scheduler. Advance it once per frame with update, and add timers
with after, every and during.
Returns
Scheduler
after discardable ¶
proc after(s: Scheduler; delay: float; action: proc ()): TimerId
Run action once, delay seconds from now. Returns an id you can pass to
cancel to call it off before it fires.
Parameters
-
s(Scheduler) -
delay(float) -
action(proc ())
Returns
TimerId
every discardable ¶
proc every(s: Scheduler; interval: float; action: proc (); count = -1): TimerId
Run action every interval seconds. It repeats forever by default, or
pass count to stop after that many fires. Returns an id for cancel.
Parameters
-
s(Scheduler) -
interval(float) -
action(proc ()) -
count(auto)
Returns
TimerId
during discardable ¶
proc during(s: Scheduler; duration: float; action: proc (dt: float); onDone: proc () = nil): TimerId
Call action every frame for duration seconds, handing it the frame's
dt, then call onDone once if it is set. Good for an effect that has to
run continuously for a fixed time. Returns an id for cancel.
Parameters
-
s(Scheduler) -
duration(float) -
action(proc (dt: float)) -
onDone(proc ())
Returns
TimerId
cancel ¶
proc cancel(s: Scheduler; id: TimerId)
Stop the timer with this id, whether or not it has fired. An id that is not
there is ignored, so cancelling twice is safe.
Parameters
-
s(Scheduler) -
id(TimerId)
clear ¶
proc clear(s: Scheduler)
Drop every timer. Safe to call from inside a callback.
Parameters
-
s(Scheduler)
update ¶
proc update(s: Scheduler; dt: float)
Advance every timer by dt seconds and fire the callbacks that come due.
Call this once a frame from your own update with the same dt. A timer a
callback adds during this call does not run until the next one.
Parameters
-
s(Scheduler) -
dt(float)