achievement_load_leaderboard

Get leaderboard data, either for all players or only friends.

Syntax:

achievement_load_leaderboard(ident, minindex, maxindex, filter)


Argument Description
ident The unique ID of the leaderboard as shown on the developer dashboard.
minindex The starting index value to get the leaderboard data from.
maxindex The maximum index value to get the leaderboard data from.
filter Whether to filter the results to those that are on your friends list or to all players (see the Description below)


Returns: N/A


Description

This function will send a request to the server for information on the given leaderboard. The leaderboard must have been created previously on the developer dashboard for your game and the ID given is that which you must supply as the first argument of the function. It will trigger a callback Social Asynchronous Event which contains the async_load map populated with the relevant key/value pairs. The id key of this ds_map is used to identify the correct callback (there can be more than one trigger function for any given asynchronous event), and will be paired with the constant achievement_leaderboard_info as well as a number of other key/value pairs for each player. The exact contents of the map are shown below:

  1. "id" - For this function it should be achievement_leaderboard_info

  2. "leaderboardid" - The unique ID for the leaderboard as defined on the provider dashboard.

  3. "numentries" - The number of entries in the leaderboard that you have received.

  4. "PlayerN" - The name of the player, where "N" is an integer value corresponding to their position within the leaderboard entries list.

  5. "PlayeridN" - The unique user id of the player, "N".
  6. "RankN" - The rank of the player "N" within the leaderboard.

  7. "ScoreN" - The score of the player "N".

You can specify the exact portion of the leaderboard to show by giving a minimum and maximum index value, as well as request that the results be filtered to retrieve only those scores by your friends or those posted by all players using the following filter constants:

NOTE: this function does not work on the Android platform.


Extended Example:

The following code would probably be called after the player has logged into their game account using achievement_login to get a list of all friends leaderboard positions for the game, on either Android or iOS:

if os_type == os_android
   {
   achievement_load_leaderboard("CgkIs9_51u0PEAIQBw", 1, 100, achievement_filter_friends_only);
   }
else
   {
   achievement_load_leaderboard("leaderboard1id", 1, 100, achievement_filter_friends_only);
   }

This will send off a request for the information on the given leaderboard and generate an asynchronous callback with the special async_load ds_map containing the following data:

var ident = ds_map_find_value(async_load, "id");
if ident == achievement_leaderboard_info
   {
   var lbid = ds_map_find_value(async_load,"leaderboardid");
   if lbid == "CgkIs9_51u0PEAIQBw" || lbid == "leaderboard1id"
      {
      global.numentries = ds_map_find_value(async_load,"numentries");
      for(var i = 0; i < numentries; i++;)
         {
         global.playername[i] = ds_map_find_value(async_load, "Player" + string(i));
         global.playerid[i] = ds_map_find_value(async_load, "Playerid" + string(i));
         global.playerrank[i] = ds_map_find_value(async_load, "Rank" + string(i));
         global.playerscore[i] = ds_map_find_value(async_load, "Score" + string(i));
         achievement_get_pic(global.playerid[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 make sure that the leaderboard being sent matches the original function call before looping through the map and storing all the different values in a number of arrays. It also requests an image for each of the entries in the map (see achievement_get_pic).


Back: Achievements and Leaderboards
Next: achievement_load_progress
© Copyright YoYo Games Ltd. 2018 All Rights Reserved