Leaderboards

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.

Use the Steam Web API to set trusted leaderboard scores

https://partner.steamgames.com/doc/webapi/ISteamLeaderboards#SetLeaderboardScore

Quick Start

First, you need to create your achievements on the Steam Developer portal. https://partner.steamgames.com/

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.

Publish

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.

Troubleshooting

Upload ignores my value

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.

Why?

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".

board.UploadScore(42,
    ELeaderboardUploadScoreMethod.k_ELeaderboardUploadScoreMethodKeepBest,
    (result, error) =>
    {
        if(!error)
            Debug.Log("Recorded: " + result.m_nScore +
                      "New Rank: " + result.m_nGlobalRankNew);
    });

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.

How to Fix?

Assuming you have the board configured incorrectly, simply update its configuration in the Steam portal and then publish the 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.


Advanced Profiles

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.

What Is This?

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.

How Does It Work?

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.

Why Use Both?

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.

Reading the Profile

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.


Examples

Get Leaderboard

Code Free

Declare your leaderboard in your Settings, and we will "get" the board for you on initialisation

C#

//Leaderboard Object will be "got" for you by the initialization process
//For Leaderboard Data, we need it as it is a struct and not a reference, we need
//To get its ID before we can use it

//Before we can use a leaderboard, we need to get its ID ... not its API Name ... its ID
//The static function takes in the api name and a delegate to be called when the process is completed
//This is an asynchronous method ... a delegate is simply a pointer to a function
//You could give it a named function you defined in your class, but far more commonly, you use an anonymous function as we have here
LeaderboardData.Get(apiName, (data, ioError) =>
{
    if (!ioError)
    {
        targetBoard = data;
        Debug.Log($"Found {apiName} with ID {targetBoard.id.m_SteamLeaderboard}");

        //At this point, you now have the board and do things with it .... see the functions below that give examples of working with the board such as reading and writing data
    }
    else
    {
        Debug.LogError($"An IO error occurred while attempting to read {apiName}");
    }
});

Upload Score

Code Free

Not Applicable

C#

// Call Upload Score passing in any details and indicating an upload Method
// This is an asynchronous function, so the last parameter is a delegate
// That will be run when the process completes
targetBoard.UploadScore(score, details, uploadMethod, (callbackResult, ioError) =>
{
    // Handle the result if ioError is false
});

Get User's Entry

Code Free

Not Applicable

C#

targetBoard.GetUserEntry(detailEntriesCount, (foundEntry, ioError) =>
{
    // Handle the found entry if ioError is false
});

Get Entries

Code Free

Not Applicable

C#

//You have several quality-of-life shortcuts to reading records in different ways
//In all cases, the final parameter is a delegate that will be called when the
//process completes and will contain the results found if any.

//Top X number of records
int howMany = 42;
int detailsCount = 0;
targetBoard.GetTopEntries(howMany, 
    detailsCount, 
    (entriesFound, ioError) =>
    {
        //Handle the entries found if ioError is false
    });

//Get entries for specific users
UserData[] users; //set this to who you want to read for
int detailsCount = 0;
targetBoard.GetEntries(users, 
    detailsCount, 
    (entriesFound, ioError) =>
    {
        //Handle the entries found if ioError is false
    });

//Get entries around the user's entry (includes the user's entry)
int beforeUser = -5;
int afterUser = 5;
int detailsCount = 0;
targetBoard.GetEntries(ELeaderboardDataRequest.k_ELeaderboardDataRequestGlobalAroundUser, 
    beforeUser, 
    afterUser, 
    detailsCount, 
    (entriesFound, ioError) =>
    {
        //Handle the entries found if ioError is false
    });
    
//Get all your friends' entries
int detailsCount = 0;
targetBoard.GetEntries(ELeaderboardDataRequest.k_ELeaderboardDataRequestFriends, 
    0, 
    0, 
    detailsCount, 
    (entriesFound, ioError) =>
    {
        //Handle the entries found if ioError is false
    });
    
//Get all entries ... really not recommended but it exists
int detailsCount = 0;
targetBoard.GetAllEntries(detailsCount, 
    (entriesFound, ioError =>
    {
        //Handle the entries found if ioError is false
    });

Attach File

Code Free

Not Applicable

C#

//Note the file will need a name but this is just the name of the file for the temporary upload
//So this is the name that will be in the user's Remote Storage, once attached we can remove it to save space.
//we like to us the same name all the time "tempFile" and we do not bother removing it instead we just let it 
//overwrite each time as a means to hold the space for future attachments
targetBoard.AttachUGC("tempFile", fileData, (ugcResult, ugcIoError) =>
{
    if (!ugcIoError)
    {
        if (ugcResult.Result == Steamworks.EResult.k_EResultOK)
            Debug.Log($"Attached file data to user entry on board {apiName}");
        else
            Debug.LogError($"Failed to attach file data to user entry on board {apiName}, Response Result = {ugcResult.Result}");
    }
    else
    {
        Debug.LogError($"Failed to attach file data to user entry on board {apiName}, IO Error!");
    }
});

Get Attached File

Code Free

Not Applicable

C#

This assumes you already have a LeaderboardEntry you want to read the attachment for. and it assumes the data you are reading is serialized from a serializable object named "SomeObject"

// Assuming
LeaderboardEntry entry;

entry.GetAttachedUgc<ExampleSerializableDataForAttachment>((dataFound, ioError) =>
{
    if(!ioError)
    {
        //Data Found is your attachment, if any. It is up to you to check and see if that is a default value or actually set data
        //how you do that depends on what kind of object it is ... for a struct you should always implement the IEquitable, IComparable and overloads for == and != operators
    }
});

Last updated