Achievements

Two game instance subsystems (module PulseOnlineAchievements) with the same API. They only differ in the user id you pass:

  UPulseOnlineLocalAchievementSubsystem UPulseOnlineServerAchievementSubsystem
Who writes the local user, for itself a trusted server, for any connected player
User id net id of a logged in local user; empty = first local player net id of the player (APlayerState::GetUniqueId)
Service IPulseOnlineAchievementService of the backend (OSS: IOnlineAchievements/IOnlineStats, Mock) IPulseOnlineServerAchievementService (EOS: PulseOnlineEOS, Mock)
Exists Enable Local Achievements, never on dedicated servers Server Achievement Mode

Both share the base class UPulseOnlineAchievementSubsystemBase, so code can take either one (UPulseOnlineAchievementSubsystemBase::Get(WorldContext, EPulseOnlineAchievementAuthority)).

Why a separate server path: the online subsystems only write achievements of local users (OSSv1 EOS rejects other users, OSSv2 of the add-on PulseOnlineOSSv2 only knows LocalAccountId). A trusted server therefore talks to the service directly through the server achievement service. PulseOnlineEOS provides one for EOS (EOS_Achievements_UnlockAchievements, EOS_Achievements_QueryPlayerAchievements, EOS_Stats_IngestStat with the player as target; on a dedicated server without a local user).

Settings

Project Settings → Pulse → Online → Achievements:

Setting Default Meaning
Enable Local Achievements false Creates the local subsystem.
Query Local Achievements On Login true Definitions and states of a local user are read right after its login.
Server Achievement Mode Disabled Disabled, DedicatedServerOnly or AnyServer (also listen hosts, standalone and PIE; requests only run with authority).
Query Server Achievements On Post Login true The server reads the states of a player after PostLogin.
Requery Achievements After Stat Update true States are read again after stats were written, so stat based progress and unlocks show up.
Achievement Flush Interval Seconds 5 Queued writes (QueueStatIncrement) are sent together at this interval. 0 = next tick.
Flush Unlocks Immediately true Queued unlocks are sent right away.
[/Script/PulseOnlineAchievements.PulseOnlineAchievementSettings]
bEnableLocalAchievements=True
ServerAchievementMode=DedicatedServerOnly

Unlocks and progress

  • Unlock: UnlockAchievement(UserId, Id) / UnlockAchievements(UserId, Ids). Achievements the cache already knows as unlocked are skipped.
  • Progress: services like EOS unlock achievements when a stat reaches a threshold (set up in the service’s portal). UpdateAchievementStats(UserId, { STAT: Amount }) adds to stats; afterwards the states are read again. EOS stat names are upper case. Writing an achievement “value” directly is not used, because OSSv1 EOS unlocks every achievement written that way regardless of the value.
  • Read: QueryAchievementDefinitions(UserId) and QueryAchievements(UserId) fill the cache: GetCachedDefinitions, GetCachedAchievements, GetCachedAchievement, IsAchievementUnlocked, HasQueriedAchievements. Progress is always in [0, 1] (EOS reports 0..1, other OSSv1 services 0..100).
  • Read stats: QueryAchievementStats(UserId, { STAT, ... }) reads stat values (stats the user never wrote are 0): GetCachedStat, GetCachedStats, HasQueriedStats. Written increments (UpdateAchievementStats, batched writes) are added to cached stats once the write succeeded, so the cache is up to date before the service reports it.
  • Events: OnAchievementDefinitionsQueried, OnAchievementsQueried(UserId, bSuccess), OnAchievementUnlocked(UserId, Id), OnAchievementProgressChanged(UserId, State), OnAchievementStatsQueried(UserId, bSuccess), OnAchievementStatChanged(UserId, Stat, Value). The first query of a user only fills the cache for achievements; later queries broadcast what changed. Stat changes are always broadcast.

Each of these is a request (UPulseOnlineQueryAchievementDefinitionsRequest, UPulseOnlineQueryAchievementsRequest, UPulseOnlineQueryAchievementStatsRequest, UPulseOnlineUnlockAchievementsRequest, UPulseOnlineUpdateAchievementStatsRequest) running in the queue of its subsystem; the subsystem functions start them and return them, so they work with Execute Online Request. The request property Authority picks the subsystem when a request is created by class.

// Local: the player unlocks for itself.
UPulseOnlineLocalAchievementSubsystem* local = GameInstance->GetSubsystem<UPulseOnlineLocalAchievementSubsystem>();
local->UnlockAchievement(FUniqueNetIdRepl(), TEXT("FIRST_STEPS"));

// Server: the dedicated server unlocks for a player.
UPulseOnlineServerAchievementSubsystem* server = GameInstance->GetSubsystem<UPulseOnlineServerAchievementSubsystem>();
server->UnlockAchievement(PlayerState->GetUniqueId(), TEXT("BOSS_DEFEATED"));
server->UpdateAchievementStats(PlayerState->GetUniqueId(), { { TEXT("BOSSES_DEFEATED"), 1 } });

Batched writes

QueueStatIncrement(UserId, Stat, Amount) and QueueUnlockAchievement(UserId, Id) collect writes per user: stat increments are summed and sent every Achievement Flush Interval Seconds, unlocks are deduplicated and sent at once (Flush Unlocks Immediately). FlushPendingWrites(UserId) / FlushAllPendingWrites() send now. Queued writes are also sent when a player logs out and before a world tears down. Writes that are still queued when the game instance shuts down are dropped (logged).

Automatic progress and world achievements

Trackers (delegates that write progress automatically) and achievements per world or save game live in the separate PulseAchievement plugin. Its bridge PulseAchievementOnlineBridge writes world unlocks and stats to these subsystems (through QueueUnlockAchievement / QueueStatIncrement), per achievement or with graph nodes such as “Unlock Online Achievement”. Online states only flow back into a world where a graph reads them explicitly (its “On Online …” nodes, e.g. for achievements across save games).

Server achievement service

IPulseOnlineServerAchievementService (Services/PulseOnlineAchievementServices.h) has QueryDefinitions, QueryStates, UnlockAchievements, IngestStats and the optional QueryStats. A backend or a backend extension registers it (see Backends); PulseOnlineEOS does it for EOS, the Mock backend has one for tests. Without the service, server requests fail with Pulse.Result.Failure.Online.NotSupported and the subsystem logs a warning at startup.

EOS setup: the server’s client (credentials in the server config) needs a client policy that allows unlocking achievements and ingesting stats for other users (“Trusted Server”). The game clients only need permissions for their own user.

Blueprint: Unlock an achievement for a player on the server

  1. On the server: Get Game Instance Subsystem (Pulse Online Server Achievement Subsystem).
  2. Player State → Get Unique Net Id → Unlock Achievement (User Id, Achievement Id BOSS_DEFEATED) → Execute Online Request.
  3. For progress: Queue Stat Increment (User Id, Stat Name BOSSES_DEFEATED, Amount 1); it is sent with the next flush.
  4. Clients see server unlocks with their next Query Achievements of the Pulse Online Local Achievement Subsystem, which then broadcasts On Achievement Unlocked.

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