How to design a game leaderboard
The first sections are free. The deep dives, level expectations and quiz are part of Pro.
On this page
- The problem
- Clarifying questions
- The requirements menu
- Non-functional requirements
- Estimates
- Core entities
- The API
- The high-level design
- What breaks first
- The deep dives
- Entity fields
- Ranking with a sorted set
- Sharding at a hundred times the players
- Variants
- What each level is expected to show
- The 30-second answer
- Quiz
The problem
A game leaderboard adds a point when a player wins a match, shows the top 10 of the monthly tournament, and tells any of 25 million players where they stand right after a win. Writes are light at 2,500 a second at peak. The answer turns on the rank question: in a table, a player's rank means counting the players above them, and that count grows with the board, while a store that keeps players in score order answers it in a handful of steps. A Redis sorted set is that store, and at this size the whole month's board fits in one node, so most of the design is about keeping that node safe, keeping a record it can be rebuilt from, and knowing when a hundredfold rise forces a split.
Clarifying questions
| Ask | Why it matters | A typical answer |
|---|---|---|
How many players are on the board, and how often do scores change? | The entry count decides whether the board fits in one machine's memory, and the write rate decides whether one node can take the updates. Both numbers shape the store before any box is drawn. | About 5 million daily and 25 million monthly players, around 10 matches each a day, with score updates averaging 500 a second and peaking near 2,500. |
Does a player's rank need to be exact and current, or is a number a few minutes old acceptable? | A periodic job that ranks everyone is the simple answer if staleness is fine. If a player expects to see their new rank right after a win, the store itself has to answer rank questions cheaply. | Exact and near real time: a player who just won should see the new rank when they open the board, not after a nightly batch. |
Who reports a win: the game client or the game server? | If a client can post its own score, anyone who edits the request can put themselves at the top. The answer decides who is allowed to call the write endpoint. | The game servers. They decide who won a match and are the sole callers of the score write; clients read. |
Is the board monthly, all-time, or both? | A monthly board resets, so each month gets its own structure and the old one becomes history. An all-time board grows without bound and changes the sizing. | A monthly tournament. A fresh board starts each month; past months can be kept for viewing. |
How should two players with the same score be ordered? | Ties are common when a point is one win. The rule has to live somewhere, either in how the score is stored or in how the rank is read, and it affects what the player sees. | Your call, but pick a rule and say where it lives: shared rank for equal scores, or the earlier winner ahead. |
Do we show the players right around someone, not just the top 10 and their own rank? | The nearby players view is one more range read on a sorted store, but a different query shape on a table, so it is worth knowing before choosing the store. | A bonus: the four players above and below a player, if time allows. |
Do we need boards per friend group or per region? | Each extra board multiplies the writes and the memory, or forces a filtered read over a shared board. | No, one global monthly board. Friend and regional boards are out of scope. |
Non-functional requirements
| Requirement | What it forces |
|---|---|
Ranks update in near real time, not in a nightly batch | The rank has to be read from live data, so the store must answer a rank question cheaply as scores change. A table where a rank is a count over the rows above does not meet this at 25 million players; a structure that keeps players in score order does. |
2,500 score updates a second at peak | Each win is one small increment, so the write path stays a single command on the leaderboard store plus one row in the record of wins. The rate is modest for an in-memory store, but it rules out recomputing anything expensive on each write. |
25 million players a month on the board | The sizing question: at 26 bytes an entry the month's board is about 650 MB, which fits one node even with overhead for the ordering structure. The design keeps one node for the board and spends its effort on a replica and a rebuild path rather than on sharding. |
Only game servers can change a score | The write endpoint is reachable from the game service, authenticated server to server, and clients get read endpoints. A client that could post a score would let anyone edit the request and take the top spot. |
Estimates
| Quantity | Working | Result | What it sizes |
|---|---|---|---|
Average and peak score updates a second | 5,000,000 daily players ÷ 86,400 seconds ≈ 58 players a second, rounded down to 50; 50 × 10 matches = 500 updates a second on average; peak taken as five times the average = 2,500 | About 500 a second on average, 2,500 at peak | The write load on the leaderboard store: a few thousand small increments a second, which is what the single-node choice has to carry. |
Memory for one month's sorted set | 25,000,000 entries × 26 bytes, the estimate used here: a 24-byte player id plus a score budgeted as a 16-bit value (Redis itself stores a score as a double-precision float, so treat this as a floor) = 650,000,000 bytes ≈ 650 MB; doubled as a rough allowance for the skip list and hash table around the entries ≈ 1.3 GB, a planning figure rather than measured Redis memory | About 650 MB of raw entries by this estimate; doubling for overhead gives about 1.3 GB as a planning figure, not a measurement | Whether the whole board fits in one node's memory. It does, with room to spare. |
Work per rank request, table against sorted set | A SQL count of rows above a player in the middle scans about half of 25,000,000 index entries = 12,500,000; a sorted set rank lookup is documented as O(log N), and as a yardstick for that growth rate the base-two log of 25,000,000 ≈ 24.6, about 25, not a measured step count | About 12.5 million entries scanned, against a walk that grows with the logarithm of the count: the base-two log of 25 million is about 25, a yardstick rather than a measured step count | Why the rank question decides the store: the table's cost grows with the board, the sorted set's barely moves. |
Board size and write rate at a hundred times the players | 25,000,000 monthly players × 100 = 2,500,000,000 entries × 26 bytes ≈ 65 GB; 2,500 peak updates × 100 = 250,000 a second | About 65 GB of board, 250,000 updates a second | The point where one node stops being the answer and the board has to be split. |
Load per shard if the big board is cut into a hundred pieces | 65 GB ÷ 100 ≈ 650 MB a shard; 250,000 ÷ 100 = 2,500 increments a second a shard, if players spread evenly | Each shard looks like today's single node | How many shards the hundredfold board needs: about a hundred of the node we already run, before accounting for uneven score ranges. |
Match results logged a day | 5,000,000 daily players × 10 matches = 50,000,000 player-matches a day; with two players a match that is 25,000,000 matches and 25,000,000 wins | About 25 million win rows a day | The record of wins in MySQL that the board can be rebuilt from, and the length of a full rebuild. |
Profile lookups for the top 10 | 50 leaderboard fetches a second × 10 entries = 500 profile reads a second if each fetch went to the players table | About 500 profile reads a second, for the same 10 or so players | The small cache of top players' names and avatars in front of the players table. |
Core entities
| Entity | What it holds |
|---|---|
Player | Who appears on the board: an id the game knows and a name to show beside a score. |
Monthly score | A player's points in one month's tournament, held in the sorted set and mirrored by the record of wins. |
Match win | One row per win, the source of truth the in-memory board can be rebuilt from. |
Shard assignment | Which piece of a split board holds a player; needed at a hundred times the scale, not before. |
The API
| Endpoint | Notes |
|---|---|
| Called by the game service once per win and not by a client; authenticate it service to service and reject it at the gateway from anywhere else. The service increments the player's entry in this month's sorted set and appends a row to the wins table. Carry a match id so a retried call does not count a win twice. |
| One range read of the highest entries of the month's sorted set, then names from a small cache of the top players' profiles. Rank is the position plus one, since the store counts from zero. |
| Two reads on the sorted set: the player's score and their position from the top. A player with no entry this month is shown as unranked rather than as an error. The nearby players bonus is a range read around that position. |
The high-level design
Step 1 of 4
Game service reports wins, scores in MySQL
Start with the trust boundary and one database. The game client sends match results to the game service, which decides who won. The game service, not the client, calls POST /v1/scores on a leaderboard service, so a player who edits their own requests has nowhere to send a fake score. The leaderboard service writes to MySQL: a players table, a wins table with one row per win, and the monthly points. The top 10 is an ordered read with a limit; a rank is a count of the rows with more points. It is complete, and it is what we will fix next.
What breaks first
The deep dives
Ranking with a sorted set. A player in the middle of 25 million asks for their rank seconds after a win while other scores keep changing. How does the store answer without counting everyone above them, and does the whole month's board fit on one machine?
Sharding at a hundred times the players. Daily players jump to 500 million and score updates to 250,000 a second, so the month's board is about 65 GB. How is it split across nodes so the top 10 and a single player's rank stay cheap, and what happens when one piece loses its memory?