xboxlive_stats_get_leaderboard


Description

This function can be used to retrieve a global leaderboard of ranks for a given statistic. You supply the user ID (as returned, for example, by the function xboxlive_get_user), the stat string (as defined when you registered it as a "Featured Stat"), and then you specify a number of details about what leaderboard information you want to retrieve. Note that you can only retrieve a global leaderboard for int or real stats, but not for string stats.

IMPORTANT! Stats used in global leaderboards must be registered as "Featured Stats" in the XDP/Windows Dev Center otherwise an error will be returned. If you want local (social) leaderboards, then please see the function xboxlive_stats_get_social_leaderboard().


The function will generate a callback which will trigger a System Asynchronous Event. This event will have the built in DS map async_load which should then be parsed for the following keys:

The rest of the DS map will also contain the leaderboard data with the following format (where "N" is the position in the leaderboard data, from 0 to "numentries"):

IMPORTANT! This function is only valid when exporting using the UWP target for the Xbox One and it requires you to have checked the Enable XBox Live option in the UWP Game Options.


Syntax:

xboxlive_stats_get_leaderboard(user_id, stat, num_entries, start_rank, start_at_user, ascending);

Argument Description
user_id The user ID of the user to get the leaderboard for
stat The stat (as string) to create the global leaderboard from
num_entries The number of entries from the global leaderboard to retrieve
start_rank The rank in the leaderboard to start from (use 0 if the "start_at_user" argument is set to true)
start_at_user Set to true to start at the user ID rank, false otherwise (set to false if the "start_rank" argument is anything other than 0)
ascending Set to true for ascending order and false for descending order


Returns:

N/A


Extended Example:

The following is an extended example of how this function can be used. To start with you'd call it in some event like Room Start or Create:

xboxlive_stats_get_leaderboard(user_id, "GlobalTime", 20, 1, false, true);

The above code would be called to get a list of all social leaderboard positions for the game, and will generate a Social Asynchronous Event call back which we would deal with in the following way:

if async_load[? "id"] == achievement_stat_event
    {
    if async_load[? "eventname"] == "GetLeaderboardComplete"
        {
        global.numentries = async_load[? "numentries"];
        for(var i = 0; i < numentries; i++;)
            {
            global.playername[i] = async_load[? "Player" + string(i)];
            global.playerid[i] = async_load[? "Playerid" + string(i)];
            global.playerrank[i] = async_load[? "Rank" + string(i)];
            global.playerscore[i] = async_load[? "Score" + string(i]);
            }
        }
    }

The above code checks the returned ds_map in the Social Asynchronous Event and if its "id" matches the constant being checked, it then checks to see if the event has been triggered by returned leaderboard data before looping through the map and storing all the different values in a number of global arrays.