Leaderboards

There are three primary APIs to be aware of:

• Rank
• Score
• Leaderboard

Before working with Rank and Score, first you must create a new Leaderboard.

Leaderboards have the following properties:

/**
 * The database id of this leaderboard.
 * This is assigned automatically when it is added to the DB.
 */ 
string Id

/**
 * The name of the leaderboard.  This must be unique across all
 * leaderboards.
 */ 
string Name

/**
 * The time strategy for the leaderboard. 
 * Current options are ALL_TIME and EPOCHAL.
 * EPOCHAL leaderboards allow for recurring leaderboards that are intended
 * to reset every certain time interval (defined by EpochInverval)
 */
string TimeStrategyType

/**
 * The score strategy for the leaderboard. 
 * Current options are OVERWRITE_IF_GREATER and ACCUMULATE.
 */
string ScoreStrategyType

/**
 * The user-presentable name or title for for the leaderboard.
 */
string Title

/**
 * The units-of measure for the score type of the leaderboard.
 * Can be anything you want! Points, crackers, ducats, you name it!
 */
string ScoreUnits

/**
 * The time at which the leaderboard epoch intervals should begin (in ms).
 * If null, then the leaderboard is all-time and not epochal. 
 * During creation, if this value is provided, then epochInterval must also
 * be provided.
 */
Long FirstEpochTimestamp

/**
 * The duration for a leaderboard epoch interval (in ms). 
 * If null, then the leaderboard is all-time and not epochal. 
 * During creation, if this value is provided, then firstEpochTimestamp
 * must also be provided.
 */
Long EpochInterval

Once you have your Leaderboard defined, use the CreateLeaderboard function in the LeaderboardApi to create it in Elements.

You can also set up and manipulate your leaderboards on the server side from your lua code:

local namazu_leaderboard = require "namazu.elements.dao.leaderboard"
namazu_leaderboard.create_leaderboard(new_leaderboard)

Now that you have a Leaderboard created, you can use the ScoreApi and RankApi to interact with it. The ScoreApi gives you the following function:

/**
 * Creates or updates a score on the specified leaderboard for the 
 * Profile of the player making the request. Returns the Score as it 
 * was written to the DB.
 */ 
Score createOrUpdateScore(String leaderboardNameOrId, Score score);

which you'll want to use whenever someone does something that warrants posting to a Leaderboard, such as being awarded a score for a game. Depending on the ScoreStrategyType of the Leaderboard, this will either add to the entry (ACCUMULATE), or do a comparison and overwrite it if it is greater than the previous entry (OVERWRITE_IF_GREATER).

The RankApi gives the following functions:

/**
 * Given the leaderboard name or id, this will return all Rank instances
 * sorted in order.
 */
Pagination<Rank> getRanksForGlobal(String leaderboardNameOrId, int offset, int count, long leaderboardEpoch);

/**
 * Given the leaderboard name or ID, this will return all Rank instances
 * sorted in order. This allows the the result set to be skipped forward
 * to make the supplied Profile appear in the result set.
 */
Pagination<Rank> getRanksForGlobalRelative(String leaderboardNameOrId, String profileId, int count, long leaderboardEpoch);

/**
 * Given the leaderboard name or id, this will return all Rank instances
 * sorted in order. This allows the the result set to be skipped forward to
 * make the supplied Profile appear int the result set.
 */ 
Pagination<Rank> getRanksForFriends(String leaderboardNameOrId, Profile profileId, int offset, int count, long leaderboardEpoch);

/**
 * Given the leaderboard name or id, this will return all Rank instances 
 * sorted in order. This allows the the result set to be skipped forward
 * to make the Profile for the supplied profile id appear in the result
 * set. Additionally this will filter the results to only include friends
 * of the supplied Profile.
 */
Pagination<Rank> getRanksForFriendsRelative(String leaderboardNameOrId, Profile profileId, int offset, int count, long leaderboardEpoch);