Stats and Leaderboards
The module PulseOnlineStats reads and writes stats (named integer values per user) and reads leaderboards. Everything runs through one game instance subsystem, UPulseOnlineStatsSubsystem, whose functions start requests in its queue.
| Who writes | How | Service |
|---|---|---|
| A local user, its own stats | UpdateStats / QueueStatUpdate with an empty user id or the local net id | IPulseOnlineStatsService (OSS: IOnlineStats, OSSv2 (add-on PulseOnlineOSSv2): IStats, Mock) |
| A server (authority), any connected player | the same functions with the player’s net id (APlayerState::GetUniqueId) | IPulseOnlineServerStatsService (EOS: PulseOnlineEOS, Mock) |
Clients never write stats of other players; such a request fails with a message. Values that decide something (rankings, ratings for matchmaking) should only be written by a dedicated server, because a client can change what it sends.
Setup
- Enable the module (it is on by default;
Enable Statsin Project Settings → Pulse → Online → Stats switches the subsystem off). - Create the stats in the portal of your online service. EOS: Game Services → Stats, names upper case, with the aggregation that fits (
SUM,LATEST,MAX,MIN); leaderboards are built on a stat in Game Services → Leaderboards. - Server writes on EOS need the server’s client policy to allow ingesting stats for other users (see Achievements).
| Setting | Default | Meaning |
|---|---|---|
| Enable Stats | true | Creates the subsystem. |
| Stats Flush Interval Seconds | 5 | Queued updates are sent together at this interval. 0 = next tick. |
| Flush On Logout | true | A server sends the queued updates of a player when the player leaves. |
| Default Leaderboard Count | 10 | Rows of a leaderboard query without a count. |
Writing stats
An update has a stat name, a value and a modification:
| Modification | Effect on the stored value |
|---|---|
Sum | adds the value (default) |
Set | replaces the value |
Largest | keeps the larger one |
Smallest | keeps the smaller one |
The modification is what Pulse Online sends to the service. Services that aggregate themselves (EOS) apply the aggregation configured in their portal; pick the matching one there.
UpdateStats(UserId, Updates)writes right away.QueueStatUpdate(UserId, Stat, Value, Modification)collects updates per user: sums are added up,Set,LargestandSmallestkeep the stronger value. They are sent everyStats Flush Interval Seconds;FlushQueuedStats(UserId)/FlushAllQueuedStats()send them now. A server also sends the queue of a player when the player logs out (Flush On Logout). Updates still queued when the game instance shuts down are dropped (logged).
UPulseOnlineStatsSubsystem* stats = UPulseOnlineStatsSubsystem::Get(this);
// Local user, batched: three kills become one write of +3.
stats->QueueStatUpdate(FUniqueNetIdRepl(), TEXT("KILLS"), 1);
// Server, for a player: best time of a race.
stats->UpdateStats(PlayerState->GetUniqueId(), { FPulseOnlineStatUpdate(TEXT("BEST_LAP_MS"), LapMs, EPulseOnlineStatModification::Smallest) });
EOS stats are 32 bit; larger values are clamped.
Reading stats
QueryStats(Users, StatNames) reads stats of one or more users (empty Users = the first local user). A client reads with its local user, a dedicated server without a local user reads through the server stats service.
Read values are cached per user: GetCachedStat(UserId, Stat, Value), GetCachedStats(UserId). Successful writes update cached values that are already known, so the cache is current before the next read.
Events: OnStatsUpdated(UserId, bWritten) (native OnStatsUpdatedNative) and the message Pulse.Message.Online.Stats.Updated (FPulseOnlineStatsMessage: user, changed stats, written or read).
Leaderboards
QueryLeaderboard(Query) reads a part of a leaderboard. FPulseOnlineLeaderboardQuery:
| Field | Meaning |
|---|---|
LeaderboardId | Leaderboard id of the service (EOS: the leaderboard id; Mock: the stat name). |
Range | Top, AroundUser, Friends or Users. |
StartRank | Top: first rank to read (1 = best). |
Count | Rows; 0 uses Default Leaderboard Count. AroundUser centers the user and shifts the window at the ends. |
LocalUserId | Who reads; empty = first local user. |
TargetUserId | AroundUser: around whom; empty = the local user. |
Users | Users: the users to read. |
Rows (FPulseOnlineLeaderboardEntry): Rank (1 = best, equal scores share a rank), UserId, DisplayName, Score, bIsLocalUser. The last read of each leaderboard is cached (GetCachedLeaderboard) and broadcast (OnLeaderboardRead). For widgets use the leaderboard view model.
Backend notes:
- OSS (EOS):
AroundUserfirst reads the user’s rank, then the rows around it.Friendsneeds the friends list of the online subsystem. - OSSv2 (add-on PulseOnlineOSSv2):
TopandAroundUserread by rank and user; friends come fromISocial. - Mock: leaderboards are computed from the stats of all mock users; every mock user is a friend (
bEverybodyIsFriend).
A backend that cannot read a range answers SupportsRange(Range) = false; the request then fails with a message instead of returning wrong rows.
Server stats service
IPulseOnlineServerStatsService (Services/PulseOnlineStatsServices.h) has QueryStats(Users, Names) and UpdateStats(User, Updates). PulseOnlineEOS registers one on the OSS backend (EOS Stats interface with the server’s client, no local user needed), the Mock backend has one for tests. Without it, server writes for other players fail with Pulse.Result.Failure.Online.NotSupported.
Testing
- Specs:
PulseOnline.Stats(rules and Mock flows),PulseOnline.MVVM.Leaderboard. - Cheats:
PulseOnlineStat,PulseOnlineStats,PulseOnlineLeaderboard(see Debugging). With the Mock backend in PIE (listen server + client), both players write stats and read the same leaderboard.