Prepare leaderboard UI - All time leaderboard - (Unity module)

Last updated on June 23, 2025

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

  • 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

  • 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

  • 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

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.

Leaderboards menu Unity Byte Wars all time leaderboard

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.

Leaderboard period widget Unity Byte Wars all time leaderboard

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.

All-time leaderboard menu Unity Byte Wars all time leaderboard

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 the LeaderboardEntry 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.

Leaderboard entry Unity Byte Wars all time leaderboard

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.

  1. 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);
    }

  2. 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);
    }

  3. Then, in the predefined OnEnable() function, add the following code to call DisplayRankingList() when the menu is displayed:

    private void OnEnable()
    {
        DisplayRankingList();
    }

  4. In the Unity Editor, go to Assets/Resources/Modules/LeaderboardEssentials and open the LeaderboardEssentialsAssetConfig.asset file. Make sure to activate the module in starter mode by ticking both the Is Active and Is Starter Active checkboxes.

  5. 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​

Last updated on

On this page