Skip to content

Calls and events

Modules work together in two ways, and their promises differ:

CallEvent
MeaningA command: do it and return the result.A fact: this happened.
Who knows whomThe caller knows the target.The listener knows the emitter.
WhenInside the call, for the same player.Just after the call, on its own.
A failure of the other sideFails the caller, or the caller decides.Never reaches the emitter. The listener is tried again.

The rule: when a failure of the other module must undo your function, call it. Otherwise listen to its event.

List it in requires of your manifest with a caret range, and copy its contract into your module:

"requires": {"stores": "^1.0", "quests": "^1.0"}
Terminal window
rudder module require stores@^1.0
rudder module require quests@^1.0

rudder module require <module>@<range> takes the newest published version of the module, of the marketplace or of your project, that fits the range, writes its contract into requires/<module>.json and puts the range into requires. rudder module require <directory of the module> [your directory] copies the contract from a source directory instead. Commit requires/<module>.json: a change of the other module’s contract shows in your diff. Generation then writes the package requires/<module> with its types, its errors as Err<Code> and a function for each function it exports.

^0.3 accepts 0.3.x and its prereleases (0.3.0-dev.1), never 0.4; ^1.2 accepts 1.x from 1.2. A version never breaks the contract of its line (see Version lines), so a range keeps working while the module grows. A release whose modules miss a required module, have one outside its range, or require each other in a circle is refused.

import (
"season/requires/quests"
"season/requires/stores"
"rudder.build/sdk/rudder"
)
//rudder:mutation server
func (player *Player) Finish(arguments FinishArguments) (Summary, error) {
if arguments.Won {
if _, err := quests.Report(quests.Progress{Metric: "win", Amount: 1}); err != nil {
return Summary{}, err
}
}
player.Xp.Add(arguments.Xp)
return Summary{Xp: player.Xp.Get()}, nil
}
  • Only functions marked export can be called from another module (Inventory grant and take, Quests report).
  • The target runs for the same player, inside your call, with the same time. A query calls queries only; a mutation calls both.
  • When the target returns an error, it changed nothing, and you get the error with its code (errors.Is(err, quests.ErrUnknownMetric)). Return it, and your whole call changes nothing; or go on, and your own writes stay.
  • A panic or a timeout of the target fails your whole call.
  • The time and operation limits of a call are shared by your module and every module it calls.

Declare it in the manifest with an object type, and emit it from a mutation:

"events": {"kicked": "Kicked"}
kicked.Emit(Kicked{Clan: key}) // to the player of the call
kicked.EmitTo(memberID, Kicked{Clan: key}) // to another player of the environment
  • An event of a call that failed is never sent; an event of a call that succeeded is never lost.
  • The payload is checked against its type and is at most 16 KB.
  • EmitTo is the only way a call reaches another player: a call never writes the data of another player. The other player sees the change when its handler has run, shortly after.
  • An event to a player that does not exist is dropped.

A handler is a method of the player type with //rudder:on <module>.<event>, or //rudder:on <event> for an event of your own module:

//rudder:on stores.purchased
func (player *Player) OnPurchased(event stores.Purchased) error {
player.Xp.Add(10)
return nil
}
  • The module must be in requires; your own events need nothing.
  • A handler runs for the player the event was sent to, as a mutation of its own, just after the call that emitted it. It may write, call the modules it requires and emit events.
  • A handler runs once for each event it handles. Its failure never reaches the emitter: it is tried again later, 1 second after the first failure, doubling up to 5 minutes, and after 10 failed attempts no more.
  • The events of a player are handled in the order they were sent, while nothing fails; a failed one does not hold back those after it.
  • A handler ignores payload fields it does not know, so a newer emitter does not break it.
  • No client, game server or module can call a handler.