Use the SDK for periodic leaderboards - Weekly leaderboard - (Unity module)

Last updated on March 22, 2024

Unwrap the wrapper​

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

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

The PeriodicLeaderboardEssentialsWrapper class will mainly use the API client, the Leaderboard class, and the Statistic class provided by the AGS Game SDK. The Statistic class handles the cycle-related interactions, while the Leaderboard class handles periodic leaderboard-related interactions with AGS that both act as a service providing the ability to query the cycle list and the leaderboard's ranking list values based on the cycle period.

What's in the Starter Pack​

As you were instructed for the user interface (UI) section of this module, the starter class PeriodicLeaderboardEssentialsWrapper_Starter has been provided for you to modify. This file is available in the Resources section.

  • PeriodicLeaderboardEssentialsWrapper_Starter file: /Assets/Resources/Modules/PeriodicLeaderboard/Scripts/PeriodicLeaderboardEssentialsWrapper_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;
    private Statistic statistic;

Implement a periodic leaderboard​

By default, the leaderboard's GetLeaderboardListV3() query result also returns a list of Cycle IDs bound to that leaderboard code. In this section, you will prepare the function to use those Cycle IDs to query the cycle details info and then ranking the list based on the cycles.

  1. Open Byte Wars in Unity.

  2. Open PeriodicLeaderboardEssentialsWrapper_Starter.cs, implement the Start() function and initialize both the statistic and leaderboard variables to get the Statistic and Leaderboard classes.

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

  3. Prepare the functions for querying the cycles info. Since you are preparing an asynchronous function, create a callback function that will inform the user regarding the query process result. Add the AGS Game SDK Result and ResultCallback as parameters to keep the function modular and the result accessible from other script.

    private void OnGetStatCycleConfigCompleted(Result<StatCycleConfig> result, ResultCallback<StatCycleConfig> customCallback)
    {
        if (!result.IsError)
        {
            Debug.Log("Get Stat's Cycle Config info success!");
        }
        else
        {
            Debug.Log($"Get Stat's Cycle Config info failed. Message: {result.Error.Message}");
        }
        
        customCallback?.Invoke(result);
    }

  4. Create another function that will call the Statistic class GetStatCycleConfig() function to get the cycle config info and bind it with the callback function you made earlier. Also, add a string parameter for the Cycle ID since it's a required parameter for querying the function.

    public void GetStatCycleConfig(string cycleId, ResultCallback<StatCycleConfig> resultCallback)
    {
        statistic.GetStatCycleConfig(
            cycleId, 
            result => OnGetStatCycleConfigCompleted(result, resultCallback) 
        );
    }

  5. You will use a different function to get the leaderboard's ranking list based on the desired cycle. Since the function will be asynchronous, create a callback function to inform us regarding the query result. Also, add the Result and ResultCallback as parameters to keep it modular and accessible from any scripts.

    private void OnGetRankingsByCycleCompleted(Result<LeaderboardRankingResult> result, ResultCallback<LeaderboardRankingResult> customCallback)
    {
        if (!result.IsError)
        {
            Debug.Log("Get Ranking by Cycle success!");
        }
        else
        {
            Debug.Log($"Get Rankings by Cycle failed. Message: {result.Error.Message}");
        }
        
        customCallback?.Invoke(result);
    }

  6. Create another new function to call the Leaderboard class GetRankingsByCycle() function that will query the leaderboard's ranking list that's stored only for a period of time based on its leaderboardCode and cycleId.

    note

    offset and limit are optional parameters, but both are useful when you want to shorten your ranking list's query result.

    public void GetRankingsByCycle(string leaderboardCode, string cycleId, ResultCallback<LeaderboardRankingResult> resultCallback, int offset = default, int limit = default)
    {
        leaderboard.GetRankingsByCycle(
            leaderboardCode, 
            cycleId, 
            result => OnGetRankingsByCycleCompleted(result, resultCallback),
            offset,
            limit
        );
    }

Resources​

Last updated on

On this page