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.

📘

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

* 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

* 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