This function is used retrieve a sequential range of leaderboard entries by leaderboard ranking. The start_idx and end_idx parameters control the requested range of ranks, for example, you can display the top 10 on a leaderboard for your game by setting the start value to 1 and the end value to 10. The leaderboard name is a string that was defined when you created the leaderboard using the function steam_create_leaderboard, and the function will return a value which can then be used to identify the call-back in the Steam Async Event, or it will return -1 if it has failed. Note that when downloading a leaderboard, the "entries" key of the async_load map may have an additional "data" key if any additional buffer data was uploaded along with the score(see steam_upload_score_buffer()). This data buffer will be Base 64 encoded and so you will need to use the function buffer_base64_decode() on the buffer before reading the data.


steam_download_scores(lb_name, start_idx, end_idx);

Argument Description
lb_name The name of the leaderboard that you are downloading the scores from (a string).
start_idx The start position within the leaderboard.
end_idx The end position within the leaderboard.



Extended Example:

In this extended example we will request the top ten ranking for the given leaderboard and parse its results in the Steam Async Event. to start with we need to request the scores with the following code:

score_get = steam_download_scores("Game Scores", 1, 10);

This will send off a request to the Steam Server for the scores from the leaderboard "Game Scores", storing the async id of the request in the variable "score_get". this will then be handled in the Steam Async Event in the following way:

var async_id = ds_map_find_value(async_load, "id");
if async_id == score_get
    var entries = ds_map_find_value(async_load, "entries");
    var map = json_decode(entries);
    if ds_map_exists(map, "default")
        var list = ds_map_find_value(map, "entries");
        var len = ds_list_size(list);
        var entry;
        for(var i = 0; i < len; i++;)
            entry = ds_list_find_value(list, i );
            steam_name[i] = ds_map_find_value(entry, "name");
            steam_score[i] = ds_map_find_value(entry, "score");
            steam_rank[i] = ds_map_find_value(entry, "rank");

What we do here is first check the "id" key of the special async_load ds_map. If this value is the same as the value of the original call-back function (stored in the "score_get" variable) we then continue to process the data. The first thing we do is parse the async_load ds_map for the key "entries" which will contain a JSON object containing the leaderboard data. This JSON object is then decoded (see json_decode) as another ds_map, and this new map id is stored in the variable "map".

This map is checked for the key "default" and if that is found then the map is destroyed and the event is exited. If no "default" key is found, the code will then parse the map to extract the necessary information about the leaderboard, by first extracting a ds_list from the "entries" key of the ds_map, and then looping through each entry of the list to get another ds_map with the name, score and rank of each entry. These values are then stored to arrays.

Once the loop has finished, the JSON ds_map is destroyed (which in turn destroys all the internal maps and lists). There is no need to destroy the async_load ds_map as this is handled for you by GameMaker Studio 2.