< Back to Manuals

Leaderboards

Leaderboards are a system which rank players based upon their scores.

Playlyfe provides realtime leaderboards which are automatically updated as and when there is any player activity. No extra calls are required to update leaderboards.

Use Cases

At Playlyfe, we love leaderboards. It's a great way of getting a social element into the game, and driving competetive behaviour. Our detailed leaderboards can also provide insight on player activity and let players know how they can improve their performance.

Leaderboards fit well in almost all scenarios, but lets just take an example of a sales and marketing team. If you want to track the overall performance of a sales executive, the various metrics that you might be interested are the total revenue generated, sales calls made, number of new clients, etc. You can have different leaderboards tracking each of these metrics, but Playlyfe can also let you make a leaderboard track a compound metric that depends on these metrics. This gives a better overall pricture. The leaderboards can also be extended to teams, where teams compete against each other and take things to another level.

Base Metric

Leaderboards are set to calculate rankings on a preset Base Metric. Players with a higher score on the base metric will have a higher rank. The base metric can be a point or a compound metric.

Team Leaderboards

You can have leaderboards on teams too. To create a team leaderboard, set the This Leaderboard is for field to Teams (this corresponds to the entity_type key in the design). In team leaderboards, a team's score is updated when any of its members score points. Only the scores which a member earns after joining the team are counted.

A team's score on the leaderboard is not the sum of all the scores of its members.

Leaderboard Cycles

With cycles, leaderboards can be reset at regular intervals which lets you find the top performers in a cycle.

Leaderboard Scopes

The scope of a leaderboard defines who all will be tracked on the leaderboard. If the scope type is team_definition or team_instance, then an additional scope.id field is required which tells which team definition you want the leaderboard for.

For player leaderboards, there can be 4 scopes:

  1. Game: Leaderboard is game-wide.
  2. Across All Teams of Type(team_definition): Leaderboard is across all instances of a team definition.
  3. Within Each Team of Type(team_instance): Leaderboard is restricted to each instance of a team definition.
  4. Custom: Leaderboard is free-form. You can decide what contributions you want to count on the leaderboard.

For team leaderboards, there can be only 3 scopes:

  1. Game: Leaderboard is game-wide.
  2. Across All Teams of Type(Team Definition): Leaderboard is across all instances of a team definition.
  3. Custom: Leaderboard is free-form. You can decide what contributions you want to count on the leaderboard.

Custom Scoped Leaderboards

Regular leaderboards track a player or team's metric, regardless of how they are accumulated. While this is enough in most use cases, there are some scenarios where you'd desire something more flexible. Say, you want a leaderboard which is updated only when certain activities are performed, then you can use our Custom leaderboards. Lets try understanding it better with an example.

If your application has many sub-challenges, like courses on a learning platform, you might want to have leaderboards within each course. Now each course has challenges that you mapped to Playlyfe's Actions and the player is awarded some points on its completion. With normal leaderboards, points scored from all courses would be included, which is fine for overall leaderboards but not for course-level leaderboards. So, to get course- level leaderboards, all we need to do is pass a scope when performing the action. This scope can be the course ID for instance which would automatically create a leaderboard that will track score changes only when actions are performed or rules executed with that scope. You can pass scopes when triggering actions or executing custom rules.

One Custom leaderboard can be used to track a lot of separate scopes, each having a unique identifier.

With this example, hope you got a better picture of what custom scoped leaderboards can do. Feel free to discuss them over at our forums.

Detailed Leaderboards

With detailed leaderboards, we can look into every player's activity and get details of how the players earned their score. This can be useful for players in figuring out their strengths and weeknesses in comparison to others.

Detailed leaderboards are only available for player leaderboards

Merged Leaderboards

Playlyfe offers a Merged Leaderboard feature, which allows you to visualize data across multiple leaderboards by merging them into a single leaderboard. To merge leaderboards, all you have to do is pass the merge_with query parameter while reading a leaderboard. The query string needs to be a comma-separated string in the following format:

[leaderboard_definition_id]{/[scope]}|[cycle]|{[timestamp]}

Here the leaderboard_definition_id is the ID of the leaderboard's definition. If the leaderboard is a custom scoped leaderboard, you need to pass its scope separated by a /. You then need to specify the leaderboard cycle (one of alltime, yearly, monthly, weekly or daily).

In case of cycles other than alltime, a timestamp is required to find out exactly which cycle is to be merged. As indicated in the above format, the leaderboard definition ID, cycle and timestamp information need to be separated by a pipe |.

The ranking of the leaderboard will still be done based on the original leaderboard. You can pretty much merge any leaderboard, only limitation is that the leaderboards being merged need to have the same entity type.

Design Structure

Base Structure

Name Description
id A unique ID for the leaderboard.
name A name for the leaderboard.
description Brief description of the leaderboard.
metric

The metric on which this leaderboard is based upon. This is an object with two fields:

  • type: the type of the metric (either point or compound)
  • id: The ID of the metric
scope

The scope on which this leaderboard operates.

The scope is decided by the type property in this object. The four supported scope types are:

  1. game: Leaderboard is game-wide.
  2. team_definition: Leaderboard is across all instances of a team definition.
  3. team_instance: Leaderboard is restricted to each instance of a team definition.
  4. custom: Leaderboard is free-form. You can decide what contributions you want to count on the leaderboard.

If the scope type is one of team_definition or team_instance, then an additional id field is required within the scope object.

  • For type: team_definition: The id field will be the team definition this leaderboard will apply to.
  • For type: team_instance: The id field will be the team definition whose instances this leaderboard will be restricted to.
type The ranking type of the leaderboard. Only regular for now.
entity_type

The type of leaderboard whether its for players or teams.

Player leaderboards can be on all four scopes, where as the Team leaderboards are possible only with game and team_definition scopes.

cycles Leaderboard cycles are the interval in which the leaderboard is reset. Your leaderboard design can have more than one cycles. There are 5 possible cycles:
  1. alltime: Leaderboards are never reset.
  2. yearly: The current leaderboard is reset at the start of every year.
  3. monthly: The current leaderboard is reset at the start of every month.
  4. weekly: The current leaderboard is reset on every Sunday.
  5. daily: The current leaderboard is reset at midnight GMT.
When you are finally reading the leaderboard (in your game), you'd pass only one of the selected cycles in your request.
requires

The visibility requirements for the leaderboard. Only the players who satisfy the requirements can view the leaderboard.

Click here to see the visibility requirement structure.
tags Array of strings which can be used when querying to get all designs based on certain tags specified

Visibility Requirements Structure

This allows certain checks to be performed to make sure a player can actually see/perform/join the task, action, team.

Field Description
type The type of condition. It can be one of metric, action, team, and, or.
not If true, inverts the condition. So any check which would usually evaluate to true will now evaluate to false.
expression An array of contexts joined with an AND or OR operator. This field is only applicable if the condition type is and or or, and replaces the context field.
context The actual comparison expression. The structure changes depending on the type of condition selected. The structure for each condition is defined below:
  • metric - Metric Based Condition
  • action - Action Based Condition
  • team - Team Based Condition
The and and or type of conditions do not have this field. Instead, they have the expressions field, which is an array of these contexts.

Metric Based Condition

Condition which depends on a player's score for a particular metric

Field Description
id ID of the metric.
type Type of the metric being used for comparison.
For set metrics, there is an additional item field which denotes the set item
item The set item whose value will be compared.
This field is only available if the metric type is set.
operator Can be one of the relational operators:
  • eq (equal to),
  • ne (not equal to),
  • gt (greater than),
  • ge (greater than or equal to),
  • lt (less than),
  • le (less than or equal to)
value The value of the metric that the player should have on his scores.

Example:

{ "requires": { "type": "metric", "not": false, "context": { "id": "exp", "type": "point", "operator": "eq", "value": "55" } } }

Action Based Condition

Condition which depends on how many times an action has been performed.

Field Description
id ID of the action.
operator Can be one of the relational operators: eq, ne, gt, ge, lt, le.
value The number of times the action should be executed by the player.

Example:

{ "requires": { "type": "action", "context": { "id": "login", "operator": "eq", "value": "15" } } }

Team Based Condition

Condition which depends on how many times an action has been performed.

Field Description
definition_id Definition ID of the team which the player should be a part of.
role The role the player should have within the team of this type. If you don't care about the role, then you can ignore this field.

Example:

{ "requires": { "type": "team", "not": false, "context": { "definition_id": "disciples", "role": "student" // optional if the player can have any role } } }

All Conditions: and

An and condition, which is shown as All of the following rules can be used to join two or more conditions such that the whole condition will be true only when all of the child conditions are true.

Example:

{ "requires": { "type": "and", "expression": [ // two or more conditions ] } }

Any Condition: or

An or condition, which is shown as Any of the following rules can be used to join two or more conditions such that the whole condition will be true even if only one of the child conditions become true.

Example:

{ "requires": { "type": "or", "expression": [ // two or more conditions ] } }

Examples

Game Scope Leaderboard

{ "name": "Game Leaders", "id": "game_leaders", "type": "regular", "description": "This leaderboard will display top players within the game", "entity_type": "players", "scope": { "type": "game" }, "metric": { "id": "knowledge", "type": "knowledge" } }

Team Instance Scope Leaderboard

{ "name": "Team Leaders", "id": "team_leaders", "type": "regular", "entity_type": "players", "description": "This leaderboard will display top players within the team", "scope": { "type": "team_instance", "id": "regional" }, "metric": { "id": "knowledge", "type": "knowledge" } }