Statistics and Leadeboards

Statistics are a means to save interesting numerical aspects of player game. For instance, a statistic can represent a balance, xp points, score, etc.

Even if it looks like statistics overlap the game state feature, it comes with the benefit of attaching an implicit leaderboard to each of them.

When the SDK sees a statistic not defined upfront, it still accepts it and attaches a default configuration

Update strategy: LAST
Reset interval: NEVER

More about those values below.

Update mode

Update mode defines how values pushed to the backend will get updated

LAST: The stat will always get the last value pushed, no computation will be applied
SUM: The stat will increase by the given value
MIN: The stat will get updated only if the new value is lower than the current value
MAX: The stat will get updated only if the new value is greater than the current value

Reset interval

This parameter governs both the leaderboard and the statistic value. At the given reset interval, the statistic value will go back to 0, and a new leaderboard will start for the period.

NEVER: The stat and leaderboard never reset
DAILY: Reset every day at 00:00 UTC,
WEEKLY: Reset every week on Monday 00:00 UTC
MONTHLY: Reset every month, first day of the month at 00:00 UTC

Manage statistic values

Update

Each statistic can be updated on a case-by-case basis, but updates can also come in batch for maximum efficiency. You can specify as many statistics you want in the update request. Other already existing stats will remain unchanged.

                    p00lsGamesSdk.UpdateStatistic(
                        new Dictionary<string, long>
                        {
                            { "hiscore", 100 },
                            { "hiscore_weekly", 300 },
                        });
                    

                    sdk.statistics.updateValues({
                        test_stat_1: Math.floor(Math.random() * 100),
                        test_stat_2: Math.floor(Math.random() * 100),
                      })
                   

Get

All player statistics are fetched at once. If a statistics is using a reset interval, the field resetId will be present, with the number of seconds before reset.

                    sdk.GetStatistics(values =>
                    {
                        Debug.Log("Statistics");
                        foreach (var (statName, stat) in values)
                        {
                            // values a dictionary of statName -> stat info
                            Debug.Log(
                                $"{statName}: {stat.value} // {stat.version}  Reset : {stat.resetIn.HasValue} {stat.resetIn}");
                        }
                    });
                    

                        const values = await sdk.statistics.fetchValues();
                        // values is on object of type

                        type UserStatisticValues = {
                          [key: string]: StatisticValueSummary;
                        };

                        interface StatisticValueSummary {
                          value: number;
                          version: number;
                          resetIn?: number;
                        }
                    

Leaderboards

User position

You can query just the user position for a given statistic. The result can be null if no values have been recorded yet.

                    sdk.GetUserPosition("hiscore", result =>
                    {
                        Debug.Log("Position:");
                        Debug.Log($"Position: {result?.position}");
                        Debug.Log($"Value: {result?.value}")
                        Debug.Log($"Reset in :{result?.resetIn}");
                    });
                    

                        const position = await sdk.statistics.fetchLeaderboardPosition("hiscore");
                        if(position) {
                            console.log("Position:");
                            console.log(`Position: ${result.position}`);
                            console.log(`Value: ${result.value}`)
                            console.log(`Reset in : ${result.resetIn || 'nop'}`);
                        }
                    

Fetch

You can get a leaderboard from first position and then paginate to the end. If the leaderboard has a reset interval, the field resetIn will be defined, with the number of seconds before reset.

                        sdk.GetLeaderboard("hiscore", leaderboard =>
                        {

                            Debug.Log($"Next: {leaderboard.next}");
                            Debug.Log($"Reset In: {leaderboard.resetIn}");
                            foreach (var entry in leaderboard.entries)
                            {
                                Debug.Log(
                                    $"Entry: {entry.displayName}, {entry.position}, {entry.value}");
                            }
                        });
                    

GetLeaderboard accept two optional parameters :

pageSize: Default 50
next: Cursor to fetch the next page

                        const {entries, next, resetIn} = await sdk.statistics.fetchLeaderboard('hiscore');
                    

fetchLeaderboard accept an optional parameter, where next is the next page cursor, and pageSize is the initial page size.

                    type Params = {
                        next?: string;
                        pageSize?: number
                    }
                    

Around user

You can also query a leaderboard to get a portion of it centered around the user. It works the same way as Fetch the only difference being you cannot paginate the results.

Depending on the user's position, his entry will not always be in the middle of the returned list. For example, if he's first or last, he may appear at either the beginning or the end.

If the user is not ranked yet, the top leaderboard is returned instead.

                        sdk.GetLeaderboardAround("hiscore", leaderboard =>
                        {

                            Debug.Log($"Next: {leaderboard.next}");
                            Debug.Log($"Reset In: {leaderboard.resetIn}");
                            foreach (var entry in leaderboard.entries)
                            {
                                Debug.Log(
                                    $"Entry: {entry.displayName}, {entry.position}, {entry.value}");
                            }
                        });
                    

GetLeaderboardAround accept two optional parameters :

pageSize: Default 50

                        const {entries, next, resetIn} = await sdk.statistics.fetchLeaderboardAround('hiscore');
                    

fetchLeaderboardAround accept an optional parameter, where pageSize is the initial page size.

                    type Params = {
                        pageSize?: number
                    }
                    

Last modified: 28 November 2024