Skip to content

Leaderboards Examples

This section provides practical examples of using Steam Leaderboards to submit player scores, retrieve leaderboard data, and display rankings inside Unreal Engine projects.

All examples below are shown using Blueprint nodes, with equivalent functionality available through the C++ API.

Prerequisites

Before using any Leaderboards-related nodes, the following conditions must be met:

  • Leaderboards must be created and published in Steamworks
  • LeaderboardName values must exactly match the names defined in Steamworks
  • The leaderboard sort method and display type must be configured correctly in Steamworks

Leaderboard creation and configuration is managed entirely through Steamworks and must be completed before any leaderboard-related functionality can be used at runtime.

Finding a Leaderboard

This example demonstrates how to find an existing Steam leaderboard by name.

The primary purpose of this step is to obtain a valid FSteamLeaderboardID, which is required for all subsequent leaderboard operations, including uploading scores and downloading leaderboard entries.

The Find Leaderboard node performs an asynchronous lookup using the leaderboard name defined in Steamworks and returns a leaderboard ID through the On Success callback.

Once resolved, the leaderboard ID should be cached and reused. All other leaderboard-related nodes operate exclusively on this ID and do not accept leaderboard names directly.

In most projects, this lookup is performed once per leaderboard and the cached ID is reused throughout the session.

Uploading a Score

This example shows how to upload a score for the current user to a leaderboard and react to the upload result.

The Upload Score to Leaderboard node submits a score to the leaderboard identified by a previously cached FSteamLeaderboardID, which was obtained earlier using the Find Leaderboard node.

In this example, a numeric score value is uploaded using the Keep Best upload method. This means Steam will update the leaderboard entry only if the new score is better than the one already stored for the user. This is the most common mode for score-based leaderboards.

The upload operation is asynchronous. When the upload completes successfully, the result is returned through the On Success callback as a FSteamUploadScoreResult structure.

In this flow, the result is broken to extract information such as whether the score was actually updated and what the new global rank is. This allows the game to immediately update UI elements, for example by displaying the player’s new rank after a match or run.

The optional Details parameter allows attaching additional integer data to the leaderboard entry. This data is stored alongside the score and can be used to represent game-specific information such as split times, lap counts, difficulty level, or other contextual values. If no extra data is required, this parameter can be left empty.

Uploading scores is typically performed at the end of a match, level, or gameplay run, once the final result has been calculated.

Downloading Leaderboard Scores

In this example, leaderboard entries are downloaded and processed for display in a UI.

The Download Leaderboard Scores node is called using a previously cached FSteamLeaderboardID. In this flow, scores are requested from the Global leaderboard within a specific rank range, starting at rank 1 and ending at rank 10. This is a common setup for displaying a top-N leaderboard.

The operation is asynchronous. When the download completes successfully, the result is returned as a FSteamDownloadScoresResult structure.

In this example, the result is broken to access the array of leaderboard entries. A single entry is then retrieved from the array and broken further to extract individual fields such as the user’s Steam ID, score value, global rank, and optional details data.

This pattern is typically used to populate leaderboard tables, ranking widgets, or to extract and display specific entries from a downloaded range.

Getting the Current User Rank

This example demonstrates how to retrieve the leaderboard entry for the current Steam user without downloading the full leaderboard.

The Get Current User Leaderboard Entry node returns the user’s rank, score, and associated metadata.

This approach is commonly used to display the player’s personal ranking in HUDs, menus, or post-game screens.

Getting a Leaderboard Entry for a Specific User

In this example, a leaderboard entry is retrieved for a specific Steam user.

This node can be used to compare scores with friends or display ranking information on user profile screens.

Only a single entry is retrieved, making this approach more efficient than downloading a full leaderboard when targeted data is required.

Important Notes

  • Leaderboards must exist and be published in Steamworks before they can be found at runtime
  • Leaderboard names are case-sensitive and must exactly match Steamworks configuration
  • Uploading scores too frequently may result in rejected updates
  • Sorting behavior and score display format are fully defined by the Steamworks leaderboard configuration