Skip to content

Leaderboards Examples

This section demonstrates practical examples of using Google Play Games Services Leaderboards in Unreal Engine projects. All examples assume that the player is already signed in to Google Play Games Services and that all leaderboards have been created and configured in the Google Play Console in advance.

Leaderboards are used to submit player scores, display rankings, and retrieve score data for comparison with other players or friends.

Basic Usage Flow

A typical leaderboards flow in a game looks like this:

  • The player signs in to Google Play Games Services.
  • Scores are submitted when relevant gameplay events occur.
  • Leaderboard data is loaded when displaying rankings or statistics.
  • The native leaderboard UI can be opened from a menu or button when needed.

Leaderboard Score Formatting

When submitting a score, the meaning of the Score value depends entirely on the score format configured for the leaderboard in the Google Play Console.

All scores are submitted as a 64-bit integer (int64). Google Play Games Services formats and interprets this value based on the leaderboard type.

Fixed-Point (Number)

The score is treated as a raw number and formatted using the configured decimal places.

Example:

  • Decimal places = 2
  • Submitted 1000 → Displayed as 10.00

Use this format for points or counters.
If your gameplay uses floats, scale them to an integer before submitting.

Time (Duration)

The score represents elapsed time in milliseconds.

Example:

  • 1 minute 23.456 seconds → submit 83456

Always convert time to milliseconds before submitting.

Currency

The score represents a value in micro-units.

Example (USD):

  • $1.00 → submit 1000000
  • $0.25 → submit 250000

Always multiply the currency value by 1,000,000.

Important Notes

  • Google Play does not validate score formatting.
  • Submitting incorrectly formatted values will result in incorrect display.
  • Always check the leaderboard configuration before submitting scores.

For full details, refer to the official Google documentation.

Submitting a Score

The most common leaderboard operation is submitting a score after a gameplay session.

Example scenario: submit the player’s score after finishing a level.

  • Call Submit Score with the corresponding LeaderboardID and score value.
  • The LeaderboardID must exactly match the identifier of the leaderboard created in the Google Play Console.

This is a fire-and-forget operation. It does not return a result and is suitable when you do not need immediate confirmation.

Calling this function multiple times with increasing scores is safe. Google Play Games Services automatically keeps the best score according to the leaderboard’s score order.

Submitting a Score with Immediate Result

If you need to know whether the submitted score is a new personal best, use the immediate submission variant.

Example scenario: show a “New High Score” message after score submission.

Typical usage pattern:

  • Call Submit Score Immediate with the LeaderboardID and score.
  • Use On Success to receive a FGooglePlayLeaderboardScoreSubmissionData object.
  • Check the returned data to determine whether the score is a new best.

This approach is useful for feedback, UI updates, or triggering achievements based on leaderboard performance.

Showing the Leaderboards UI

Most games provide a menu option to display leaderboards using the native Google Play Games UI.

Showing All Leaderboards

Example scenario: open a global leaderboard screen from the main menu.

  • Call Show All Leaderboards UI when the button is pressed.
  • Use On Opened and On Closed callbacks to pause or resume gameplay if required.
  • Handle On Failure to gracefully report UI errors.

Showing a Specific Leaderboard

If your game has multiple leaderboards, you can open a specific one directly.

Example scenario: show a leaderboard related to the currently selected game mode.

  • Call Show Leaderboard UI with the target LeaderboardID.
  • Specify the desired time span and collection (for example, all-time public scores).

Using callbacks is optional but recommended if you need to control gameplay state while the UI is visible.

The native leaderboard UI is fully managed by Google Play Games Services and requires no additional setup.

Loading Leaderboard Metadata

Leaderboard metadata can be loaded to display names, icons, and available variants inside custom UI.

Loading All Leaderboards

Example scenario: build a custom leaderboard selection screen.

Typical usage pattern:

  • Call Get All Leaderboards with bForceReload set to true.
  • Store the returned array of FGooglePlayLeaderboard.
  • Use the metadata to populate UI elements such as titles and icons.

Loading a Single Leaderboard

If only one leaderboard is relevant, loading it individually is more efficient.

  • Call Get Leaderboard with the target LeaderboardID.
  • Enable bForceReload to ensure fresh data.

Loading Scores

Loading Top Scores

To display global or friends-based rankings, load the top scores for a leaderboard.

Example scenario: show the top 10 scores for a leaderboard.

Typical usage pattern:

  • Call Get Top Scores with the desired time span and collection.
  • Set MaxResults to limit the number of returned entries.
  • Use the returned array of FGooglePlayLeaderboardScore to populate a ranking list.

Loading Player-Centered Scores

To show rankings around the current player, use player-centered scores.

Example scenario: display the player’s rank with nearby competitors.

  • Call Get Player Centered Scores with the desired parameters.
  • This returns scores above and below the current player’s position.

This approach is useful for competitive feedback without showing the entire leaderboard.

Loading the Current Player’s Score

If you only need the player’s own score and rank, you can load it directly.

Example scenario: display the player’s best score on the main menu.

Typical usage pattern:

  • Call Get Current Player Score with the target LeaderboardID.
  • Check the bHasScore flag in On Success.
  • If true, use the returned FGooglePlayLeaderboardScore.

Important Notes and Common Mistakes

  • All leaderboard functions require the player to be signed in to Google Play Games Services.
  • Leaderboard IDs must exactly match the IDs defined in the Google Play Console.
  • Scores are automatically ordered based on the leaderboard configuration.
  • Submitting lower scores may be ignored depending on the leaderboard’s score order.
  • Leaderboard data may be cached locally unless a forced reload is requested.
  • Use immediate submission when you need confirmation or result data.

These examples cover the most common leaderboard usage patterns and are suitable for both simple scoreboards and more advanced competitive systems.