Data
The data of a module is the fields of its owner types. You read and write them like Go values; Rudder keeps them, and a call keeps all its writes or none.
type Player struct { rudder.Player Clan rudder.Value[string] Donated rudder.Counter `rudder:"period=week"` Energy rudder.Regen Levels rudder.Records[Level] Built rudder.Timer[Upgrade]}
type Level struct { Reached rudder.Counter}Owners
Section titled “Owners”- The player type embeds
rudder.Player. Every module has exactly one. Its fields are the data of each player; a call works with the fields of the player it runs for.ID()is the player id andWallet()its balances. - The shared type embeds
rudder.Project. A module has at most one. Its fields are shared by all players of the environment: clans, the lots of a market, a leaderboard. See Shared data.
A field is named by its Go name in lowerCamel (Donated is donated). A tag
rudder:"<name>" keeps the name of a field you rename in Go. The name is what the Dashboard and
the history show.
Counter
Section titled “Counter”rudder.Counter: an int64 that never goes below zero.
| Method | Meaning |
|---|---|
Get() int64 | The value. |
Add(n) | Adds n. |
Spend(n) error | Takes n, or returns rudder.ErrInsufficient and changes nothing when the value is below n. |
Set(v) | Sets the value. |
n and v must not be negative. A counter with a period, rudder:"period=day", week or
month, belongs to the current period: when a new period starts it reads 0, without anything
running at midnight. Days start at the day start of the project, weeks on Monday, months on
their first day.
rudder.Value[T]: one document of a contract type, at most 16 KB.
| Method | Meaning |
|---|---|
Get() (T, bool) | The value, and whether there is one. |
Put(v) | Replaces it. |
Delete() | Removes it. |
rudder.Set[T]: a set of strings or integers, at most 16 KB in all.
| Method | Meaning |
|---|---|
Add(m) bool | Adds a member; false when it was there. |
Remove(m) bool | Removes a member; false when it was absent. |
Has(m) bool | Whether the member is there. |
All() []T | The members, sorted. |
Count() int | How many. |
Records
Section titled “Records”rudder.Records[R]: many records of the same shape under string keys, such as the progress of
each season or the level of each building. R is a struct of counters, values, sets and regens;
records do not nest.
level := player.Levels.Get("farm")level.Reached.Add(1)Get(key) returns the record of a key, empty when nobody wrote it. A key is 1 to 128 bytes.
rudder.Regen: a quantity that comes back with time up to a cap, such as energy or lives. The
rule is data you pass at every use, usually from a catalog, so a designer changes the rate and
the cap without a new build:
meter := player.Energy.With(settings.Get().Energy) // rudder.RegenRule{Every: 300, Max: 5}if err := meter.Spend(1); err != nil { return err // rudder.ErrInsufficient}state := meter.Get() // Value, Max, Every, NextAt, FullAt, At| Method | Meaning |
|---|---|
Get() rudder.RegenState | The value now, and when the next point and the full value come, so the client ticks by itself. |
Spend(n) error | Takes n, or returns rudder.ErrInsufficient. |
Add(n) | Adds n, even above the cap. |
Fill() | Raises the value to the cap. |
A player who never used it is full. One point comes every Every seconds up to Max; a value
at or above the cap does not grow. A partial interval is kept: a spend 2 minutes into a
5-minute interval leaves 3 minutes to the next point. A lowered cap takes nothing away. A
changed rule counts the whole time since the last write.
The wallet
Section titled “The wallet”player.Wallet() holds the balances of the currencies of the project.
| Method | Meaning |
|---|---|
Balance(asset) int64 | The balance. |
Credit(asset, n) | Adds n. |
Debit(asset, n) error | Takes n, or returns rudder.ErrInsufficient. |
Pay(price rudder.Amount) error | Debits an amount. |
Grant(rewards ...rudder.Amount) | Credits each amount. |
Every credit and debit is in the history of the player, with the module and function that
made it. A currency the project does not have fails the call. Generation fails when the error
of Debit, Pay or Spend is ignored: money fails closed. Write _ = ... to ignore it on
purpose.
rudder.ErrInsufficient returned from a function answers 422 with the code insufficient.
Sorted set
Section titled “Sorted set”rudder.SortedSet: members with scores, shared by all players, such as a leaderboard. It is a
field of the shared type only. See Shared data.
Fast fields
Section titled “Fast fields”A rudder.Counter or rudder.Set tagged rudder:"fast" takes very frequent writes for
numbers whose last second may be lost: who is online, the hits on a world boss.
- The last second of writes of a fast field may be lost. Never use one for currency or for
anything that must not be lost; a fast counter has no
Spend. - A fast field has no period.
- A fast set holds at most 100 000 members of at most 128 bytes.
Timers
Section titled “Timers”rudder.Timer[T] calls a handler of the module at a given time. See
Timers.
Changing the data of a published module
Section titled “Changing the data of a published module”New fields are always fine. Removing a field, or changing its type, its period, its owner,
fast or the type of a value incompatibly is a breaking change: Rudder refuses it inside a
version line, and accepts it only in the first version of the next one, published with
--release --allow-breaking (see Compatibility).