Adobe AIR & GameCircle: Enabling Leaderboards

Introduction

Once you’ve set up your project with the GameCircle AIR ANE, you’re ready to add leaderboards to your game.

Leaderboards are created in the Mobile Apps GameCircle Developer Console. Then, once you’ve initialized Amazon GameCircle in your game, you can call the GameCircle APIs to interact with your published leaderboards. This page covers using the GameCircle APIs to:

  • Get leaderboard IDs for your game
  • Add a link to the leaderboards overlay
  • Send scores to a leaderboard
  • Get the local player’s score
  • Get high scores & percentiles from a leaderboard
  • Change the toast popup location

Create and Publish Leaderboards

Use the GameCircle Developer Console to create and publish leaderboards for your game. To use the Developer Console, you need to create an Amazon developer account. This is a quick sign-in process; you can use your Amazon retail account or set up a new account for the Developer Console.

Once in the Developer Console, go to the Apps & Services > GameCircle tab and create a configuration for your game. The configuration workflow includes setting up and publishing leaderboards. See Creating a GameCircle Configuration for more help, including setting up leaderboards and achievements.

You can create up to 100 leaderboards for each configuration you set up in the Developer Console. For more details on designing and implementing leaderboards, see Create Leaderboard Assets.

Get Leaderboards for Your Game

Get a list of leaderboard IDs for your game using loadLeaderboards(). In response, one of the following events is fired:

  • LoadLeaderboardsCompleted.LEADERBOARDS_LOADED
  • LoadLeaderboardsCompleted.LOAD_LEADERBOARDS_FAILED

Example:

GameCircle.gameCircle.loadLeaderboards().addLoadLeaderboardsListener(
  function(loadLeaderboardsCompleted:LoadLeaderboardsCompleted):void  {
    trace(loadLeaderboardsCompleted.toString());
    var leaderboards:Vector.<GameCircleLeaderboard>=loadLeaderboardsCompleted.leaderboards;
  });

The event LEADERBOARDS_LOADED contains the leaderboard definitions, including IDs, in an array.

Your players can view your GameCircle leaderboards in an in-game overlay. You need to add a link to it somewhere in your game where players can easily find it. Use the method showLeaderboards() to display the standard leaderboard overlay.

Example:

// show the leaderboards overlay   
GameCircle.gameCircle.showLeaderboards();

You can also display one particular leaderboard using showLeaderboard() and specifying a leaderboard ID.

Example:

// show overlay for the leaderboard with ID  "leaderboard01"   
GameCircle.gameCircle.showLeaderboard("leaderboard01");

Send Scores to a Leaderboard

Submit scores to GameCircle using the submitScore() method. In response, one of the following events is fired:

  • SubmitScoreCompleted.SCORE_SUBMITTED
  • SubmitScoreCompleted.SUBMIT_SCORE_FAILED

Example:

// submit a score of 100 to the leaderboard with id  "leaderboard01"
GameCircle.gameCircle.submitScore("leaderboard01", 100).addSubmitScoreListener(
  function(submitScoreCompleted:SubmitScoreCompleted):void  {
    trace("Submit  score completed: " + submitScoreCompleted.toString());
});

Get Local Player’s Score

Retrieve the local player’s current score and ranking on a leaderboard using the method loadLocalPlayerScore(). This method takes the leaderboard ID and one of the following filter names. For more information on time filters, see How do time filters work?.

  • GameCircleLeaderboardFilter.GLOBAL_ALL_TIME
  • GameCircleLeaderboardFilter.GLOBAL_DAY
  • GameCircleLeaderboardFilter.GLOBAL_WEEK

In response calling this method, one of the following events is fired:

  • LoadLocalPlayerScoreCompleted.LOCAL_PLAYER_SCORE_LOADED
  • LoadLocalPlayerScoreCompleted.LOAD_LOCAL_PLAYER_SCORE_FAILED

The event LOCAL_PLAYER_SCORE_LOADED contains two values: score and rank.

Example:

// load player's score for leaderboard01, global all-time
GameCircle.gameCircle.loadLocalPlayerScore("leaderboard01",  GameCircleLeaderboardFilter.GLOBAL_ALL_TIME).addLocalPlayerScoreListener(
  function(loadLocalPlayerScoreCompleted:LoadLocalPlayerScoreCompleted):void  {
    trace(loadLocalPlayerScoreCompleted.toString());
});

Get Leaderboard High Scores & Percentiles

Retrieve your game’s high score and percentile data as a table with the methods loadScores() and loadPercentiles().These methods can be useful when creating your own custom leaderboards outside of the Amazon Developer Console. These methods take the leaderboard ID and one of the following filter names. For more information on time filters, see How do time filters work?.

  • GameCircleLeaderboardFilter.GLOBAL_ALL_TIME
  • GameCircleLeaderboardFilter.GLOBAL_DAY
  • GameCircleLeaderboardFilter.GLOBAL_WEEK

For loadScores(), one of the following events is fired:

  • LoadScoresCompleted.SCORES_LOADED
  • LoadScoresCompleted.LOAD_SCORES_FAILED

The event SCORES_LOADED contains an array of GameCircleScore objects. Each object contains the following score-related properties: player, rank, score string, and score value.

Example:

// load high scores for leaderboard01, global all-time
GameCircle.gameCircle.loadScores("leaderboard01",  GameCircleLeaderboardFilter.GLOBAL_ALL_TIME).addLoadScoresListener(
  function(loadScoresCompleted:LoadScoresCompleted):void  {
    trace(loadScoresCompleted.toString());
});

For loadPercentiles(),one of the following events is fired:

  • LoadPercentilesCompleted.PERCENTILES_LOADED
  • LoadPercentilesCompleted.LOAD_PERCENTILES_FAILED

The event PERCENTILES_LOADED contains an array of GameCirclePercentile objects. Each object contains the following properties: player, score, and percentile.

Example:

// load percentiles for leaderboard01, global all-time
GameCircle.gameCircle.loadPercentiles("leaderboard01",  GameCircleLeaderboardFilter.GLOBAL_ALL_TIME).addLoadPercentilesListener(
  function(loadPercentilesCompleted:LoadPercentilesCompleted):void  {
    trace(loadPercentilesCompleted.toString());
});

Change Toast Popup Location

Control the placement of leaderboard and achievement toasts in your game using the method setPopupLocation(). This method lets you change the popup’s location on the screen by specifying one of the following values:

  • BOTTOM_CENTER
  • TOP_CENTER

Example:

// show toast popups on the top right
GameCircle.gameCircle.setPopupLocation(GameCirclePopupLocation.TOP_CENTER);