Skip to content

Shared data

A clan, the lots of a market, the stock of an offer, a leaderboard: data that belongs to no player. It lives in the shared type of the module, next to the player type, and is reached only through functions of the player.

type Clans struct {
rudder.Project
Total rudder.Counter
Clans rudder.Records[Clan]
Gold rudder.SortedSet
}
type Clan struct {
Leader rudder.Value[string]
Members rudder.Set[string]
Treasury rudder.Counter
}
//rudder:mutation
func (player *Player) Join(arguments JoinArguments) (Card, error) {
clans := player.Clans()
clan := clans.Clans.Get(arguments.Clan)
if _, led := clan.Leader.Get(); !led {
if clans.Total.Get() >= settings.Get().Limit {
return Card{}, ErrLimit
}
clans.Total.Add(1)
clan.Leader.Put(player.ID())
}
clan.Members.Add(player.ID())
player.Clan.Put(arguments.Clan)
return card(arguments.Clan, clan), nil
}
  • The shared type embeds rudder.Project. Its fields are counters, values, sets, regens, records, timers and sorted sets.
  • The generator gives the player type a method named after the shared type, player.Clans(). The shared type has no functions and no way back to the player: pass player.ID() when it needs it.
  • Functions and event handlers are methods of the player type only. What a client may see or change of shared data is decided by a function of the player, so shared data is never open to a client by mistake.
  • Checks are exact. You read and write shared fields like the fields of the player, and a check and the write after it hold together. Two players who found the last clan at once: one founds it, the other gets limit. Two buyers of the last item of a stock: one gets it, the other gets sold_out.
  • All or nothing, across owners. A mutation that pays from the wallet of the player and adds to the treasury of a clan does both or neither.
  • You write no concurrency code and follow no rule about order. Read and write any shared fields in any order.
  • A query reads one consistent moment of shared data.
  • One shared record, or the plain shared fields of a module together, take a few hundred writes per second. Past that, calls answer 503 try_again, which the SDKs send again. Calls on different records do not slow each other.
  • A number that every player writes at once (the health of a world boss, a stock at the start of a sale to the whole game) belongs in a sorted set with a total, or in a fast counter.

A call never writes the data of another player. Change the shared data at once, and tell the other player with an event that your module handles itself:

//rudder:mutation
func (player *Player) Kick(arguments KickArguments) (Card, error) {
key, _ := player.Clan.Get()
clan := player.Clans().Clans.Get(key)
if leader, _ := clan.Leader.Get(); leader != player.ID() {
return Card{}, ErrNotLead
}
clan.Members.Remove(arguments.Player)
kicked.EmitTo(arguments.Player, Kicked{Clan: key})
return card(key, clan), nil
}
//rudder:on kicked
func (player *Player) OnKicked(event Kicked) error {
if current, _ := player.Clan.Get(); current == event.Clan {
player.Clan.Delete()
}
return nil
}

The shared data is the truth at once: the kicked player is out of Members. Its own Clan follows when the event is handled, shortly after.

An exchange between two players (a trade, a sale) goes through a shared record that holds the goods in between, one step per player. Goods and money are then always in exactly one place, with a player or in the record.

rudder.SortedSet keeps members (usually player ids) with integer scores, shared by all players: a leaderboard.

week := player.Clans().Gold.Period(rudder.Week)
week.Add(player.ID(), arguments.Gold)
place, found := week.Rank(player.ID())
top := week.Top(10)
MethodMeaning
Best(member, score)Keeps the better of the stored score and score.
Add(member, amount)Adds to the score; an absent member starts at 0.
Set(member, score)Replaces the score.
Remove(member)Takes the member out.
Score(member) (int64, bool)The score.
Rank(member) (int64, bool)The place, from 1.
Top(count) []rudder.EntryThe first count places (1 to 1000), each {Member, Score, Place}.
Count() intThe number of members.
Total() int64The sum of the scores, for a set tagged rudder:"total".

Choose the set on each call:

  • Key(key): one of many sets of the field, such as one board per row of a catalog. At most 128 bytes, no slash.
  • Period(rudder.Day), rudder.Week or rudder.Month: a set per period, empty at the start of each. Previous() reads the period before (read only); older periods cannot be read.
  • Order(rudder.Ascending): the lowest score first, such as the time of a race; Best then keeps the lower score.

The key, period and order together name the set, so a board whose rules change starts again and its old scores stay under the old rules.

What a sorted set promises:

  • It takes writes from every player at once.
  • A score is from 0 to 2^53; a member is 1 to 128 bytes.
  • Equal scores share a place (1, 1, 3), and Top lists them by member.
  • A call sees its own writes at once, and the writes of other calls a few milliseconds after they finished. A place is a reading of the moment, never a guard: decide nothing on it that a later write could not correct. A finished period no longer changes, so Previous() is stable.
  • A reward for a period is claimed: each player reads its own place in Previous() in its own call. No call walks the members to pay them.
  • Total() is exact for every finished call. Two calls that each see the total below a limit can together pass it; record the one winner of that moment in a shared value, whose check is exact.

A timer of the shared type runs for no player: an auction closes, a clan war ends. Its handler reads and writes shared data and reaches players only by EmitTo; the wallet, the data of a player and calls of other modules are not available in it.