Table of Contents

Leaderboards

Adding leaderboards to your game can help retaining your players by displaying the scores of the best ones.

GDevelop provides a built-in solution to create, manage and use leaderboards in your game. To enjoy it, your game must be registered (it is by default) but not necessarily public.

Manage leaderboards

In the games dashboard, you can access all the leaderboards linked to your game. To find more details on how to manage and configure leaderboards, please refer to Leaderboard Administration.

You can also access this administration interface from within the actions and conditions related to leaderboards.

Send a new score to a leaderboard

You can use the action “Save player score”.

Choose a leaderboard

If you haven't created a leaderboard yet, please do so in the admin interface.

Once it is done, you can either select the leaderboard you want to send the score to, or use an expression to define the unique id of the leaderboard (if it is stored in a scene variable for instance).

Set the score to send

A number field is available to set the score you want to send.

Set the name of the player

For the player to type their name, you can use the Text Input or Text Entry objects and then use the result to set the player name in the entry that will be sent to the leaderboard.

The player name must respect a few constraints (30 characters-long, allowed characters are letters from the latin alphabet or numbers and the characters -, _ and |).

To help you respect those constraints, the action will apply the expression Leaderboards::FormatPlayerName to the provided player name. Here is a few examples on how this expression can transform the player name:

Original player name Formatted Why
"Dr Neo Cortex-24|7" "Dr_Neo_Cortex-24|7" White spaces replaced by _
"Senna$!" "Senna" Special characters removed
"Brûlé" "Brule" Diacritic marks removed
"aPlayerNameTh4tIsT00LongToBeSaved" "aPlayerNameTh4tIsT00LongToBeSa" Name truncated if too long
"" (empty) "Player89456" Random name if input is empty (5-digits-long number)

Check the score was correctly saved

You have 3 conditions at your disposal to monitor how the saving is run through.

For each of those conditions, you can specify the leaderboard but this is optional. This can prove useful if you try to save the player score in multiple leaderboards at once.

Display a leaderboard

You can use the action “Display leaderboard”. It will be displayed on top of your game, and the view will have a button to close it in order to come back to your game.

Leaderboards can be displayed on any platform: Android, iOS, desktop, on the web. They will work everywhere and will adapt to the screen size.

Choose the leaderboard to display

Simply select the leaderboard you want to display, much like when you send a score to a leaderboard.

Wait for the leaderboard to display

In order to give feedback to the player that the leaderboard will display soon, you have the choice between 2 options:

  • Display the built-in loader on top of your game (option available in the action)
  • Use the condition “Leaderboard display is loading” to trigger an action (display a text “Loading” for example)

Either case, if there's an error during the display, it will close automatically. You can also use the 2 conditions “Leaderboard display has errored” and “Leaderboard display has loaded” if you want to add logic around a possible error.

Pause the scene when the leaderboard is displayed

You may want to pause the scene while the leaderboard is displayed. Here is our recommendation to achieve that:

  • Suppose you have a scene that is named “Level 1”
  • Create a new scene “LeaderboardBackground”
    • This scene will run in background when the leaderboard is displayed
  • In the events sheet of scene “Level 1”, add this event:

  • In the events sheet of scene “LeaderboardBackground”, add this event to go back to “Level 1” scene: