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

Last updated on June 23, 2025

Unwrap the Wrapper​

In this tutorial, you will learn how to implement AccelByte Gaming Services (AGS) Leaderboard using the AGS Software Development Kit (SDK) to retrieve leaderboard rankings. In Byte Wars, there is a game instance wrapper defined in the PeriodicLeaderboardWrapper class, which already includes full functionality for fetching periodic leaderboard rankings. For this tutorial, you will use the PeriodicLeaderboardWrapper_Starter wrapper, a starter version of the PeriodicLeaderboardWrapper class, to implement the feature from scratch.

What's in the Starter Pack​

To follow this tutorial, you will use the starter wrapper class called PeriodicLeaderboardWrapper_Starter. This wrapper is defined in the file below:

  • C# file: Assets/Resources/Modules/PeriodicLeaderboard/Scripts/PeriodicLeaderboardWrapper_Starter.cs

There is also a model class containing helper constant variables and a struct, defined in the file below:

  • C# file: Assets/Resources/Modules/LeaderboardEssentials/Scripts/LeaderboardEssentialsModels.cs

The PeriodicLeaderboardWrapper_Starter class includes several predefined components:

  • Helper variables to reference the AGS SDK interfaces. These variables are assigned when the wrapper is initialized:

    private Leaderboard leaderboard;
    private Statistic statistic;

    void Start()
    {
        leaderboard = AccelByteSDK.GetClientRegistry().GetApi().GetLeaderboard();
        statistic = AccelByteSDK.GetClientRegistry().GetApi().GetStatistic();
    }

The LeaderboardEssentialsModels class includes the following helpers:

  • Constants for UI messages and the query limit used when sending requests to retrieve leaderboard rankings:

    public static readonly int QueryRankingsLimit = 10;
    public static readonly string RankedMessage = "Your Rank";
    public static readonly string UnrankedMessage = "You Are Unranked";

  • A function to get the leaderboard code based on the game mode. These codes match the leaderboard codes you’ve configured in the Admin Portal:

    public static string GetLeaderboardCodeByGameMode(InGameMode gameMode)
    {
        string gameModeSuffx = "unknown";
        switch (gameMode)
        {
            case InGameMode.SinglePlayer:
            case InGameMode.LocalElimination:
            case InGameMode.LocalTeamDeathmatch:
                gameModeSuffx = "singleplayer";
                break;
            case InGameMode.MatchmakingElimination:
            case InGameMode.CreateMatchElimination:
                gameModeSuffx = "elimination";
                break;
            case InGameMode.MatchmakingTeamDeathmatch:
            case InGameMode.CreateMatchTeamDeathmatch:
                gameModeSuffx = "teamdeathmatch";
                break;
        }
        return $"board-unity-highestscore-{gameModeSuffx}";
    }

  • A function to get the leaderboard cycle name based on selected period. These names match the statistics cycle you’ve configured in the Admin Portal:

    public static string GetFormattedLeaderboardPeriod(StatisticCycleType period) => $"unity-{period.ToString()}".ToLower();

Get Stat Cycle Config​

In this section, you will implement the functionality to retrieve the statistics cycle config.

  1. Open the PeriodicLeaderboardWrapper_Starter class and create the function below to get the statistics cycle configs. You need this config to get the cycle ID, which can then be used to send periodic leaderboard ranking requests later.

    public void GetStatCycleConfigByName(string cycleName, ResultCallback<StatCycleConfig> resultCallback)
    {
        statistic.GetListStatCycleConfigs(result => OnGetStatCycleConfigByNameCompleted(cycleName, result, resultCallback));
    }

  2. Next, create the callback function to handle the result of the request. It filters the list and returns only the one that matches the requested cycle name.

    private void OnGetStatCycleConfigByNameCompleted(string cycleName, Result<PagedStatCycleConfigs> result, ResultCallback<StatCycleConfig> customCallback)
    {
        if (result.IsError)
        {
            BytewarsLogger.LogWarning($"Get stat cycle config by name failed. Message: {result.Error.Message}");
            customCallback.Invoke(Result<StatCycleConfig>.CreateError(result.Error));
            return;
        }

        StatCycleConfig statCycle = result.Value.Data.FirstOrDefault(x => x.Name.Equals(cycleName, StringComparison.OrdinalIgnoreCase));
        if (statCycle == null)
        {
            string errorMessage = $"Stat cycle config with cycle name {cycleName} not found.";
            BytewarsLogger.LogWarning($"Get stat cycle config by name failed. Message: {errorMessage}");
            customCallback.Invoke(Result<StatCycleConfig>.CreateError(ErrorCode.NotFound, errorMessage));
            return;
        }

        BytewarsLogger.Log("Get stat cycle config by name success!");
        customCallback.Invoke(Result<StatCycleConfig>.CreateOk(statCycle));
    }

Get Periodic Leaderboard Rankings​

In this section, you will implement the functionality to retrieve periodic leaderboard rankings.

  1. Open the PeriodicLeaderboardWrapper_Starter class and create the following function to send a request for periodic leaderboard rankings based on the specified leaderboard code and the cycle ID. Once the request completes, the callback function will be invoked to handle the 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
        );
    }

  2. Next, create the callback function to handle the result of the request. Here, it simply logs the request status and then invokes the callback delegate:

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

Get Player Periodic Leaderboard Rank​

In this section, you will implement functionality to get the periodic leaderboard rank for a specific player. You can use this later to display the current logged-in player's periodic leaderboard rank.

  1. Open the PeriodicLeaderboardWrapper_Starter class and create the following function to send a request for the periodic leaderboard ranking of a specific player by passing the player's user ID. Once complete, the callback function will be called to handle the result:

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

  2. Next, create the callback function to handle the request result. Here, it simply logs the request status and then invokes the callback delegate. If success, the result contains the rank values for each cycle ID associated with the leaderboard. 

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

Resources​

Last updated on

On this page