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:mutationfunc (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: passplayer.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.
What Rudder promises
Section titled “What Rudder promises”- 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 getssold_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.
Limits
Section titled “Limits”- 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.
Another player
Section titled “Another player”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:mutationfunc (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 kickedfunc (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.
Sorted sets
Section titled “Sorted sets”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)| Method | Meaning |
|---|---|
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.Entry | The first count places (1 to 1000), each {Member, Score, Place}. |
Count() int | The number of members. |
Total() int64 | The 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.Weekorrudder.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;Bestthen 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
Toplists 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.
Shared timers
Section titled “Shared timers”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.