Functions
A function is a method of the player type with a directive on the line above:
//rudder:queryfunc (player Player) State() (State, error) { ... }
//rudder:mutationfunc (player *Player) Claim(arguments ClaimArguments) (State, error) { ... }
//rudder:mutation serverfunc (player *Player) Report(arguments Progress) (Reported, error) { ... }Directives
Section titled “Directives”| Directive | Meaning |
|---|---|
//rudder:query | Reads only. A write fails the call. No idempotency key. |
//rudder:mutation | May change data. Needs an Idempotency-Key; runs at most once per key. |
server | Only the game server and operators call it. To a client it does not exist. |
export | Modules that require this one may call it (see Calls and events). |
name=<name> | The name callers use, instead of the method name in lowerCamel. |
Options follow the kind: //rudder:mutation server export, //rudder:query name=offers.
Mark server anything the client must not decide by itself: match results, progress the
server checks, grants after a validated receipt.
The name of a function is its method name in lowerCamel, with a leading initialism lowered:
Claim is claim, XPBoost is xpBoost.
Signature
Section titled “Signature”A function takes at most one parameter, its arguments, and returns (T, error) or error.
The parameter and T are contract types: a basic type (string, boolean, integer, float), a type
of types, rudder.Amount, rudder.Window, time.Time, or a pointer to, a slice of or a map
with string keys of those.
Arguments are checked against their schema before the function runs: a missing required field
or an unknown one answers 400 invalid_arguments.
An exported method of the player type without a directive fails generation; unexport helpers.
Errors
Section titled “Errors”Declare the errors of a module as package variables:
var ( ErrNotReached = rudder.Error("not_reached", "the tier is not reached yet") ErrClaimed = rudder.Error("claimed", "the tier is already claimed"))A function that returns one answers 422 with its code and message, and nothing it wrote is
kept: not its fields, not the wallet, not its events or timers. Codes are unique in a module;
invalid_arguments and insufficient are taken. ErrNotReached.With("tier 3") adds a detail to
the message and keeps the code; errors.Is matches by code.
Any other failure of the module (a panic, an operation outside the rules, a value over its
size) answers 500 internal; running over the time of a call answers 500 module_timeout.
Nothing is kept either way.
Time, randomness and the call
Section titled “Time, randomness and the call”| Function | Meaning |
|---|---|
rudder.Now() | The time of the call, fixed for the whole call. |
rudder.Random() | A *rand.Rand seeded for the call. |
rudder.Environment() | staging or prod. |
rudder.PeriodStart(rudder.Day) | The start of the current day, week or month of the project. |
rudder.Profiles(ids) | The nickname and avatar of up to 1000 players, to show them. |
rudder.Log.Info(message) | A log line, shown with the call in Activity and rudder logs; also Debug, Warn, Error. |
Use only these for time and randomness: a module has no system clock, network, files or goroutines. A call starts the module fresh, so package-level variables start from their initial values at every call.
Limits of a call
Section titled “Limits of a call”| Limit | Value |
|---|---|
| Time of the module in a call | 200 ms, shared with the modules it calls |
| Operations on fields, catalogs and the wallet | 1000 per call |
| Memory | 64 MB |
| Arguments | 1 MB |
| Result | 256 KB |
| Logs | 64 KB per call |