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

Last updated on March 12, 2025

What's on the menu​

In this tutorial, you will learn how to prepare the leaderboard user interface (UI) to display the leaderboard as a ranking list using the AccelByte Gaming Services (AGS) Leaderboard service.

The Leaderboard Menu UI has been created for you, but they still need additional code before you can connect them with the AGS Game SDK. These prepared files are available in the Resources section and consist of the following:

  • LeaderboardSelectionMenuCanvas_Starter: A UI menu that displays all available leaderboard lists.
    • CS file: /Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardSelectionMenu_Starter.cs
    • Prefab file: /Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardSelectionMenuCanvas_Starter.prefab
  • LeaderboardCycleMenuCanvas_Starter: A UI menu that displays all available leaderboard cycle options.
    • CS file: /Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardCycleMenu_Starter.cs
    • Prefab file: /Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardCycleMenuCanvas_Starter.prefab
  • LeaderboardMenuCanvas_Starter: A UI menu that displays the ranking list of the chosen leaderboard.
    • CS file: /Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/LeaderboardMenu_Starter.cs
    • Prefab file: /Assets/Resources/Modules/LeaderboardEssentials/Prefabs/LeaderboardMenuCanvas_Starter.prefab
  • RankingEntryPanel: A UI component to hold the ranking information.
    • CS file: /Assets/Resources/Modules/LeaderboardEssentials/Scripts/UI/Components/RankingEntryPanel.cs
    • Prefab file: /Assets/Resources/Modules/LeaderboardEssentials/Prefabs/Components/RankingEntryPanel.prefab
  • LeaderboardItemButton: A UI component that is used for the leaderboard options button.
    • Prefab file: /Assets/Resources/Modules/LeaderboardEssentials/Prefabs/Components/LeaderboardItemButton.prefab

Leaderboard Selection Menu​

The Leaderboard Menu displays the leaderboard list based on the query result from the AGS Leaderboard server in the form of buttons using the LeaderboardItemButton prefab. This menu is accessible from the Main Menu and its menu button is already exposed in MainMenuCanvas.prefab.

The following is already included in LeaderboardSelectionMenu_Starter.cs:

  • The declarations of the UI references that are ready to use:

    [SerializeField] private Transform leaderboardListPanel;
    [SerializeField] private Transform noEntryPanel;
    [SerializeField] private Transform loadingPanel;
    [SerializeField] private Transform failedPanel;

    [SerializeField] private Button backButton;
    [SerializeField] private GameObject leaderboardItemButtonPrefab;

  • The getter/setter to switch the menu states. The states are: default, loading, and failed.

    private LeaderboardSelectionView CurrentView
    {
        get => currentView;
        set
        {
            leaderboardListPanel.gameObject.SetActive(value == LeaderboardSelectionView.Default);
            noEntryPanel.gameObject.SetActive(value == LeaderboardSelectionView.Empty);
            loadingPanel.gameObject.SetActive(value == LeaderboardSelectionView.Loading);
            failedPanel.gameObject.SetActive(value == LeaderboardSelectionView.Failed);
            currentView = value;
        }
    }

  • The function named OnBackButtonClicked() that listens to the backButton onClick event and redirects the player to the previous menu with the MenuManager:

    private void OnBackButtonClicked()
    {
        MenuManager.Instance.OnBackPressed();
    }

Here's the preview of the Leaderboard Selection Menu:

leaderboard-selection-menu-preview Unity Byte Wars all time leaderboard

Leaderboard Cycle Menu​

A leaderboard can span over different cycles, e.g., All Time or Weekly. The Leaderboard Cycle Menu displays all cycle types available for the leaderboard as a button using the LeaderboardItemButton prefab, which will then direct to the actual leaderboard. In this module, you will only use the All Time type for a basic implementation.

The following are already included in LeaderboardCycleMenu_Starter.cs:

  • The declarations of the UI references that are ready to use:

    [SerializeField] private Button allTimeButton;
    [SerializeField] private Button backButton;

    [SerializeField] private Transform leaderboardListPanel;
    [SerializeField] private Transform loadingPanel;
    [SerializeField] private Transform loadingFailed;

    [SerializeField] private GameObject leaderboardItemButtonPrefab;

  • The getter/setter to switch the menu states. The states are: default loading, and failed.

    public LeaderboardCycleView CurrentView
    {
        get => currentView;
        set
        {
            leaderboardListPanel.gameObject.SetActive(value == LeaderboardCycleView.Default);
            loadingPanel.gameObject.SetActive(value == LeaderboardCycleView.Loading);
            loadingFailed.gameObject.SetActive(value == LeaderboardCycleView.Failed);
            currentView = value;
        }
    }

  • The function named OnBackButtonClicked() that listens to the backButton onClick event and redirects the player to the previous menu with MenuManager:

    private void OnBackButtonClicked()
    {
        MenuManager.Instance.OnBackPressed();
    }

Here's the preview of the Leaderboard Cycle Menu:

leaderboard-cycle-menu-preview Unity Byte Wars all time leaderboard

Leaderboard Menu​

The Leaderboard Menu displays the ranking list of the desired leaderboard queried from AGS. It also displays the current player ranking in the leaderboard if the user is not listed in top 10 players. Each ranking info displayed uses the RankingEntryPanel prefab that contains the player name and their highest score in the leaderboard.

The following are already included in LeaderboardMenu_Starter.cs:

  • The declarations of the UI references that are ready to use:

    [SerializeField] private Transform rankingListPanel;
    [SerializeField] private Button backButton;
    [SerializeField] private GameObject rankingEntryPanelPrefab;
    [SerializeField] private RankingEntryPanel userRankingPanel;

    [SerializeField] private Transform resultPanel;
    [SerializeField] private Transform emptyPanel;
    [SerializeField] private Transform loadingPanel;
    [SerializeField] private Transform loadingFailed;

  • The getter/setter to switch the menu states. The states are: default, loading, empty, and failed.

    public LeaderboardMenuView CurrentView
    {
        get => currentView;
        set
        {
            resultPanel.gameObject.SetActive(value == LeaderboardMenuView.Default);
            emptyPanel.gameObject.SetActive(value == LeaderboardMenuView.Empty);
            loadingPanel.gameObject.SetActive(value == LeaderboardMenuView.Loading);
            loadingFailed.gameObject.SetActive(value == LeaderboardMenuView.Failed);
            currentView = value;
        }
    }

  • The function named OnBackButtonClicked() that listens to the backButton onClick event and redirects the player to the previous menu with MenuManager:

    private void OnBackButtonClicked()
    {
        MenuManager.Instance.OnBackPressed();
    }

Here's the preview of the Leaderboard Menu:

leaderboard-menu-preview Unity Byte Wars all time leaderboard

Ranking Entry Panel​

The Ranking Entry Panel is a prepared script for handling the Ranking Entry UI. This panel displays the player ranking information such as the rank number, display name, and rank score of a specific user. This prefab is mainly used for displaying all the rankings of the leaderboard and the current user ranking for that leaderboard.

The following are already included in RankingEntryPanel.cs:

  • The declarations for the UI references that are ready to use:

    [SerializeField] private Image prefabImage;
    [SerializeField] private TMP_Text playerRankText;
    [SerializeField] private TMP_Text playerNameText;
    [SerializeField] private TMP_Text playerScoreText;

  • A constant variable to hold the default prefix for the player's display name:

    private const string DefaultDisplayNamePrefix = "PLAYER-";

  • A function to reset the all the UI text:

    public void ResetRankingEntry()
    {
        playerRankText.text = "";
        playerNameText.text = "You Have No Ranking Yet";
        playerScoreText.text = "0";
    }

  • A function to modify all the text values within the entry panel:

    public void SetRankingDetails(string userId, int playerRank, string playerName, float playerScore)
    {
        // If display name is null or empty, set to default format: "PLAYER-<<5 char of userId>>"
        if (string.IsNullOrEmpty(playerName)) playerName = $"{DefaultDisplayNamePrefix}{userId[..5]}";
        
        playerRankText.text = $"#{playerRank}";
        playerNameText.text = playerName;
        playerScoreText.text = $"{playerScore}";
    }

  • A function to modify the entry panel's color:

    public void SetPanelColor(Color color)
    {
        prefabImage.color = color;
    }

Here's the preview of the Ranking Entry panel:

ranking-entry-panel-preview Unity Byte Wars all time leaderboard

Ready the UI​

In this section, you are going to prepare the UI for the AGS Game SDK Leaderboard integration.

Leaderboard Selection Menu UI​

  1. Open LeaderboardSelectionMenu_Starter.cs.

  2. Define a public static variable to store the chosen leaderboard code. Each leaderboard has its own leaderboard code, so this leaderboard code will be required for getting the rank list from other menu.

    public static string chosenLeaderboardCode;

  3. Since you will display the leaderboard list in buttons, create a new function for the button callback to change to the next menu and store the chosen leaderboard code to the public chosenLeaderboardCode. Later on, this function will be bound to the generated buttons.

    private void ChangeToLeaderboardCycleMenu(string newLeaderboardCode)
    {
        chosenLeaderboardCode = newLeaderboardCode;
        MenuManager.Instance.ChangeToMenu(AssetEnum.LeaderboardCycleMenuCanvas_Starter);
    }

Leaderboard Cycle Menu UI​

  1. Open LeaderboardCycleMenu_Starter.cs.

  2. Define the LeaderboardCycleType enum for the leaderboard cycle type you want to support. Later, when you query the leaderboard, you will need to specify the cycle type you want. In this module, you only need to define AllTime.

    public static LeaderboardCycleType chosenCycleType;
    public enum LeaderboardCycleType
    {
        AllTime
    }

  3. Next, declare the helper variable to store the cycle ID.

    public static string chosenCycleId;

  4. Create a function to store the chosen cycle type and direct to the Leaderboard Menu.

    public static void ChangeToLeaderboardMenu(LeaderboardCycleType cycleType, string cycleId)
    {
        chosenCycleType = cycleType;
        chosenCycleId = cycleId;

        MenuManager.Instance.ChangeToMenu(AssetEnum.LeaderboardMenuCanvas_Starter);
    }

  5. In the Start() function, add ChangeToLeaderboardMenu() to listen to the all-time button onClick event.

    private void Start()
    {
        backButton.onClick.AddListener(OnBackButtonClicked);
        allTimeButton.onClick.AddListener(() => ChangeToLeaderboardMenu(LeaderboardCycleType.AllTime, string.Empty));
    }

  6. In the Enable() function, add the code below to make sure the default state is shown when the leaderboard cycle menu is opened.

    private void OnEnable()
    {
        leaderboardListPanel.DestroyAllChildren(allTimeButton.transform);
        CurrentView = LeaderboardCycleView.Default;
    }

Enable starter mode​

  1. In the Unity Editor, open the LeaderboardEssentialsAssetConfig in the Inspector. You can find this file in Assets/Resources/Modules/LeaderboardEssentials/LeaderboardEssentialsAssetConfig.asset.

  2. In the Inspector, below the Tutorial Module Starter category, make sure the Is Starter Active is ticked.

Resources​

Last updated on

On this page