Leaderboards

Leaderboards are typically restricted to tracking and reporting the leading players in a game. GameSparks Leaderboards offer you a much wider and flexible scope, both for tracking comparisons within your player pool and for controlling how comparisons are displayed in-game to the players:

• Highly Configurable - Keep track of any comparisons of player performance and then support artifacts in-game that flexibly display this information in a meaningful way to players. This supports complex, contextual displays of information about other players and also provides the framework for many social and competitive features.
• Highly Performant - Our internal ranking and sorting algorithms allow new scores to be added to Leaderboards with 10m+ entries and have a new rank calculated within milliseconds.
• Driven by Running Totals - Leaderboards consume data from Running Totals and can also perform calculations on grouped Running Totals, allowing you to further transform the data from the Running Total into a list of scores of the values that you want. A single Leaderboard can consume data from multiple Running Totals (and in turn, from multiple Events). This allows for some complex Leaderboards, such as a Leaderboard with a halfway score and a final score in the same list. You can achieve this without having to worry about recording the halfway score during the game. Simply send the Events when they happen and the platform does the rest!
  • For more details on Running Totals, see here.
• Partition - You can partition Leaderboards, which allows you to set up a single Leaderboard configuration and have it automatically create new Leaderboards when a particular value changes. A good example here is a level Leaderboard, where the rules are the same for the Leaderboard at each level. You tell the Leaderboard to partition by level and the rest is done for you. Far better than creating 100 separate Leaderboard configurations to represent each level!
  • For how to partition Leaderboards, see this tutorial.
• Social Ranking - Not only can Leaderboards provide instant rankings, but we can filter these based on your connection to a wide range of available social networks, such as ranking you against your socially networked friends.

Best Practices To make sure your game performs and scales well, see GameSparks Best Practices, Leaderboards.

FAQs? You can review Frequently Asked Questions about working with Leaderboards.

Managing Leaderboard Configurations

The Configurator Leaderboards page displays the list of Leaderboards and allows you to create new Leaderboards and edit or delete existing ones:

You can use the following options (highlighted above):

• Add - Add a new Leaderboard.
• - Edit Leaderboard.
• - Delete Leaderboard.

Creating a Leaderboard Configuration

Click Add to create a new Leaderboard.

• Short Code - The Short Code is a mandatory field used to give the Leaderboard a unique identifier for use elsewhere in the Portal and in Cloud Code.
• Name - The Name field is a mandatory field used as an identifier to help you find the Leaderboard in the Portal.
• Description - The Description is a mandatory field, which you can use to describe the purpose of the Leaderboard.
• Team - The type of Leaderboard to be created. Leaderboards can be Team or Player based - if a Team is not selected, then the Leaderboard is a Player Leaderboard.
• Update Frequency - Select the rate at which the GameSparks platform will update the Leaderboard data:
  • Real-time - Updated in real-time (default).
  • Daily - Updated every day.
  • Weekly - Updated every week.
  • Monthly - Updated every month.
• Reset Frequency - Select how often you want to reset the Leaderboard:
  • Never - Never Reset (default).
  • Daily - Reset every day.
  • Weekly - Reset every week.
  • Monthly - Reset every month.
• Property Set - Select the Property Set which you want to attach to the Leaderboard - the Property Set will be surfaced and made available wherever you use the Leaderboard.
  • For more details on attaching Property Sets to Leaderboards, see here.
• High Score Notifications - A flag to indicate whether a NewHighScoreMessage should be sent to the user when they submit a new high score.
• Social Notifications - A flag to indicate whether a SocialRankChangedMessage should be sent to friends when their scores are beaten.
• Top N Notifications - Whether a GlobalRankChangedMessage should be sent to players when their scores are beaten (if they are within the Top N Threshold).

• Top N Threshold - Which global positions in the Leaderboard should be notified when they are beaten.

  Resetting a Leaderboard does not restart it at zero! When a Leaderboard is reset, say Daily, it simply means that the Leaderboard entries are cleared out at the end of each day. However, the underlying Running Total data is not reset to start from zero. So if a player scored a high score of 50 on Day 1, that player would have to post a score of greater than 50 on Day 2 to register a new high score. If you want to restart your Leaderboards at zero, you'll need to partition the Leaderboard. See Starting Leaderboards at Zero

Creating Leaderboard Fields

To complete a Leaderboard configuration, you can add Fields. Each Field refers to a Running Total Collector.

Selecting Running Totals? When you start to add fields for your Leaderboard's Running Total Collectors, you can select from two kinds of Running Total - (i) Event/Attributes you've created and which qualify as System Generated Running Totals or (ii) custom User Configured Running Totals that you've configured for a Leaderboard's specific purpose. For simple ranking Leaderboards, you can use a System Generated Running Total that uses the appropriate aggregation type. For more complex Leaderboards, such as one that tracks the most improved player at a specific game level or most improved player over the last month, a custom User Configured Running Total will be required. For more information, see Running Totals.

In the Fields panel, click to Add fields to a Leaderboard:

• Running Total - Select from your list of Running Totals:
  • The drop-down list is divided into System Running Totals and Configured Running Totals. In this example, we've chosen the Player Score Configured Running Total.
• Collector - Select from a list of Running Total Collectors that are defined for the chosen Running Total:
  • Remember that if you select a Configured Running Total, the Calculation Type you selected for the Running Total's Collector will be used to aggregate data for the Leaderboard, not the original Default Aggregation Type selected for the Event/Attribute on which the Running Total is based.
  • In this example, we can see from the suffix given to the Collector - MAX.Score.all - that:
    • MAX - the aggregation method is for the Maximum score.
    • all - there is no filtering set so all data values will be used.
• Filter Type - Select a filter which incoming Event Attribute values will be checked against before being entered into the Leaderboard.
• Filter Value - Specify a value for the given filter type.
• Sort - Select how this field affects the ordering of the Leaderboard if at all.
• Group - This field is enabled if:
  • The Event/Attribute you have selected as the Running Total Collector has its Default Aggregation Type set as Grouped, OR
  • Any other Running Total Attribute on the Event has its Default Aggregation Type set as Grouped. Even though the Event's Grouped Attribute is not selected as the Leaderboard's Running Total Collector, you can select how the actual Running Total Collector will be grouped, just in case you do decide to return that Grouped Attribute into the Leaderboard and so prevent duplication of the Running Total Attribute values on the Leaderboard.
  • If enabled, this field allows you to select how the Leaderboard data should be grouped. Available values are:
    • Minimum - Lowest entry.
    • Maximum - Highest entry.
    • Sum - Sum of the entries.
    • Count - Number of entries.
    • Range - Difference between Minimum and Maximum.
    • ID - Lists each Entry on a single Leaderboard.
    • Partition - Partitions the Leaderboard on this Entry, more on that here.

Deleting Leaderboard Fields

You can click the delete icon to remove a Field from your Leaderboard.

Updating a Leaderboard Configuration

You can click the edit icon to update a Leaderboard configuration.

IMPORTANT - Leaderboard entries will be lost! If the Leaderboard has had entries posted to it, these entries will be lost when you save your editing changes and update the Leaderboard's configuration.