Leaderboards

The Leaderboards module allows you to interact with game leaderboards; this includes retrieving scores, posting new scores, and ensuring leaderboards are supported by the specific arena.

Arkadium.com and arenas within the Arkadium network display Leaderboards, which allow players to track their in-game performance against that of their peers. These scores are displayed from highest to lowest along with the player's avatar, username, and country of origin.

Typically, Leaderboards are displayed via a tab on the side navigation, or in some cases below the game near the How To Play text. They are subdivided into four sections: Daily, Weekly, Monthly, and All Time. Each of the Leaderboard types, with the exception of All Time, resets at a discrete time rather than being a rolling list of the past X hours or days. For example, the Monthly leaderboard resets on the first of each month.

Scores are submitted to the Leaderboard automatically and should not require player input for submission. However, a player must be registered or subscribed before their scores are submitted, as the Leaderboards do not support anonymous data.

Supporting Leaderboards is not a requirement and should be considered on a case-by-case basis. For example, Leaderboards might be a great fit for a game with a Daily Challenge mode, but less relevant for games with lengthy level progression.

Players can check the leaderboards in the context of a game

Setup

To utilize the Leaderboard module, initialize the SDK and access the leaderboard component:

import * as ArkadiumApi from '@arkadiuminc/sdk';

const sdk = await ArkadiumApi.getInstance();

sdk.leaderboard;

Usage

Leaderboard types

There are 4 types of leaderboards exposed by sdk.leaderboard.type:

{
    Day = "day",
    Week = "week",
    Month = "month",
    All = "all",
}

Some Leaderboards APIs accept these types as an optional argument.

Check if leaderboard service is supported by the Arena

const isSupported = await sdk.leaderboard.isSupported();

Get user's score

const userScore: number = await sdk.leaderboard.getUserScore();

// optionally a leaderboard type (default is instance.leaderboard.type.All) can be passed to fetch the corresponding score on that leaderboard
// example usage fetching the user score for the weekly leaderboard
const userScore: number = await sdk.leaderboard.getUserScore(instance.leaderboard.type.Week);

Get top scores

const topScores = await sdk.leaderboard.getTopScores();

// optionally a leaderboard type (default is instance.leaderboard.type.All) and a limit (default is 100) can be passed to fetch the corresponding top scores on that leaderboard up to the limit
// example usage fetching the 20 top scores for the monthly leaderboard
const topScores = await sdk.leaderboard.getTopScores(instance.leaderboard.type.Month, 20);

// example iteration of topScores
topScores.forEach((entry) => console.log(`Entry: rank: ${entry.rank}, score: ${entry.score}, username: ${entry.username}, avatar: ${entry.avatar}`));

The result of calling getTopScores will be a list of entries of the following type:

type LeaderboardEntry = {
    rank: number;
    score: number;
    username: string;
    avatar: string;
}

Post a new score

await leaderboard.postScore(1000);