Leaderboards
Last updated
Last updated
Steam leaderboards are persistent, automatically sorted tables used to display scores globally or among friends. They can appear both in-game and on your title’s Steam community page. Each game can create up to 10,000 unique leaderboards, and scores are retrievable immediately after upload.
Leaderboards support an unlimited number of players. Each entry stores a required score (as an int
) and optionally up to 64 int
values of detail data. This detail data is a simple array used for session-specific context, such as character used, time taken, or other gameplay stats. It’s not parsed or sorted by Steam and is overwritten when a new score is submitted.
You can also associate leaderboard entries with Steam UGC (User-Generated Content), allowing you to link replays, loadouts, or screenshots to scores.
Leaderboards can be configured to accept score submissions only via trusted server-side API calls. This is highly recommended to prevent tampering. When using this setting, only a server with access to the Steam Web API and your publisher token can submit scores. If left untrusted, any client can submit any score, which opens the door to abuse.
Log in to your Steam Developer Portal and access your app's admin page. Look for the Technical Tools section and select the Edit Steamworks Settings option.
From there, select the Stats & Achievements > Leaderboards option and create your new boards.
Make a note of the value you use in the API Name field. You will use it when working with achievements in code.
You **MUST** publish your changes in the Steam Developer Portal before they will be accessible via Steam API. In the Steam Developer Portal when you have pending changes you will see a red banner at the top of the screen ... click it and follow the instructions.
A common issue when your start is that it may appear that the leaderboard is ignoring the score you upload, or that it only takes scores in the opposite direction you intended.
For example, if you upload 10, then upload 11, it may ignore the 11, but if you upload 9 it will take the 9.
Steam Leaderboards are configured to sort scores in a particular direction and when you upload a score you are typically doing so as "Keep Best".
The "Keep Best" option tells Steam to only record the new value you present ** if ** that value is better than the previous value recorded. This is determined by the "sort order" you configured for the board in the Steam Portal.
Assuming you have the board configured incorrectly, simply update its configuration in the Steam portal and then publish the changes.
You MUST ALWAYS publish changes when making edits in the Steam Portal. It does not apply the moment you make the change in the portal it is a Perforce-based source control system that requires you to publish your changes.
If for some reason you find your board still acts like it's sorted the other way around, this is likely due to an issue seen a few times with Steam's backend services. Submit a support case letting Valve know that your board appears to be bugged and is not changing its sort direction as it should.
To work around the issue make a new board (with a new name) and set it up with the sort of direction you desire; do not delete the broken board … please … so Valve can review it.
Rich public user profiles can be significant to social games
To be effective, profiles need to be accessible anytime a player’s name is visible. That includes offline friends, leaderboard entries, teammates, or opponents who beat you. The profile must be viewable by any user who sees it, without needing to be friends or share a lobby.
Steam’s rich presence can help in some cases. For example, you might see “Main Menu” under a friend’s name. That comes from rich presence, but it only works for yourself and your friends.
For everything else, the data is stored in a profile object. In DOTA’s case, it’s probably stored directly on the account, since DOTA has access to far more Steam features than most developers. That said, we can get close to the same result by storing profile data using leaderboards.
The goal is to create a publicly accessible player profile, similar to what you see in games like DOTA. These profiles let players show off in-game achievements, favourite builds, top stats, and more — all viewable by other users even outside of active lobbies or friendships.
Steam Leaderboards are used for this because they’re globally readable and can store more than just a score. They include a details
array (up to 64 integers) and support a UGC attachment per entry, which together allow for rich, flexible data storage.
Start by deciding what data you want players to display in their profiles, such as favourite character, highest level reached, clan affiliation, or other game-specific highlights.
This information should be stored in a structured format that can be serialized. Then, pack the relevant values into an int[]
using the leaderboard’s details
field. Since this is limited to 64 integers, efficient packing is key. For instance, booleans can be stored using bit flags, and enums or IDs are already integer-friendly.
While the details
array is great for compact, high-speed lookups; more descriptive or extended profile data (like full builds or character layouts) should go in a UGC attachment. This can be a file stored via Steam Remote Storage, serialized into a byte array.
Once set up, this profile data is uploaded to the leaderboard using a standard score submission. You can alternate the score or increment it to signal a new version. After uploading, the UGC file is attached to the leaderboard entry, allowing others to fetch it alongside the entry’s details.
Leaderboard Details (int[]
): Fast, lightweight, and instantly accessible. Ideal for stats, flags, and IDs.
Leaderboard Attachment (UGC): More flexible and suited to richer or nested data. Use it to store full profile objects as JSON, binary data, or other formats.
Steam retains attachments even if the original file is deleted from remote storage, making it a stable way to associate additional data with leaderboard entries.
To read a user’s profile, query the leaderboard entry using their Steam ID or another identifier. The returned data will include the score, details
, and the attachment if one exists. You can then deserialize the attachment back into a usable profile structure in your game.
This system enables persistent, shareable profiles that work outside of direct Steam relationships and are visible wherever player names are shown — in leaderboards, match histories, or UI elements.
First, you need to create your achievements on the Steam Developer portal.