SCILLLeaderboard

public class SCILLLeaderboard : SCILLThreadSafety

Overview

This component is derived from the SCILLThreadSafety class. It handles all communication with the SCILL backend to load and update personal challenges in real time. It also implements user interfaces.

This class does two things:

The prefabs like userRankingPrefab must have a SCILLLeaderboardRankingItem attached that handles UI for each ranking item.

Sometimes, it’s not easy for the player to find himself in the leaderboard. To solve that, we added support for the users position to be shown in the header of the leaderboard UI (or somewhere else that makes sense for your own game).

An example leaderboard UI

An example leaderboard UI

Use the userRanking inspector property to connect an instance of the userRankingPrefab. The leaderboard will update the values regulary for the individual user and the whole leaderboard.

Usage

This leaderboard implements infinite scrolling via a ScrollRect which should be below the hierarchy of this component. Build this hierarchy as seen in the image at the right side.

Attach the SCILLLeaderboard script to the Leaderboard game object and adjust inspector settings as seen below.

The recommend hierarchy for leaderboards

The recommend hierarchy for leaderboards

First, you need to enter your leaderboard id (you can also set this via script). This leaderboard id can be found in the Admin Panel.

Then adjust the settings for page size and number of top entries as described below.

Next, you need to connect a Unity.UI.Text component to Leaderboard Name so that the name of the leaderboard can be set dynamically from the values you entered when creating the leaderboard in the Admin Panel.

The Rankings Container is a transform that prefabs for rankings will be added to. In this case we chose that Content item from the Scroll View which has a VerticalLayoutGroup to align the items vertically.

User Ranking is connected to the user ranking prefab which has been put in the leaderboard header and which will be updated regulary with the users position in the leaderboard - even if the user is not within the currently loaded rankings.

Last but not least, connect prefabs for the ranking items. These prefabs need to have a SCILLLeaderboardRankingItem attached which will handle updating the UI.

The recommend hierarchy for leaderboards

The recommend hierarchy for leaderboards

Available Prefabs

In the SCILL SDK we already provide ready to be used prefabs of ranking items and a fully functional leaderboard with infinite scrolling feature.

Inspector Properties

leaderboardId

public string leaderboardId;

You need to set a Leaderboard ID. You find the leaderboard ID in the Admin Panel in the Leaderboard list. You can also change this value via script and implement tabs or a leaderboard selection that allows users to display different leaderboards.

Every list in the Admin Panel has this button to copy IDs

Every list in the Admin Panel has this button to copy IDs

Info

You can change the leaderboard id via script everytime, but make sure you call the UpdateLeaderboard method so the data is updated.

numberOfTopEntries

public int numberOfTopEntries = 3;

The leaderboard instantiates the topRankingPrefab for the first couple of items to highlight them. Use this setting to decide how many items are shown highlighted.

memberType

public SCILLMemberType memberType = SCILLMemberType.User;

SCILL Leaderboards are generated automatically for users and teams. To also generate leaderboards for teams you need to set a team_id when sending events. See Events for more info. Use this setting to set if team rankings or user rankings should be displayed.

You need to update the leaderboard with the UpdateLeaderboard method if you change this value via script, which will also reset the pagination state, as team rankings contain much less items than user rankings.

numberOfDecimals

public int numberOfDecimals = 0;

SCILL Events does not support float values (see Why no floats). But some leaderboard scores like lap times are typically stored in a float value to capture also fractions of a second. To support this use case you can convert the float in your game to an integer value capturing the precision you want by multiplying with 100 or 1000.

Sending laptime event
public void SendLapTime()
{
    var metaData = new EventMetaData();
    metaData.score = (int)(lapTime * 100);
    metaData.time_condition = "lap-time";

    SCILLManager.Instance?.SendEventAsync("achieve-score", "group", metaData);
}

Then, set numberOfDecimals to 2 to divide the leaderboard score by 100 before displaying it.

pageSize

public int pageSize = 25;

Defines how many items are loaded and rendered at once. If you have a scrolling UI you should set this value higher, if you use pagination you can set this value to exactly the number of items visible at once.

Allowed values are between 1 and 100.

leaderboardName

public Text leaderboardName;

Connect a UnityEngine.UI.Text component. The text will be set to the name of the leaderboard. This is useful if you want to have multiple leaderboards or if you want to make use of SCILLs multi-language support.

rankingsContainer

public Transform rankingsContainer;

Connect a Transform component. The prefabs for each ranking item will be instantiated into this transform. Make sure you set an auto layout component like VerticalLayoutGroup to that rankingsContainer component so that items get displayed correctly.

userRanking

public SCILLLeaderboardRankingItem userRanking;

Connect a SCILLLeaderboardRankingItem instance from your hierarchy to this setting. It will be updated with the users value in the leaderboard or will be hidden if the user does not have an entry in the leaderboard.

userRankingPrefab

public SCILLLeaderboardRankingItem userRankingPrefab;

Connect a prefab that will be used for the users entry in the leaderboard. It should highlight the user so that he finds himself quickly in the leaderboard.

topRankingPrefab

public SCILLLeaderboardRankingItem topRankingPrefab;

Connect a prefab that will be used for the top entries in the leaderboard. It should be a bit different in style than the defaultRankingPrefab. This prefab will be used for the numberOfTopEntries (see above for a setting).

defaultRankingPrefab

public SCILLLeaderboardRankingItem defaultRankingPrefab;

Connect a prefab that will be used for all entries in the leaderboard except the users and top rankings.

Getters

CurrentPage

public int CurrentPage { get; private set; }

Returns the current page starting a 1.

Methods

UpdateLeaderboard

public void UpdateLeaderboard()

Reset the current leaderboard and load from scratch. This function is used internally in OnEnable to initiate loading the leaderboard. You can also use this function to reset and load the leaderboard if you have changed the leaderboardId via script.