xboxlive_stats_get_social_leaderboard


Description

This function can be used to retrieve a social 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 created it using the xboxlive_stats_set_stat_* functions), and then you specify a number of details about what leaderboard information you want to retrieve. Note that you can only retrieve a social leaderboard for int or real stats, but not for string stats, and that if you flag the "favourites_only" argument as true, then the results will only contain data for those friends that are marked by the user as "favourites".

IMPORTANT! Stats used in social leaderboards do not need to be registered as "Featured Stats" in the XDP/Windows Dev Center..


The function will generate a callback which will trigger a System Asynchronous Event. This event will have the special 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_social_leaderboard(user_id, stat, num_entries, start_rank, start_at_user, favourites_only);

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)
favourites_only Set to true to show only friends that are marked as "favourites" or false otherwise


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_social_leaderboard(user_id, "GlobalTime", 20, 1, false, false);

The above code would be called to get a list of all global 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.