Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
  Leaderboards for GameMaker Studio 2

Utilize official Leaderboards for your GameMaker Studio 2 game jam entry


  • YYC (YoYo Compiler)
  • GameMaker Studio 2 v2.3.0 or newer
  • Windows (other platforms not supported, but may work)
  • Leaderboards enabled for your game on
  • OAuth2 for GameMaker Studio 2


🚨 This library requires that OAuth2 for GameMaker Studio 2 is installed in your GameMaker Studio 2 project.

  1. Go to Dashboard > Games > (your game) > Leaderboards to create and edit your game's leaderboards.

Once you have created your first leaderboard, the credentials and information required to submit and retrieve scores is presented to you.

  1. Copy and paste the contents of the gm48_leaderboards_library.gml file into a new script resource.

  2. Create a new persistent object resource and set up the following events:


You must first set the Game API Token. This is used to recognize the request came from your game. The value for gameApiToken can be found in Dashboard > Games > (your game) > Leaderboards.


Initialize the leaderboards.


You may optionally send an argument, which contains the script that should be executed when any response from the API has been received.


Async HTTP


Example project

  1. Download the repository and open the project file in GameMaker Studio 2.

The project will not work out-of-the-box, as you must first retrieve an access token via OAuth2 for GameMaker Studio 2.

You must also change the variables leaderboardId and gameApiToken values in the obj_example object resource to the corresponding leaderboard ID and Game API Token in Dashboard > Games > (your game) > Leaderboards.

  1. Launch the game in debug mode (F6). Watch the console output for debugging information.

  2. Press Enter to submit a score. OAuth2 for GameMaker Studio 2

Please refer to the OAuth2 for GameMaker Studio 2 repository for installation.

YYC (YoYo Compiler)

Please refer to this explanation for details.


Before you can use the leaderboards, you must ask the player for authorization to use their account.

This functionality is provided via the OAuth2 for GameMaker Studio 2 library. Please refer to the repository for instructions.

Once the player has been authorized, you may proceed to use the Leaderboards library.

Submitting scores

🚨 Submitting scores is always done on the behalf of an account. You should not use your own or the same account for player score submitted. That defeats the purpose.

All you need to submit a score is 1) the ID of the leaderboard, which corresponds to the ID value found in Dashboard > Games > (your game) > Leaderboards, and 2) the score that you wish to submit.

gm48_leaderboards_add_score(leaderboardId, scoreToSubmit)

When you use the gm48_leaderboards_add_score function, the request ID is returned. Store this value if you want to recognize your request later. All requests are stored in the global gm48_leaderboards_request ds_map variable.

You may send meta information along with the score. Please see the obj_example object resource's Key Up: Enter event for details on how to implement this functionality.

Once the request to the Leaderboards API has been processed, a response is sent back to GameMaker Studio 2 via the Async HTTP event, and if you have defined a callback script, the response and the request ID will be sent along as the the callback script is executed.

function scr_example_callback(response, requestId)
    show_message("Your score has been submitted to the official Leaderboards!");

The response value is a struct, as the raw response is run through json_parse. Please see GameMaker Studio 2 documentation for more information on how to deal with structs.

Retrieving scores

The callbacks scr_all_scores_callback_example and scr_my_scores_callback_example values should correspond to script resources in your project.

The script resource will be executed in the same fashion as the scr_example_callback example in the previous section.

All scores

gm48_leaderboards_get_all_scores(leaderboardId, scr_all_scores_callback_example);

The player's scores

gm48_leaderboards_get_my_scores(leaderboardId, scr_my_scores_callback_example);

Here's an example on how to check if the user has submitted any scores:

function scr_my_scores_callback_example(response){
    if (array_length( > 0) {
        global.playerHasSubmittedAScore = true;


For any security related issues, please use the form located here: instead of using the issue tracker.


See CHANGELOG for details on what has changed.


See CONTRIBUTING for details on how to contribute.



MIT License


No releases published

Sponsor this project