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

Last updated on March 12, 2025

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 = AccelByteSDK.GetClientRegistry().GetApi().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)
        {
            BytewarsLogger.Log("Get Leaderboard List V3 successful.");
        }
        else
        {
            BytewarsLogger.LogWarning($"Get Leaderboard List V3 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 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)
        {
            BytewarsLogger.Log("Get Rankings V3 successful.");
        }
        else
        {
            BytewarsLogger.LogWarning($"Get Rankings V3 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)
    {
        BytewarsLogger.Log($"Get leaderboard {leaderboardCode} rankings.");

        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)
        {
            BytewarsLogger.Log("Get User Ranking V3 successfull.");
        }
        else
        {
            BytewarsLogger.LogWarning($"Get User Ranking V3 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)
    {
        BytewarsLogger.Log($"Get user {userId} ranking in leaderboard {leaderboardCode} rankings.");

        leaderboard.GetUserRankingV3(
            userId,
            leaderboardCode,
            result => OnGetUserRankingCompleted(result, resultCallback)
        );
    }

Resources​

Last updated on

On this page