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:

• Load Leaderboard provided by the leaderboard id and update it every 10 seconds.
• Instantiate one of the ranking item prefabs (i.e. userRankingPrefab) property for each LeaderboardRanking object contained in the response and add as child to the rankingsContainer transform.

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).

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.

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.

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.

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.

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.