Use the SDK to set and query stats - Stat tracking and display - (Unity module)

Last updated on March 12, 2025

Unwrap the Wrapper

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

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

The StatsEssentialsWrapper class uses the ApiClient, Statistic, and ServerStatistic classes provided by the AGS Game SDK. These classes interact with the AGS Statistics service to update and query the statistics value.

What's in the Starter Pack

Just as in the UI tutorial of this module, a StatsEssentialsWrapper_Starter class has been provided for you with the starter code. This file is available in the Resources section and consists of the following file:

StatsEssentialsWrapper_Starter.cs: /Assets/Resources/Modules/StatsEssentials/Scripts/StatsEssentialsWrapper_Starter.cs

The file contains some functionalities for you already:

Namespaces declarations for using the Statistic and ServerStatistic classes from the AGS Game SDK.
```
using AccelByte.Api;
using AccelByte.Core;
using AccelByte.Models;
using AccelByte.Server;
```
Local variables that hold the references to the Statistic and ServerStatistic classes.
```
private Statistic statistic;
private ServerStatistic serverStatistic;
```

Integrate Statistics service

This section will guide you through implementing the AGS Statistics service using the AGS Game SDK.

Integrate into client side

Open Byte Wars in Unity.
Open StatsEssentialsWrapper_Starter.cs. In the Start() function, initialize the statistic variable to get the Statistic object of the client ApiClient.
```
void Start()
{
    statistic = AccelByteSDK.GetClientRegistry().GetApi().GetStatistic();
}
```

Implement the function to update a statistic value. Since the process is asynchronous, create a callback function that will inform the user regarding the result. You add the AGS Game SDK Result and ResultCallback as parameters so the result will be accessible from other scripts.

private void OnUpdateUserStatsFromClientCompleted(Result<UpdateUserStatItemValueResponse> result, ResultCallback<UpdateUserStatItemValueResponse> customCallback = null)
{
    if (!result.IsError)
    {
        BytewarsLogger.Log("Update User's Stat Items from Client successful.");
    }
    else
    {
        BytewarsLogger.LogWarning($"Update User's Stat Items from Client failed. Message: {result.Error.Message}");
    }
    
    customCallback?.Invoke(result);
}

Create a new function called UpdateUserStatsFromClient to update player statistic value from game client. To update the statistic value, you need to provide the statistic code to update and an instance of PublicUpdateUserStatItem to store the new value and the update strategy (e.g. min, max, or total).

public void UpdateUserStatsFromClient(string statCode, PublicUpdateUserStatItem statItem, string additionalKey, ResultCallback<UpdateUserStatItemValueResponse> resultCallback = null)
{        
    statistic.UpdateUserStatItemsValue(
        statCode,
        additionalKey,
        statItem,
        result => OnUpdateUserStatsFromClientCompleted(result, resultCallback)
    );
}

Create the function to query statistics values. Create another callback function in StatsEssentialsWrapper_Starter class that will inform the user of the query result. Similar to before, you add the AGS Game SDK Result and ResultCallback as the parameters.

private void OnGetUserStatsFromClientCompleted(Result<PagedStatItems> result, ResultCallback<PagedStatItems> customCallback = null)
{
    if (!result.IsError)
    {
        BytewarsLogger.Log("Get User's Stat Items from Client successful.");
    }
    else
    {
        BytewarsLogger.LogWarning($"Get User's Stat Items from Client failed. Message: {result.Error.Message}");
    }
    
    customCallback?.Invoke(result);
}

Create a new function called GetUserStatsFromClient that calls the GetUserStatItems() function from the Statistic class from the AGS Game SDK. You can get all statistic values of the player at once by providing an array of targeted statCodes, an array of tags as a filter, and a ResultCallback to the function.

public void GetUserStatsFromClient(string[] statCodes, string[] tags, ResultCallback<PagedStatItems> resultCallback)
{
    statistic.GetUserStatItems(
        statCodes, 
        tags, 
        result => OnGetUserStatsFromClientCompleted(result, resultCallback)
    );
}

Integrate into server side

Open Byte Wars in Unity.
Open StatsEssentialsWrapper_Starter.cs. In the Start() function, initialize the serverStatistic variable to get the Statistic class from the server ApiClient.
```
void Start()
{
    ...
    serverStatistic = AccelByteSDK.GetServerRegistry().GetApi().GetStatistic();
}
```

Implement the function for updating the statistic values for many users. Since the process is asynchronous, create a callback function that will inform the user regarding the result. Add the AGS Game SDK Result and ResultCallback as parameters so the result will be accessible from other scripts.

private void OnUpdateManyUserStatsFromServerCompleted(Result<StatItemOperationResult[]> result, ResultCallback<StatItemOperationResult[]> customCallback = null)
{
    if (!result.IsError)
    {
        BytewarsLogger.Log("Update User's Stat Items from Server successful.");
    }
    else
    {
        BytewarsLogger.LogWarning($"Update User's Stat Items from Server failed. Message: {result.Error.Message}");
    }
    
    customCallback?.Invoke(result);
}

Create a new function to call the UpdateManyUsersStatItems() to update multiple player statistic values from game server. To update those values, you need to provide the statistic code to update and the list of UserStatItemUpdate instance that contains target user ID, new statistic value, and the update strategy (e.g. min, max, or total).

public void UpdateManyUserStatsFromServer(string statCode, List<UserStatItemUpdate> statItems, ResultCallback<StatItemOperationResult[]> resultCallback)
{   
    serverStatistic.UpdateManyUsersStatItems(
        statItems.ToArray(),
        result => OnUpdateManyUserStatsFromServerCompleted(result, resultCallback));
}

Create the function for querying statistic values. Create another callback function in StatsEssentialsWrapper_Starter that will inform the user of the query result. Similar to before, you add the AGS Game SDK Result and ResultCallback as parameters.

private void OnGetUserStatItemsFromServerCompleted(Result<FetchUserStatistic> result, ResultCallback<FetchUserStatistic> customCallback = null)
{
    if (!result.IsError)
    {
        BytewarsLogger.Log("Get User's Stat Items from Server successful.");
    }
    else
    {
        BytewarsLogger.LogWarning($"Get User's Stat Items from Server failed. Message: {result.Error.Message}");
    }
    
    customCallback?.Invoke(result);
}

Create another function that will call the BulkFetchStatItemsValue() function in the ServerStatistic class with an array of target players' userId, the target statistics value's statCode, and ResultCallback as parameters. Similar to the UpdateUserStatItems() function in the ServerStatistic class, game servers can also query multiple statistic values of a specific player at once.
```
public void BulkGetUsersStatFromServer(string[] userIds, string statCode, ResultCallback<FetchUserStatistic> resultCallback)
{
    serverStatistic.BulkFetchStatItemsValue(
        statCode,
        userIds,
        result => OnGetUserStatItemsFromServerCompleted(result, resultCallback)
    );
}
```

Resources

GitHub link to the file in the Unity Byte Wars repository:
- Assets/Resources/Modules/StatsEssentials/Scripts/StatsEssentialsWrapper_Starter.cs

Unwrap the Wrapper​

What's in the Starter Pack​

Integrate Statistics service​

Integrate into client side​

Integrate into server side​

Resources​

On this page