Calls and events
Modules work together in two ways, and their promises differ:
| Call | Event | |
|---|---|---|
| Meaning | A command: do it and return the result. | A fact: this happened. |
| Who knows whom | The caller knows the target. | The listener knows the emitter. |
| When | Inside the call, for the same player. | Just after the call, on its own. |
| A failure of the other side | Fails 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.
Require a module
Section titled “Require a module”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"}rudder module require stores@^1.0rudder module require quests@^1.0rudder 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.
Call an exported function
Section titled “Call an exported function”import ( "season/requires/quests" "season/requires/stores"
"rudder.build/sdk/rudder")
//rudder:mutation serverfunc (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
exportcan be called from another module (Inventorygrantandtake, Questsreport). - 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.
Emit an event
Section titled “Emit an event”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 callkicked.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.
EmitTois 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.
Handle an event
Section titled “Handle an event”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.purchasedfunc (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.