Progression
Leaderboards
Find a leaderboard, upload a score, download entries.
Leaderboards are three latent nodes plus a handful of readers.
Finding one
Find Leaderboard (Async) takes the leaderboard name from the partner site and returns a handle. Everything else takes that handle.
Leaderboards can also be created on demand rather than on the partner site, which is useful for per level boards you do not want to define by hand.
Once you have a handle:
| Node | What it does |
|---|---|
| Get Leaderboard Name | Its name |
| Get Leaderboard Entry Count | How many entries it has |
| Get Leaderboard Sort Method | Ascending or descending |
| Get Leaderboard Display Type | Numeric, seconds, or milliseconds |
| Format Leaderboard Score | Turn a raw score into display text using the display type |
Format Leaderboard Score is worth using. A time leaderboard stores milliseconds, and showing 93500 instead of 1:33.5 is the usual mistake.
Uploading a score
Upload Leaderboard Score (Async) takes the handle, a score, and a method:
| Method | Behaviour |
|---|---|
| Keep Best | Only replaces the player's score if the new one is better |
| Force Update | Always replaces |
Keep Best is what you want for a high score board. Force Update is for a board showing a current value rather than a best, like a season rank.
The result tells you the new rank, the previous rank, and whether the score actually changed. That is what you need for a "you moved up 4 places" message.
You can also attach up to 64 integers of detail per entry, for a ghost, a loadout or a replay reference.
Downloading entries
Download Leaderboard Entries (Async) takes the handle, a request type, and a range:
| Request type | What you get |
|---|---|
| Global | Top of the board, by absolute rank |
| Global Around User | Entries either side of the local player |
| Friends | Only the player's Steam friends |
Global Around User takes a negative start and a positive end, so -4 to 5 gives you the player plus four above and five below.
Each entry carries the player's Steam ID, rank, score, and any detail integers. Pair it with Get Friend Info or an avatar lookup to build a full row. See Friends and presence.