Leaderboards

ChilliConnect Leaderboards allow you to rank your players in real-time and compare scores globally or with the Player's Facebook friends. Leaderboards are added through the Leaderboards page within the ChilliConnect dashboard.

ConnectLeaderboards

For each Leaderboard, the following properties can be specified:

NameDescriptive name for the Leaderboard
KeyThe Key used to identify the Leaderboard in API calls from your game
DescriptionOptional detailed description for the Leaderboard
Ranking TypeThe order in which scores will be ranked, either from Highest to Lowest or from Lowest to Highest
Update TypeHow updates to the score will be treated. See Update Types
Rank ScoresWhether or not scores submitted to this Leaderboard should be ranked. See Ranking Limits
Partition Ranking LimitIf this is a ranked Leaderboard, limit the number of ranked scores per partition. See Ranking Limits
Reset FrequencyHow often the Leaderboard is reset, using Daily, Weekly, Monthly scheduling options, or on demand when configured with Ad-Hoc
Run Cloud Code Script on ResetIf the Leaderboard is resettable, run the specified Cloud Code scripts when the Leaderboard resets. See Reset Scripts

Scores can be added to a Leaderboard using the AddScore method. You can then retrieve a players score with GetPlayerScore, scores around the player with GetScoresAroundPlayer and scores for the players Facebook friends with GetScoresForFacebookFriends. For a complete list of Leaderboard functions available, see the Leaderboards module of the API.

Update Types

The Update Type of a leaderboard determines how updates to existing scores in the leaderboard treated. Update Type can be one of the following values:

Highest ScoreWill update the score if there is a new score submitted with a greater (or lesser depending on the Ranking Type) value.
Latest ScoreWill update scores based on the timestamp. Any new score that is submitted is applied.
CumulativeThe new score is added to the old score in every update operation on this type.
Ranking TypeThe order in which scores will be ranked, either from Highest to Lowest or from Lowest to Highest
AppendThe submitted score value is ignored and a score is appended to the end of the Leaderboard on first submission. Subsequent updates are ignored. The Append update type can be useful for alternative use cases such as bucketing.

Partitions

Partitions allow you to dynamically sub-divide a single Leaderboard and are useful when you require a very large number of Leaderboards with the same configuration - for example, if you have a Leaderboard for every level in your game and you have 100 levels, rather than having to create 100 Leaderboards in ChilliConnect, you can create a single "Levels" Leaderboard, and have the game client specify the partition as the level number.

To do this, when calling the AddScore method, you can set the PartitionKey to the level name, such as LevelOne, LevelTwo etc. and the Leaderboard will store scores for each level separately. In order to retrieve scores for a specific level, you can provide the PartitionKey to any of the GetScore endpoints.

You are able to view scores by partition on the dashboard by either selecting or specifying which partition to view in the "Recent Partitions" drop-down list.

Note that every Leaderboard has a limit of 10,000 partitions, and if the Leaderboard has reset period defined for it then this limit will apply to each reset period individually. When this limit is reached no AddScore requests that have a new partition defined will succeed.

ConnectDashboardPartitions

Resets

Leaderboards can be configured to reset, either automatically on a predefined schedule or manually through the ChilliConnect dashboard.

Date

When configuring a Leaderboard you have the option to specify if you want it to reset at a certain date and time. The reset date is always specified in UTC.

ConnectResetWeekly

You can retrieve scores for a previous reset period through any of the GetScore endpoints by specifying the Period parameter in the request. Scores will be returned for the reset period that was active on the specified date. GetScores requests that do not provide the Period parameter will default to the currently active date period for that Leaderboard.

You can browse scores submitted through a specific reset periods using the date range selector on the scores screen. The range will snap to the appropriate upper and lower date boundaries for your defined reset period.

ConnectResetWeeklyDashboardView

Ad-Hoc

Rather than resetting on a fixed schedule, Ad-Hoc Leaderboards are manually reset using the "Reset" button from the Leaderboard scores view on the ChilliConnect Dashboard.

ConnectResetAdHocReset

All of the reset periods that have been triggered are listed under the "Ad-Hoc Reset Dates" tab. The GetResetPeriods API call can also be used to load all reset periods for Ad-Hoc Leaderboards.

ConnectResetAdHocResetList

Ranking Limits

The number of ranked scores that can be stored in a Leaderboard is limited by account type:

Trial100k
Indie5m
Start Up20m
Studio50m
Enterprise50m (negotiable).

The ranking limit is global for each game and includes scores across all partitions. For Leaderboards that reset, scores in previous reset periods do not count towards the ranking limit. The current number of ranked scores and the limit for any specific game can be viewed from "Limits" tab on the Game View:

ConnectRankedScoresLimit

For scores that are not ranked, the GlobalRank property will be returned as 0. Unranked scores are not included in the various Get Score API responses apart from GetPlayerScore.

Leaderboards can also be pre-configured with a Partition Ranking Limit. Setting the Partition Ranking Limit will cause only the top x scores per Partition to be ranked (this includes the "default" Partition that is used when no PartitionKey is specified). This can be useful if you anticipate a Leaderboard having a large number of Partitions but want to evenly distribute ranked scores across them. For example, in a game with 100's of levels, you might have a Partition per level but chose to only rank the top 1,000 scores for each level. This can prevent early levels that all players play from using up the entire ranked scored allocation.

Reset Scripts

For Leaderboards that reset, you can specify up to 10 Cloud Code scripts to run when a reset happens, this allows you to implement features such as rewards for top ranking players.

ConnectPlayerDelete

TypeRange or All. "Range" scripts are executed for a subset of scores, "All" scripts are executed against every score in the Leaderboard.
Start RankIf Type is Range, the (inclusive) starting rank of the scores to run the script against.
End RankIf Type is Range, the (inclusive) end rank of the scores to run the script against.
ScriptThe Cloud Code script to run against the specified scores. Must be an Event script with the Event Type of "Leaderboard Reset".

Each specified script will be executed once per score in the defined range. Scripts are executed for ranked scores across all active partitions within the reset period, are automatically set to run within the correct player context, and have access to information about the score and rank via the ChilliConnect.Event.Data variable. The below code sample shows all contextual information available:

//An example script
//When a Leaderboard is Reset, apply appropriate rewards
var rank = ChilliConnect.Event.Data.Rank;
var score = ChilliConnect.Event.Data.Score;
var leaderboardKey = ChilliConnect.Event.Data.LeaderboardKey;
var partition = ChilliConnect.Event.Data.Partition;
var period = ChilliConnect.Event.Data.Period;
var ranksTotal = ChilliConnect.Event.Data.RanksTotal;

//get the required version of the SDK see: https://docs.chilliconnect.com/api/?system=script&sdk=2.18.0
var sdk = ChilliConnect.getSdk("2.18.0");

try {
    var currency = "COINS";
    var amount = 10;

    if(rank <= 10){
        currency = "GOLD";
        amount = 20;
    }

    sdk.Economy.addCurrencyBalance(currency, amount);
}
catch(e)
{
    ChilliConnect.Logger.error("Error:" + e );
}

Deleting Scores

To delete a score for the Leaderboard, click on the delete icon at the end of the row. Removing a score will reorder the Leaderboard table.

Alternatively you can handle the deletion of Leaderboard scores from the Client device using the DeleteScore. It's currently not possible to delete a score that belongs to a Leaderboard when the reset period has passed. Only scores that fall into the currently active period can be deleted. Also note that deleting a ranked score will not re-rank any unranked scores that are currently stored against a leaderboard.

Alternative Use Cases

Leaderboards in ChilliConnect are highly flexible and can be used to implement several use cases that are not directly related to traditional Leaderboards. Some examples are described below.

Bucketing

Bucketing is the ability to arrange players in to fix-sized pools for competitive purposes. For example, you might want to run weekly tournaments in your game where players compete for score against 5 other random players. This can be implemented in ChilliConnect using a Leaderboard with the Append Update Type and a weekly reset period. Players are first added to the bucket Leaderboard and get a fixed ranking/position. You can then use arithmetic and the GetScores method to return the other players in that bucket. For example, suppose you want to divide players in to buckets of 5 each week. You add a player to the leaderboard and get their ranking back as 12 - you can then work out that the player is in bucket 3 (rankings 11-15) and retrieve the other players in that bucket using GetScores. For this use case, deleting scores is not recommended as it will affect player ranks.

Offline Matchmaking

Leaderboards can also be used for matchmaking or finding other players at a similar skill level for challenge type functionality. Rather than add players to a leaderboard based on an actual score, you can add them to a leaderboard using a value you want to base matchmaking on, for example a skill level. You can then use GetScoresAroundPlayer to find players of a similar skill level. You can also specify the leaderboard with a daily or weekly reset type to ensure that inactive players are not matched against.