Leaderboards

Elements facilitates the creation of Leaderboards that can track user rankings and scores.

There are three primary APIs to be aware of:

• Rank

• Score

• Leaderboard

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

Leaderboard Properties

Leaderboards have the following properties:

• id: The database id of this leaderboard. This is assigned automatically when it is added to the DB.

• Name: The name of the leaderboard as a string. This must be unique across all leaderboards.

• TimeStrategyType: The time strategy for the leaderboard. Current options are ALL_TIME and EPOCHAL. EPOCHAL leaderboards allow for recurring leaderboards that are intended to repeatedly reset after a certain time interval (defined by EpochInverval).

• ScoreStrategyType: The score strategy for the leaderboard. Current options are OVERWRITE_IF_GREATER and ACCUMULATE.

• Title: The user-presentable name or title for for the leaderboard as a string.

• ScoreUnits: The units-of measure for the score type of the leaderboard as a string. This can be anything you want, such as points, crackers, ducats - you name it!

• FirstEpochTimestamp: The time at which the leaderboard epoch intervals should begin (in ms). If null, then the leaderboard is all-time and not epochal.

• EpochInterval: The duration for a leaderboard epoch interval (in ms). If null, then the leaderboard is all-time and not epochal. If this value is provided during creation of the Leaderboard, then firstEpochTimestamp must also be provided.

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, which creates or updates a score on the specified leaderboard for the Profile of the player making the request and returns the Score as it was written to the DB.

Score createOrUpdateScore(String leaderboardNameOrId, Score score);

You'll want to update the leaderboard score 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 compare and overwrite it if it is greater than the previous entry (OVERWRITE_IF_GREATER).

The RankApi provides the following functions:

Given the leaderboard name or id, this function 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 function 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 function will return all Rank instances for friends of the User 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> getRanksForFriends(String leaderboardNameOrId, Profile profileId, int offset, int count, long leaderboardEpoch);

Given the leaderboard name or id, this will return all Rank instances for friends of the user 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);