GMCloud and GameMaker Part 6: High Scores and Ranks

GMCloud’s has a High Score service that can be used to keep track of player scores and ratings. Currently only the high-score service is available; player ranking mode (which only allows one entry per player on the score table, which gets updated every time the player submits a new score) will become available in the future.

Assuming you’ve read all previous parts up til now (particularly Part 1, Part 2 and Part 3, and Part 5), how the highscore system can be used should be familiar to you.

Submitting High Scores

High Scores are tied to player accounts, so the player will need to already have been linked to the game (as described in previous parts). And just as with Cloud Saves, the library function to issue a high score submission request is as follows, assuming our logged-in player’s linkId and linkSecret are stored in a ds_map:

uuid = gmcloud_add_score(data[? "linkId"], data[? "linkSecret"], score);

Score is a whole number between 0 and 999,999,999,999. Fractions will be rounded; and numbers outside this range will be clamped.

The result of this request is a rank corresponding to what rank in the High Score table this new score is. If the score is higher than all other scores on the table, the rank will be 1. If the score is lower than all other scores on the table, then the rank will be whatever number of scores are on the table.

The rank can be extracted from the result just like we do in previous parts:

if (gmcloud_result_exists(uuid)) {
    var rank = real(gmcloud_result_pop(uuid));
    // we now have the rank value
}
else if (gmcloud_error_exists(uuid)) {
    var error = gmcloud_error_pop(uuid));
    // here was an error
}

Getting the player’s current High Score

The player’s current highest score in the game, and the rank of this score, can be found using:

uuid = gmcloud_get_myscorerank(data[? "linkId"], data[? "linkSecret"]);

The result of the request is a JSON containing a score key of the highest score the player has submitted so far, and a rank key containing the rank of this score. To decode, we can do:

if (gmcloud_result_exists(uuid)) {
    var scores = gmcloud_result_pop(uuid);
    var data = json_decode(scores);
  
    // we now do something with data[? "score"] and data[? "rank"]
    
    ds_map_destroy(data);
}

The player’s current highest score is also stored in their game profile under the highScore key

Getting the High Scores for the game

There are two ways to get the leader table: being logged in, and without being logged in.

If logged in, the following can be used:

uuid = gmcloud_get_topscoresowner(data[? "linkId"], data[? "linkSecret"], 5);

The last argument is the number of high scores to download, the current maximum is 20 scores.

If not logged in, the following can be used:

uuid = gmcloud_get_topscores(5);

Both request the same data, however gmcloud_get_topscoresowner will include an extra key called you indicating whether the high score is yours. This is to facilitate highlighting the player’s own scores in the user interface.

The return format is something like the following JSON:

[
  {
    "displayName": "meseta",
    "you": true,
    "rank": 1,
    "score": 999999,
    "created": 1547297937
  },
  {
    "displayName": "steve",
    "you": false,
    "rank": 2,
    "score": 9999,
    "created": 1547297922
  }, 
  {
    "displayName": "anonymous",
    "you": false,
    "rank": 3,
    "score": 55,
    "created": 1547297788
  },
  ...

Note: when importing using GML’s json_decode , a ds_map will be created with a default key containing the list. The code to handle this might look something like:

if (gmcloud_result_exists(uuid)) {
    var scores = gmcloud_result_pop(uuid);
    var data = json_decode(scores);
    var score_list = data[? "default"];

    for (var i=0; i<ds_list_size(score_list); i++) {
        var score_entry = score_list[| i];
        // the following values are now available:
        // score_entry[? "rank"]
        // score_entry[? "displayName"]
        // score_entry[? "score"]
        // score_entry[? "created"]
        // score_entry[? "you"] - if you used gmcloud_get_topscoresowner
    }
    ds_map_destroy(data);
}

Viewing High Scores online

High Scores are also available on your game’s page on the GMCloud website, and might look something like this (if I was your only player)

An example of when meseta plays your game a lot

Note the duplicate rank 6 on the scorebored. When more than one score entries have equal value, they will receive the same rank. This will however cause the next ranks to be omitted. In the above example, because rank 6 appears an extra 2 times, rank 7 and 8 will be skipped, and the next rank is 9. This is consistent if you consider that Rank 9 is the 9th highest score; while Rank 6 is the 6th highest score.

That’s it! You can now submit and read highscores from within GM. A dashboard is also available on your game’s page on the GMCloud website, providing a central place for people to view the highscores.