Skip to content

Timers

A timer calls a handler of your module later: a building is ready in two hours, a reward arrives tomorrow, an auction closes.

type Player struct {
rudder.Player
Levels rudder.Records[Level]
Built rudder.Timer[Upgrade]
}
//rudder:mutation
func (player *Player) Start(upgrade Upgrade) error {
player.Built.Key(upgrade.Building).At(rudder.Now().Add(2*time.Hour), upgrade)
return nil
}
func (player *Player) OnBuilt(upgrade Upgrade) error {
player.Levels.Get(upgrade.Building).Reached.Add(1)
return nil
}
  • A timer is a field rudder.Timer[T] of the player type or of the shared type. T is the payload, a contract type. Its handler is the method On<Field>(payload T) error of the same type, without a directive.
  • At(time, payload) schedules it; a time already passed is due at once.
  • Key(key) names one timer of several of a kind, such as one per building. There is at most one pending timer per player, timer and key: At again moves it and replaces its payload.
  • Cancel() removes the pending timer; without one it does nothing.
  • Scheduling and cancelling happen only if the call succeeds.
  • The handler runs once, as a mutation of the same player, within about a second of its time. It may schedule its own timer again; that is how a timer repeats.
  • A handler that fails is tried again later, like the handler of an event. The player card shows its attempts and last error; a timer that keeps failing waits for a fix.
  • The payload is at most 16 KB.

A timer of the shared type runs for no player: it reads and writes shared data and reaches players only by EmitTo.

A moment shared by every player, such as the end of a season, is a window in a catalog that every call reads, not a timer per player.