Implement leaderboards with the SDK - All time 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 LeaderboardEssentialsWrapper class, which already includes full functionality for fetching leaderboard rankings. For this tutorial, you will use the LeaderboardEssentialsWrapper_Starter wrapper, a starter version of the LeaderboardEssentialsWrapper 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 LeaderboardEssentialsWrapper_Starter. This wrapper is defined in the file below:

  • C# file: Assets/Resources/Modules/LeaderboardEssentials/Scripts/LeaderboardEssentialsWrapper_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 LeaderboardEssentialsWrapper_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 void Start()
    {
        leaderboard = AccelByteSDK.GetClientRegistry().GetApi().GetLeaderboard();
    }

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

Get Leaderboard Rankings​

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

  1. Open the LeaderboardEssentialsWrapper_Starter class and create the following function to send a request for leaderboard rankings based on the specified leaderboard code. Once the request completes, the callback function will be invoked to handle the result:

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

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

Get Player Leaderboard Rank​

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

  1. Open the LeaderboardEssentialsWrapper_Starter class and create the following function to send a request for the 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)
    {
        BytewarsLogger.Log($"Get user {userId} ranking in leaderboard {leaderboardCode} rankings.");

        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:

    private void OnGetUserRankingCompleted(Result<UserRankingDataV3> result, ResultCallback<UserRankingDataV3> customCallback)
    {
        if (!result.IsError)
        {
            BytewarsLogger.Log("Get User Ranking V3 successful.");
        }
        else
        {
            BytewarsLogger.LogWarning($"Get User Ranking V3 failed. Message: {result.Error.Message}");
        }
        
        customCallback?.Invoke(result);
    }

Resources​

Last updated on

On this page