Service providers

A service provider serves one online service of the backend from a class of the game: stats from a web API of the studio while EOS keeps the login and the sessions, cloud files in a storage of the game, matchmaking tickets at FlexMatch. The provider is a Blueprint (or C++) class; the rest of Pulse Online (requests, subsystems, widgets, bridges) does not know that the service is not the one of the backend.

Pulse Online has one adapter per service a provider can serve. Create a Blueprint of the adapter (Add > Pulse > Online or the Create step of the Pulse window, where each adapter has an entry with its name), override the operations you need and name the class in the settings:

Adapter Service Operations
Online Achievement Provider IPulseOnlineAchievementService Query Definitions, Query States, Unlock Achievements, Ingest Stats, Query Stats
Online Server Achievement Provider IPulseOnlineServerAchievementService the same for any player, written by a trusted server
Online Stats Provider IPulseOnlineStatsService Query Stats, Update Stats
Online Server Stats Provider IPulseOnlineServerStatsService Query Stats, Update Stats for any player
Online Leaderboard Provider IPulseOnlineLeaderboardService Query Leaderboard, Supports Range
Online Title Storage Provider IPulseOnlineTitleStorageService Enumerate Files, Read File
Online User Storage Provider IPulseOnlineUserStorageService Get Capabilities, Enumerate Files, Read File, Write File (with condition), Delete File
Online Moderation Provider IPulseOnlineModerationService Send Report, Query Active Sanctions
Online Matchmaking Provider IPulseOnlineMatchmakingService Start Ticket, Cancel Ticket; Update Ticket and Finish Ticket answer
Online User Content Provider IPulseOnlineUserContentService Query Items, Subscribe, Download, Upload, Get Item State, Get Installed Items; Notify Item Changed
Online Anti-Cheat Provider IPulseOnlineAntiCheatService Check Pre Login, Register Client, Unregister Client, Receive From Client, Begin/End Client Session, Receive From Server; Send To Client, Send To Server, Report Violation

There are no adapters for the identity (login state and net ids), lobbies and game sessions (data of the backend, travel), friends, presence, avatars, commerce, voice, network and platform; they come from backends and extensions.

How an operation answers

Adapters are providers of PulseFoundation (UPulseProvider, see providers.md of PulseFoundation). Every operation gets a request id; the provider answers it with the Finish function of the operation, at once inside the operation or later from a timer, a web request or a task:

  • Operations without data answer with Finish Operation (Result).
  • Operations with data have their own Finish function, e.g. Finish Query Stats (Result, Stats).
  • An operation the provider does not override answers Not Supported (Pulse.Result.Failure.Online.NotSupported).
  • Every request is answered exactly once: a second or late answer is ignored with a warning, a request that waits too long fails with Pulse.Result.Failure.Timeout (Get Default Timeout, 30 seconds; matchmaking tickets and user content have no timeout), and the requests still open when the backend stops or another provider replaces this one answer Pulse.Result.Failure.Cancelled.
  • An answer given inside the operation reaches the caller inside its call, before the service function returns (also the Not Supported of an operation the provider does not override, and Update Ticket inside Start Ticket). Callers of the services handle that; a C++ provider that never wants to answer inside the call sets SetDelivery(EPulseProviderDelivery::NextTick) in OnInitialize.

The Result is a Pulse result. The services of Pulse Online work with FPulseOnlineResult; the adapter turns the answer back with Pulse::Online::FromResult: the reasons of the online layer and of PulseFoundation become their error ids again (Conflict stays Pulse.Online.Conflict, Timeout stays Pulse.Online.Timeout), any other reason becomes Pulse.Online.Unknown with the text of the result. Child tags of these reasons count as the reason. An online result in the details (an answer made with ToResult) comes back as it was, unless the provider changed the reason since.

Answer a write of the user storage whose condition does not hold with the reason Pulse.Result.Failure.Online.Conflict, so cloud saves see the conflict (Cloud Storage). Check Write Condition of the user storage adapter applies the rules of IfMissing and IfVersion with their texts, Make Content Hash makes the sha1: hash of the bytes (a version for a storage without its own).

A user storage provider whose Get Capabilities says bVersion must honour IfMissing and IfVersion. Cloud saves write their index with IfVersion on such a service; a provider that answers Not Supported there fails every save.

Choosing a provider

Settings: Project Settings > Pulse > Online > Service Overrides: the name of the service (picked from a list) to the provider class. The backend makes the providers when it starts, after its own services and its extensions, so a provider replaces what they registered. A provider that serves another service than its key is skipped with an error in LogPulseOnline; the Check step of the Pulse window reports the same entry.

Runtime: UPulseOnlineBackendSubsystem::SetServiceOverride(ServiceName, ProviderClass) serves the service by the provider from now on: the running backend makes it at once, and it wins over the settings after every SwitchBackend. A provider the running backend refuses (it serves another service, is abstract or makes no service) is not kept and the function returns false. The service name has a list to pick from in Blueprint. None as class removes the runtime override (the running backend keeps the provider until it starts again). GetServiceOverride(ServiceName) returns the class.

UPulseOnlineBackend::GetServiceProvider(ServiceName) returns the provider that serves a service, and GetServiceSource(ServiceName) where a service comes from (Backend, Extension, Provider, Runtime); the cheat PulseOnlineStatus prints both.

Example: only stats through a service of the game

  1. Create a Blueprint of Online Stats Provider, BP_StudioStats.
  2. Override Query Stats: send a web request to the stats API; when it answers, build an array of FPulseOnlineUserStats (user and stat name to value) and call Finish Query Stats with the request id, a success (Make Pulse Success) and the stats. On an error call it with Make Pulse Failure and a reason.
  3. Override Update Stats: send the changes, then Finish Operation.
  4. Project Settings > Pulse > Online > Service Overrides: IPulseOnlineStatsService → BP_StudioStats.

Blueprint: A stats provider in Blueprint

  1. Blueprint class of Online Stats Provider → override Query Stats (Request Id, Local User Id, User Ids, Stat Names).
  2. Send the web request of the game; in its answer build an array of Pulse Online User Stats (User Id, Stats map).
  3. Finish Query Stats (Request Id, Result = Make Pulse Success, Stats). On an error: Make Pulse Failure with a reason.
  4. Override Update Stats the same way and answer with Finish Operation; Project Settings > Pulse > Online > Service Overrides: IPulseOnlineStatsService → the Blueprint.

The stats subsystem, the leaderboards widget and PulseAchievementOnlineBridge now read and write the stats of the game service; login, sessions and the party stay on EOS.

C++ providers

A C++ provider derives from the adapter of its service and either overrides the _Implementation functions or returns its own native service from MakeService (the service must have the name of the adapter, GetServiceName):

UCLASS()
class UMyStatsProvider : public UPulseOnlineStatsProvider
{
	GENERATED_BODY()

public:

	virtual TSharedPtr<IPulseOnlineService> MakeService() override
	{
		return MakeShared<FMyStatsService>(GetBackend());
	}
};

The backend owns the provider (GetBackend()), initializes it before MakeService and ends it when it stops or when another service replaces it. Native services of the adapters forward each call as a request; a provider that answers off the game thread posts its answer to the inbox of the provider (GetInbox).

Extensions and DisabledExtensions

Backend extensions (UPulseOnlineBackendExtension, C++) still run before the providers. Disabled Extensions in the settings switches single extensions off, e.g. the Steam extension of PulseOnlineSteam in a build that only uses EOS. See Backends.


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