Leaderboards
A leaderboard needs an OrderedDataStore, which a profile store is not. KeepBlox keeps one beside the profiles for each board you name, fills it from the profiles’ data as they save, and reads it back sorted.
const store = KeepBlox.store("Profiles", { template = { coins = 0, wins = 0 }, leaderboards = { coins = function(data) return data.coins end, wins = function(data) return data.wins end, }, leaderboardOptions = { interval = 60, cache = 60 },})
const top = store:leaderboard("coins", { count = 10 })for rank, entry in top do print(rank, entry.key, entry.value) -- entry.key is the profile key, such as "u_1"endDeclaring boards
Section titled “Declaring boards”leaderboards maps each board’s name to a function that reads its value from a profile’s data. The
function receives the data as it was stored, and returns a number, or nil.
Each board is the ordered data store "<store>__<board>", keyed by profile key. With the store above,
the boards are Profiles__coins and Profiles__wins.
Boards with a period
Section titled “Boards with a period”A board that starts again empty every week, or every day, is declared with a period:
leaderboards = { weekly = { read = function(data, week) return if data.week == week then data.weekCoins else nil end, -- 1970-01-05 00:00 UTC was a Monday: each period runs from Monday to Monday, UTC. period = { length = 604800, origin = 345600 }, },},- Each period is its own ordered data store,
"<store>__<board>_<n>", wherenisfloor((now - origin) / length)by the server’s wall clock (os.time). Servers’ clocks differ by seconds, so the last seconds of a period may land on either side. readis given the period it is read for. A game that keeps its own count for the period can return nil until that count has started again.- The first write in a new period is made whatever the last period held: the new store has nothing for the key yet.
store:leaderboardPeriod(name)gives the currentn(nil for a board without a period), andstore:leaderboard(name, { period = n })reads any period, such as last week’s winner.
Values
Section titled “Values”- A value is stored as an integer: KeepBlox floors it with
math.floor. - nil removes the key from the board. So does NaN, and any value that is not a number.
- A read function that throws is reported through
store.onError, and that board is skipped for that save.
When boards are written
Section titled “When boards are written”A board is a mirror, written after a save and not with it. The profile is the truth.
- After a save stores a profile, each board’s value is written if it changed since the last value written for that profile.
- A profile writes its boards at most once per
intervalseconds (default 60). - The release always writes, whatever the interval, so a player’s final values reach the board.
A board can therefore trail the profile by up to interval, and by the time between two saves on top
of that. Writes run in their own thread, so they never hold up a save.
Budgets
Section titled “Budgets”Roblox gives ordered data stores their own request budgets, smaller than a standard data store’s:
about 30 + 5 per player a minute for writes (OrderedWrite) and 5 + 2 per player for sorted reads
(OrderedList).
- Writes. Before each board write, KeepBlox checks the
OrderedWritebudget. When it is spent, the write is skipped, and the value is written by a later save once the budget returns. A failed write is reported throughstore.onErrorand tried again the same way. A write skipped or failed at the release has no later save to retry it: the board keeps its previous value for that key until the profile is next loaded and saved. - Reads.
store:leaderboardkeeps each answer forcacheseconds (default 60), per board, period, count and order. Calls within that time return a copy of the cached answer and cost nothing. With theOrderedListbudget spent, a read answers with the last answer to the same query, however old, and raises"the ordered list budget is spent"when it has none.
Reading a board
Section titled “Reading a board”store:leaderboard(name, query) returns a list of { key, value } entries.
| Query field | Meaning |
|---|---|
count |
How many entries from the top. Default 10; clamped to 1..100. |
ascending |
true for lowest first. Default: highest first. |
period |
Which period of a board with a period. Default: the current one. |
It raises an error when the store has no leaderboards, or no board of that name.
The entry above a value
Section titled “The entry above a value”store:leaderboardAbove(name, value, query) returns the entry nearest above value: the lowest value
higher than it, or nil when nothing is. It costs one GetSortedAsync of one entry, and its answer is
kept for cache seconds. With a page of the top read once, it tells a player outside that page who
is next to pass, and by how much:
const above = store:leaderboardAbove("coins", myCoins)if above then print(`{above.key} is {above.value - myCoins} ahead`)endOptions
Section titled “Options”leaderboardOptions is optional:
| Field | Default | Meaning |
|---|---|---|
interval |
60 | Seconds between one profile’s writes to its boards. The release ignores it. |
cache |
60 | Seconds a leaderboard answer is kept. |
