Leaderboards

The eSkills Leaderboards serve the purpose of promoting players' engagement by providing feedback on their relative performance.

What are Leaderboards made of?


To each eSkills game correspond multiple leaderboard tables. Each table is defined by a game mode (product), environment (Live or Sandbox) and a Time Frame (described below).

Here we have an example of an eskills game with only one game mode, for which there are 6 leaderboard tables.

GameMode

Environment

Time Frame

1v1

LIVE

TODAY

1v1

LIVE

WEEK

1v1

LIVE

ALL_TIME

1v1

SANDBOX

TODAY

1v1

SANDBOX

WEEK

1v1

SANDBOX

ALL_TIME

📘

It is not necessary for the developer to define a Game Mode.

ESkills maintains a default leaderboard which registers all highscores independent of game mode, hereby referred to as "eSkills default leaderboard".

The "Ins and Outs"


Every time a eSkills game is finished, the results are automatically recorded in a corresponding leaderboard. If such leaderboard does not exist yet, it is created the moment the first score is to be inserted.

At the end of the game, eSkills checks the game's distinctive characteristics (name, environment and game mode) and compares the players' score against any preexisting scores in each time frame. A leaderboard is updated whenever a new score is higher than the current one, stored for that player.

It is possible to retrieve information about the leaderboards by requesting a combination of the game's name identifier, match environment (LIVE or SANDBOX), game mode, time frame (today, week, all-time).

Time frames

  • All-time: refers to the all-time highscores and it's permanent.

  • Week: refers the highscores achieved the current week. Weekly highscore leaderboards are reset every Monday at 00h:00m UTC-0 time-zone.

  • Today: refers to the highscores achieved the current day. Daily highscore leaderboards are reset every day at 00h:00m UTC-0 time-zone.

How highscores are updated

📘

A wallet address is considered a single entity, and highscores are registered solely based on it. If a player chooses to change its username, its highscores are never lost, and all leaderboards pertaining to a game will update to the most recently used username.

Retrieving information about the leaderboards using the Catappult API


There are 2 endpoints that allow the client to retrieve information about the leaderboards, namely players' usernames, their wallet_address, their score and their rank:

  1. Top 'n' Players returns the top 10 to 100 players from a given leaderboard and time frame and their scores.

  2. General Player Statistics returns information from a leaderboard regarding: who are the top 3 players and what are their scores, what is the rank and the score of a given player and what are the adjacent players and their scores.

Using the Top 'n' players endpoint

You can test and see more information about the api here.

Scheme: https
Host: api.eskills.catappult.io
Path: /room/statistics/top_n_players
Query string arguments: package_name, product, match_environment, time_frame, limit.
Example:

https://api.eskills.catappult.io/room/statistics/top_n_players?package_name=com.appcoins.eskills2048.dev&product=1v1&match_environment=LIVE&time_frame=ALL_TIME&limit=10

Query String Arguments details

Parameter

Type

Description

package_name*

String

The package name corresponding to the game.

product

String

The game mode identifier.
If not specified, defaults to eSkills default leaderboard.

match_environment

String

The title of the match environment. It can be either LIVE or SANDBOX. If not specified, defaults to LIVE.

time_frame

String

The title of the time frame. It can be either TODAY, WEEK or ALL_TIME. If not specified, defaults to ALL_TIME.

limit

Integer

The number of ranks to be returned. Can range from "top 10" to "top 100". If not specified, defaults to 1.

* mandatory fields

Using the General Player Statistics endpoint

You can test and see more information about the api here.

Scheme: https
Host: api.eskills.catappult.io
Path: /room/statistics/general_player_stats
Query string arguments: package_name, product, wallet_address, ranks_above_user, ranks_below_user, match_environment, time_frame.
Example:

https://api.eskills.catappult.io/room/statistics/general_player_stats?package_name=com.appcoins.eskills2048.dev&wallet_address=0xcccccccccccccccccccccccccccccccccccccccc&product=1v1&ranks_above_user=1&ranks_below_user=1&match_environment=LIVE&time_frame=ALL_TIME

Query String Arguments details

Parameter

Type

Description

package_name*

String

The package name corresponding to the game.

product

String

The game mode identifier.
If not specified, defaults to eSkills default leaderboard.

wallet_address

String

The wallet address from which we want to obtain information about.

ranks_above_user

Integer

Number of upwards adjacent users to be returned. Ranges from 1 to 10. If not specified, defaults to 1.

ranks_below_user

Integer

Number of downwards adjacent users to be returned. Ranges from 1 to 10. If not specified, defaults to 1.

match_environment

String

The title of the match environment. It can be either LIVE or SANDBOX. If not specified, defaults to LIVE.

time_frame

String

The title of the time frame. It can be either TODAY, WEEK or ALL_TIME. If not specified, defaults to ALL_TIME.

* mandatory fields

📘

Wallet Address is optional!

The required user can be identified either by providing its wallet address, or by making the request while authenticated with the user session token.

An example on how to display the General Player Statistics endpoint response