Skip to content

Leaderboards

Jump to bottom
Francisco Dias edited this page Apr 6, 2024 · 6 revisions

Leaderboards

Leaderboards can be a fun way to drive competition among your players, both for your most hardcore fans (who will be fighting for the top spot in a public leaderboard) and for your more casual players (who will be interested in comparing their progress to their friends').

Functions

The following functions are provided for working with leaderboards:

Constants

The following constants are provided to be used as input arguments or output values:

Structs

The following structures are used as output values from the function calls to the GooglePlayServices API:


Back To Top

GooglePlayServices_Leaderboard_LoadPlayerCenteredScores

Asynchronously load the player-centered page of scores for a given leaderboard. If the player does not have a score on this leaderboard, this call will return the first page instead.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

GooglePlayServices_Leaderboard_LoadPlayerCenteredScores(leaderboardId, span, collection, maxResults, forceReload)
Argument Type Description
leaderboardId String The unique identifier of the leaderboard.
span LeaderboardTimeSpan The time span to retrieve data for.
collection LeaderboardCollection he collection to retrieve scores for
maxResults Real The maximum number of scores to fetch per page. Must be between 1 and 25.
forceReload Boolean If true, this call will clear any locally cached data and attempt to fetch the latest data from the server. This would commonly be used for something like a user-initiated refresh. Normally, this should be set to false to gain advantages of data caching.

Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "GooglePlayServices_Leaderboard_LoadPlayerCenteredScores"
ind Real The id of the request this callback refers to.
data String A json formatted string of an array of LeaderboardEntryJSON. This string can be parsed into an array with the function json_parse.

Example:

GooglePlayServices_Leaderboard_LoadPlayerCenteredScores(Leaderboard1, Leaderboard_TIME_SPAN_ALL_TIME, Leaderboard_COLLECTION_PUBLIC, 5, true)

The code sample above will start a query for player centered leaderboard entries. The results can be caught inside an Social Async Event.

if(async_load[?"type"] == "GooglePlayServices_Leaderboard_LoadPlayerCenteredScores")
{
    var array = json_parse(async_load[?"data"])
    for(var a = 0 ; a < array_length(array) ; a ++)
    {
        var struct = array[a]
        var ins = instance_create_depth(800,200+a*75,00,Obj_GooglePlayServices_Leaderboard_Entry)
        ins.displayRank = struct.displayRank;
        ins.displayScore = struct.displayScore;
        ins.rank = struct.rank;
        ins.rawScore = struct.rawScore;
        ins.scoreHolder = struct.scoreHolder;
        ins.scoreHolderDisplayName = struct.scoreHolderDisplayName;
        ins.scoreHolderHiResImageUri = struct.scoreHolderHiResImageUri;
        ins.scoreHolderIconImageUri = struct.scoreHolderIconImageUri;

        // This is an options parameter and is only present if a scoreTag was provided.
        ins.scoreTag = struct[$ "scoreTag"];

        ins.timestampMillis = struct.timestampMillis;
    }
}

The code above shows a way of reading the returned data using the function json_parse. This sample is taken from the demo project check the project for more context.



Back To Top

GooglePlayServices_Leaderboard_LoadTopScores

Asynchronously load the top page of scores for a given leaderboard.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

GooglePlayServices_Leaderboard_LoadTopScores(leaderboardId, span, collection, maxResults, forceReload)
Argument Type Description
leaderboardId String The unique identifier of the leaderboard.
span LeaderboardTimeSpan The time span to retrieve data for.
collection LeaderboardCollection he collection to retrieve scores for
maxResults Real The maximum number of scores to fetch per page. Must be between 1 and 25.
forceReload Boolean If true, this call will clear any locally cached data and attempt to fetch the latest data from the server. This would commonly be used for something like a user-initiated refresh. Normally, this should be set to false to gain advantages of data caching.

Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "GooglePlayServices_Leaderboard_LoadTopScores"
ind Real The id of the request this callback refers to.
data String A json formatted string of an array of LeaderboardEntryJSON. This string can be parsed into an array with the function json_parse.

Example:

GooglePlayServices_Leaderboard_LoadTopScores(Leaderboard1, Leaderboard_TIME_SPAN_ALL_TIME, Leaderboard_COLLECTION_PUBLIC, 5, true)

The code sample above will start a query for top scores leaderboard entries. The results can be caught inside a Social Async Event.

if(async_load[?"type"] == "GooglePlayServices_Leaderboard_LoadTopScores")
{
    var array = json_parse(async_load[?"data"])
    for(var a = 0 ; a < array_length(array) ; a ++)
    {
        var struct = array[a]
        var ins = instance_create_depth(800,200+a*75,00,Obj_GooglePlayServices_Leaderboard_Entry)
        ins.displayRank = struct.displayRank;
        ins.displayScore = struct.displayScore;
        ins.rank = struct.rank;
        ins.rawScore = struct.rawScore;
        ins.scoreHolder = struct.scoreHolder;
        ins.scoreHolderDisplayName = struct.scoreHolderDisplayName;
        ins.scoreHolderHiResImageUri = struct.scoreHolderHiResImageUri;
        ins.scoreHolderIconImageUri = struct.scoreHolderIconImageUri;

        // This is an options parameter and is only present if a scoreTag was provided.
        ins.scoreTag = struct[$ "scoreTag"];

        ins.timestampMillis = struct.timestampMillis;
    }
}

The code above shows a way of reading the returned data using the function json_parse. This sample is taken from the demo project check the project for more context.



Back To Top

GooglePlayServices_Leaderboard_Show

This function will call the Google Play Services overlay for a specific leaderboard.


Syntax:

GooglePlayServices_Leaderboard_Show(leaderboardId)
Argument Type Description
leaderboardId String The unique identifier of the leaderboard.

Returns:

N/A


Example:

GooglePlayServices_Leaderboard_Show(leaderboardId);

The code above will trigger the leaderboard overlay of the given leaderboard.



Back To Top

GooglePlayServices_Leaderboard_ShowAll

This function will call the general Google Play Services leaderboards overlay. Here the user will have access to all the existing leaderboards of the current application.


Syntax:

GooglePlayServices_Leaderboard_ShowAll()

Returns:

N/A


Example:

GooglePlayServices_Leaderboard_ShowAll()

The code above will trigger the leaderboard overlay of all the available leaderboards for this game.



Back To Top

GooglePlayServices_Leaderboard_SubmitScore

This function requests the Google Play Services API to submit a score to the given leaderboard.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

GooglePlayServices_Leaderboard_SubmitScore(leaderboardId, score, scoreTag)
Argument Type Description
leaderboardId String The unique identifier of the leaderboard.
score Real The value to be submitted to the leaderboard (remember that only the highest score value is displayed in the leaderboard).
scoreTag String A tag that will be added to the value being submitted to the leaderboard (note that this value is required, if you don't want to set a tag use an empty string).

Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "GooglePlayServices_Leaderboard_SubmitScore"
ind Real The id of the request this callback refers to.
success Boolean Whether or not the function request succeeded.
leaderboardId String The unique name of the leaderboard.
score Real The submitted score.
scoreTag String The tag for the current submission.
report String A json formatted string of LeaderboardReportJSON. This string can be parsed into a struct with the function json_parse. Only available if the task succeeds.

Example:

GooglePlayServices_Leaderboard_SubmitScore(leaderId, 100, "archer");

The code sample above will submit a new score to the leaderboard with a specific tag ("archer"). The result can be caught inside a Social Async Event as follows:

if(async_load[?"type"] == "GooglePlayServices_Leaderboard_SubmitScore")
if(async_load[?"success")
{
    //Done, let's continue
}

The code above checks if the task was successful. This sample is taken from the demo project check the project for more context.



Back To Top

LeaderboardCollection

These constants represent kinds of leaderboard collections.

These constants are referenced by the following functions:


Member Description
Leaderboard_COLLECTION_SOCIAL These leaderboards contain the scores of players in the viewing player's friends list.
Leaderboard_COLLECTION_PUBLIC Public leaderboards contain the scores of players who are sharing their gameplay activity publicly.

Back To Top

LeaderboardTimeSpan

These constants represent the various types of time span that can be used.

These constants are referenced by the following functions:


Member Description
Leaderboard_TIME_SPAN_DAILY Refers to the scores of the day. Scores are reset every day. The reset occurs at 11:59PM PST.
Leaderboard_TIME_SPAN_WEEKLY Refers to the scores of the week. Scores are reset once per week. The reset occurs at 11:59PM PST on Sunday.
Leaderboard_TIME_SPAN_ALL_TIME Refers to all the scores. Scores are never reset.

Back To Top

LeaderboardEntryJSON

Represents a score and its associated metadata.


Member Type Description
displayRank String A formatted string to display for this rank. This handles appropriate localization and formatting.
displayScore String A formatted string to display for this score. The details of the formatting are specified by the developer in their dev console.
rank Real The rank returned from the server for this score. Note that this may not be exact and that multiple scores can have identical ranks. Lower ranks indicate a better score, with rank 1 being the best score on the board.
rawScore Real The raw score value.
scoreHolder PlayerJSON A struct of PlayerJSON.
scoreHolderDisplayName String The display name of the player that scored this particular score.
scoreHolderHiResImageUri String The URI of the hi-res image to display for the player who scored this score (you can later convert the uri to a local path using the GooglePlayServices_UriToPath).
scoreHolderIconImageUri String The URI of the icon image to display for the player who scored this score (you can later convert the uri to a local path using the GooglePlayServices_UriToPath).

Back To Top

LeaderboardReportJSON

Represents a leaderboard report and its associated metadata.


Member Type Description
allTime LeaderboardReportEntryJSON The all time result report.
weekly LeaderboardReportEntryJSON The weekly result report.
daily LeaderboardReportEntryJSON The daily result report

Back To Top

LeaderboardReportEntryJSON

Represents a leaderboard report entry.

This struct is referenced by the following structs:


Member Type Description
isNewBest Boolean Whether or not this score is a new best.
score Real The score submitted to the server.
scoreTag String The tag used the submittion of the achievement.

GameMaker 2024

Google Play Services

Guides

Modules

Clone this wiki locally