Prepare leaderboard UI - All time leaderboard - (Unity module)
What's on the Menu
In this tutorial, you will learn how to prepare menus used to display leaderboards. The menus are available in the Resources section and consist of the following files:
LeaderboardsMenu: A C# class that displays buttons to select leaderboard types based on the Byte Wars game modes: Single Player, Elimination, and Team Deathmatch. You will use this class to select which leaderboard to display.
- C# file:
Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardsMenu.cs
- Prefab file:
Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardsMenu.prefab
- C# file:
LeaderboardPeriodMenu: A C# class that displays buttons to select the leaderboard time period.
- C# file:
Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardPeriodMenu.cs
- Prefab file:
Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardPeriodMenu.prefab
- C# file:
LeaderboardAllTimeMenu_Starter: A C# class used to display the all-time leaderboard rankings.
- C# file:
Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardAllTimeMenu_Starter.cs
- Prefab file:
Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardAllTimeMenu_Starter.prefab
- C# file:
LeaderboardEntry: A C# class used to display individual player leaderboard information, such as the player's rank and score.
- C# file:
Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardEntry.cs
- Prefab file:
Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardEntry.prefab
- C# file:
Leaderboards Menu
Below is a preview of the LeaderboardsMenu
prefab. This menu displays buttons to select leaderboard types based on the Byte Wars game modes: Single Player, Elimination, and Team Deathmatch.
The buttons shown above are declared in the LeaderboardsMenu
class:
[SerializeField] private Button singlePlayerButton;
[SerializeField] private Button eliminationButton;
[SerializeField] private Button teamDeathmatchButton;
When any of these buttons are clicked, the following property is set. This property can then be used to determine the selected game mode when sending a request to retrieve leaderboard rankings:
public static InGameMode SelectedGameMode { get; private set; }
Leaderboard Period Menu
Below is a preview of the LeaderboardPeriodMenu
prefab. This menu displays buttons to select the leaderboard time period. There are two types of leaderboard time periods: All-Time and Cycle. In this tutorial, we will implement the All-Time leaderboard period.
When any of the buttons are clicked, the following property is set. This property can then be used to determine the selected period when sending a request to retrieve leaderboard rankings:
public static StatisticCycleType SelectedPeriod { get; private set; }
All-Time Leaderboard Menu
This menu displays individual leaderboard rankings, including the player's display name and score. The individual entries are shown using the LeaderboardEntry
prefab. The list will display only a limited number of leaderboard rankings (e.g., the top 10 players). If the currently logged-in player is not in the top list, their ranking will be shown at the bottom of the menu. Below is a preview of the LeaderboardAllTimeMenu_Starter
prefab.
The components shown above are declared in the LeaderboardAllTimeWidget_Starter
class:
[SerializeField] private LeaderboardEntry leaderboardEntryPrefab;
[SerializeField] private LeaderboardEntry playerLeaderboardEntry;
[SerializeField] private AccelByteWarsWidgetSwitcher widgetSwitcher;
[SerializeField] private Transform leaderboardListPanel;
- The
widgetSwitcher
is a helper component used to switch between menu states: default, loading, and error. - The
leaderboardListPanel
is the container where leaderboard entries will be displayed. - The
leaderboardEntryPrefab
is a reference to theLeaderboardEntry
prefab used to instantiate individual entries. - The
playerLeaderboardEntry
is used to display the current logged-in player's leaderboard rank.
Leaderboard Entry
Below is a preview of the LeaderboardEntry
prefab. It displays an individual leaderboard ranking, including the player's display name, rank, and score.
The components shown above are declared in the LeaderboardEntry
class:
[SerializeField] private TMP_Text rankText;
[SerializeField] private TMP_Text displayNameText;
[SerializeField] private TMP_Text scoreText;
To set the ranking information, the LeaderboardEntry
class provides the following method:
public void SetRankingDetails(string userId, int rank, string displayName, float score)
{
// If the display name is null or empty, set a default format: Player-{first 5 characters of user ID}
displayNameText.text = string.IsNullOrEmpty(displayName) ? $"Player-{userId[..5]}" : displayName;
rankText.text = $"{rank}";
scoreText.text = $"{score}";
}
To reset the displayed information, the LeaderboardEntry
class provides this method:
public void Reset()
{
displayNameText.text = LeaderboardEssentialsModels.UnrankedMessage;
rankText.text = "?";
scoreText.text = "";
}
Ready the UI
In this section, you will prepare the menus mentioned earlier to begin integrating the leaderboard.
Open the
LeaderboardAllTimeMenu_Starter
class and create the function below. You will later use this function to send a request to retrieve leaderboard rankings. For now, add the code below to switch the menu to the loading state:private void DisplayRankingList()
{
widgetSwitcher.SetWidgetState(AccelByteWarsWidgetSwitcher.WidgetState.Loading);
}Next, create the following function to set the leaderboard rank of the currently logged-in player:
private void DisplayPlayerRanking(UserRanking playerRanking)
{
// If the current logged-in player is not ranked, display an empty entry. Otherwise, display the rank.
if (playerRanking == null)
{
playerLeaderboardEntry.Reset();
return;
}
playerLeaderboardEntry.SetRankingDetails(
GameData.CachedPlayerState.PlayerId,
playerRanking.rank,
LeaderboardEssentialsModels.RankedMessage,
playerRanking.point);
}Then, in the predefined
OnEnable()
function, add the following code to callDisplayRankingList()
when the menu is displayed:private void OnEnable()
{
DisplayRankingList();
}In the Unity Editor, go to
Assets/Resources/Modules/LeaderboardEssentials
and open theLeaderboardEssentialsAssetConfig.asset
file. Make sure to activate the module in starter mode by ticking both the Is Active and Is Starter Active checkboxes.Now, play the game in the Editor. You’ll be able to navigate to Main Menu > Leaderboard > All Time, and then see the list menu in the loading state.
Resources
The files used in this tutorial are available in the Unity Byte Wars GitHub repository.
- Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardsMenu.cs
- Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardsMenu.prefab
- Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardPeriodMenu.cs
- Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardPeriodMenu.prefab
- Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardAllTimeMenu_Starter.cs
- Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardAllTimeMenu_Starter.prefab
- Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardEntry.cs
- Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardEntry.prefab