Implement leaderboards with the SDK - All time leaderboard - (Unity module)

Last updated on March 22, 2024

Unwrap the wrapper​

In this tutorial, you will learn how to implement a leaderboard into Byte Wars using the AccelByte Gaming Services (AGS) Game SDK.

Byte Wars uses a wrapper class named LeaderboardEssentialsWrapper that acts as the wrapper to cache and handle the leaderboard service functionalities when using the AGS Game SDK. This way, it provides modularity without overriding engine classes.

The LeaderboardEssentialsWrapper class will mainly be using the API Client and Leaderboard class provided by the AGS Game SDK. This Leaderboard class handles leaderboard-related interactions with AGS that act as a service that provides the ability to query the leaderboard list and their ranking list values.

What's in the Starter Pack​

Just as you were instructed for the UI section of this module, a LeaderboardEssentialsWrapper_Starter class has been provided for you as the starter code. This file is available in the Resources section.

  • LeaderboardEssentialsWrapper_Starter.cs file: /Assets/Resources/Modules/LeaderboardEssentials/Scripts/LeaderboardEssentialsWrapper_Starter.cs

The starter class has some functionalities already provided for you:

  • The AGS Game SDK libraries declarations, which allow the use of the AGS Statistic and Server Statistic classes.

    using AccelByte.Api;
    using AccelByte.Core;
    using AccelByte.Models;

  • Leaderboard variable declarations to hold the leaderboard functionalities.

    private Leaderboard leaderboard;

Implement a leaderboard​

  1. Open Byte Wars in Unity.

  2. Open LeaderboardEssentialsWrapper_Starter.cs and initialize the leaderboard variable to get the Leaderboard class in the Start() function. Copy the following function.

    void Start()
    {
        leaderboard = MultiRegistry.GetApiClient().GetLeaderboard();
    }

  3. Prepare for querying the leaderboard list. Since the function is asynchronous, create a callback function that will inform the user regarding the query process result. To keep it modular, you will add the AGS Game SDK Result and ResultCallback, so the result will be accessible from other scripts.

    private void OnGetLeaderboardListCompleted(Result<LeaderboardPagedListV3> result, ResultCallback<LeaderboardPagedListV3> customCallback = null)
    {
        if (!result.IsError)
        {
            Debug.Log("Get leaderboard list successful.");
        }
        else
        {
            Debug.Log($"Get leaderboard list failed. Message: {result.Error.Message}");
        }

        customCallback?.Invoke(result);
    }

  4. Create another function to call the GetLeaderboardList function and bind it with the callback function you created earlier. This function will return all available leaderboards that are registered in the AGS Admin Portal.

    public void GetLeaderboardList(ResultCallback<LeaderboardPagedListV3> resultCallback)
    {
        leaderboard.GetLeaderboardListV3(
            result => OnGetLeaderboardListCompleted(result, resultCallback)
        );
    }

  5. You need to implement the get leaderboard ranking data function. This function is also asynchronous, so create a new callback function that will inform the user regarding the result. You also need to add the AGS Game SDK Result and ResultCallback in the parameters list, so the result will be accessible from other scripts.

    private void OnGetRankingsCompleted(Result<LeaderboardRankingResult> result, ResultCallback<LeaderboardRankingResult> customCallback = null)
    {
        if (!result.IsError)
        {
            Debug.Log("Get leaderboard ranking data successful.");
        }
        else
        {
            Debug.Log($"Get leaderboard ranking data failed. Message: {result.Error.Message}");
        }
        
        customCallback?.Invoke(result);
    }

  6. Create another new function to call the GetRankingList function, then bind it with the callback function you just created. This function will return all available ranking lists of the chosen leaderboard for all available periods.

    public void GetRankings(string leaderboardCode, ResultCallback<LeaderboardRankingResult> resultCallback, int offset = default, int limit = default)
    {
        leaderboard.GetRankingsV3(
            leaderboardCode,
            result => OnGetRankingsCompleted(result, resultCallback), 
            offset, 
            limit
        );
    }

  7. To get a specific user's ranking information, you need to prepare a separate function. Create a new callback function to inform the query process result with Result and ResultCallback to keep it modular and easy to access.

    private void OnGetUserRankingCompleted(Result<UserRankingDataV3> result, ResultCallback<UserRankingDataV3> customCallback)
    {
        if (!result.IsError)
        {
            Debug.Log("Get player ranking successfull.");
        }
        else
        {
            Debug.Log($"Get player ranking failed. Message: {result.Error.Message}");
        }
        
        customCallback?.Invoke(result);
    }

  8. Create a new function to call the GetUserRanking function and bind it with the callback function you created. This function will return the desired user's ranking information of the desired leaderboard for all leaderboard period options.

    public void GetUserRanking(string userId, string leaderboardCode, ResultCallback<UserRankingDataV3> resultCallback)
    {
        leaderboard.GetUserRankingV3(
            userId,
            leaderboardCode,
            result => OnGetUserRankingCompleted(result, resultCallback)
        );
    }

Resources​

Last updated on

On this page