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

  1. Enable the module (it is on by default; Enable Stats in Project Settings → Pulse → Online → Stats switches the subsystem off).
  2. 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.
  3. 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, Largest and Smallest keep the stronger value. They are sent every Stats 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): AroundUser first reads the user’s rank, then the rows around it. Friends needs the friends list of the online subsystem.
  • OSSv2 (add-on PulseOnlineOSSv2): Top and AroundUser read by rank and user; friends come from ISocial.
  • 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.

This site uses Just the Docs, a documentation theme for Jekyll.