How To Add An Online Leaderboard In GameMaker


How To Add An Online Leaderboard In GameMaker

Johannes from LootLocker takes us through their latest GameMaker extension: Easy Leaderboard.


We've released an extension for GameMaker that makes it super easy to add online leaderboards to your game: we call it Easy Leaderboard by LootLocker!

In addition to the extension, we've also created a sample game called Rocky Runner that shows the leaderboards in action.

Rocky Runner gif

Click to play on itch.io

You can implement the Easy Leaderboard in five simple steps:

  1. Create a free LootLocker account
  2. Create a leaderboard
  3. Copy Game API key & leaderboardID
  4. Run InitializeLootLocker() from any Create event
  5. Run LootLockerCallback() from Async - HTTP event

Let's discuss each of those steps in more detail.

1. Create a free LootLocker account

Step one couldn't be simpler: head over to LootLocker and set up your free account.

undefineCreate a LootLocker Accountd

Once you're set up, we need to enable the Guest Login authentication method so that players can be identified by your game.

1. Click on the cog wheel on the sidebar:

Settings

2. Next, click on "Platforms":

Platforms

3. Scroll down and select "Guest Login":

Guest Login

4. Enable guest login by clicking the toggle in the top right corner. Then press "Save":

Enable Guest Login

Now we have our LootLocker settings just how we want them and can continue setting up our leaderboard.

Create a leaderboard in LootLocker

Now that you've signed up and configured LootLocker, it's time to create a leaderboard for your game.

1. In the LootLocker dashboard, click the "Systems" icon in the sidebar, and then "Leaderboards":

Leaderboards

2. Click "Create":

Create Leaderboards

3. Give your leaderboard a name and key. The name is what you use inside the LootLocker dashboard, and the key is what you can use as an identifier in your game. 

Check “Enable Game API writes”, and click "Save":

Create

Now we've created the leaderboard in LootLocker, we can begin implementing it in GameMaker!

Copy the Game API key & leaderboardID

We'll now want to copy the Game API key and leaderboardID from the LootLocker console into GameMaker.

The Game API key can be found in the "Settings" menu by clicking the cog wheel in the sidebar and selecting "Game Settings". 

You'll find it under the “API” tab.

Game API Key

The leaderboardID can be found by clicking on "Systems" and selecting "Leaderboards". You should see the ID of the leaderboard you created earlier.

You can also use the key that you entered earlier to identify the leaderboard.

Leaderboards ID


Run InitializeLootLocker() from any Create event

Inside GameMaker, create a new Object. In the "Create" event, insert the following code:

LootLockerInitialize("gameAPIkey", "version", "developmentMode", "leaderboardID");

If you’re using GML Visual, you’ll need to add the “Execute Code” action and enter the code inside it.

Initialize Call

Next, we'll replace the values that we just entered with real data.

  1. Replace "gameAPIkey" with the Game API key you copied from LootLocker as a string
  2. Replace "leaderboardID" with the leaderboardID(int) or key(string) that you copied from LootLocker
  3. Replace "version" with the version of your game, for example "0.0.0.1" as a string
  4. Replace "developmentMode" with boolean true or false (depending on which environment you created the leaderboard in in LootLocker)

Run LootLockerCallback() from the Async - HTTP event

Now we want to create a new Async - HTTP event. We can do this by selecting:

  1. Add Event -> Asynchronous -> Async - HTTP
  2. Insert the following code:

LootLockerCallback();

Callback

That's it - you're now ready to upload and display scores on your leaderboard in GameMaker!

What happens next?

Now that you've set up your leaderboard, it's time to hook it up to your game.

Included in the extension are two examples we created for different ways to implement the leaderboard:

  • LootLockerExample_SimpleLeaderboard
  • LootLockerExample_RockyRunner

Below, you can also find a variety of functions to make your leaderboard work in your game.

Upload a score to your leaderboard:

LootLockerSubmitScore("leaderboardID", “scoreYouWantToUpload”);

As mentioned previously, you can use the Key defined for a leaderboard in place of its ID. Both ways are valid.

Fetch the full list of high scores formatted as "1. PlayerName     1000":

LLHighscoresTopFormatted() - Returns a string

Fetch the full list of centered highscores formatted as "1. PlayerName     1000":

LLHighscoresCenteredFormatted() - Returns a string

There are plenty more leaderboard functions available in the extension, which you can read more about on the LootLocker website.

If you get stuck, join us on Discord and we'll do our best to help out.

Good luck and have fun!

//Johannes


Written by Gurpreet S. Matharoo

Technical Writer at GameMaker, Gurpreet creates documentation and tutorials, to make game dev easier for you. He loves using the computer to bring new things to life, whether it's games, digital art, or Metal music.