Skip to content

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
}
  • 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 and Wallet() 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.

rudder.Counter: an int64 that never goes below zero.

MethodMeaning
Get() int64The value.
Add(n)Adds n.
Spend(n) errorTakes 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.

MethodMeaning
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.

MethodMeaning
Add(m) boolAdds a member; false when it was there.
Remove(m) boolRemoves a member; false when it was absent.
Has(m) boolWhether the member is there.
All() []TThe members, sorted.
Count() intHow many.

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
MethodMeaning
Get() rudder.RegenStateThe value now, and when the next point and the full value come, so the client ticks by itself.
Spend(n) errorTakes 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.

player.Wallet() holds the balances of the currencies of the project.

MethodMeaning
Balance(asset) int64The balance.
Credit(asset, n)Adds n.
Debit(asset, n) errorTakes n, or returns rudder.ErrInsufficient.
Pay(price rudder.Amount) errorDebits 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.

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.

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.

rudder.Timer[T] calls a handler of the module at a given time. See Timers.

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).