Backends
Pulse Online does not talk to an online subsystem directly. Its features (users, sessions, party, friends, presence, achievements, stats, voice) use services, small C++ interfaces in the core module. A backend connects the services to an online service. The game picks a backend once; the features work the same with every backend.
| Backend | Module | Priority | Services |
|---|---|---|---|
| OSS | PulseOnlineBackendOSS | 100 | Identity, sessions, friends, presence, achievements, stats, leaderboards (Online Subsystem v1, e.g. EOS, Steam, Null). |
| OSSv2 | PulseOnlineBackendOSSv2 (add-on PulseOnlineOSSv2) | 50 | Identity, sessions (lobbies and sessions), friends, presence, stats, leaderboards, files, store (Online Services v2). See OSSv2 backend. |
| Mock | PulseOnlineBackendMock | -100 | Everything, in memory. For specs, PIE without an online service and failure tests. |
PulseOnlineEOS (separate bridge plugin) extends the OSS backend when the online subsystem is EOS: lobby promotion, EOS voice, server achievements, server stats, the NAT type, reports and sanctions. A game serves single services from a class of its own, also in Blueprint, with a service provider (Service Providers).
Choosing the backend
UPulseOnlineBackendSubsystem (game instance) creates the backend at start:
- the command line
-PulseOnlineBackend=<Name>(OSS,Mock,OSSv2with the add-on, or a class name), - otherwise Backend Class in Project Settings > Pulse > Online,
- otherwise the available backend with the highest priority.
SwitchBackend(Class) changes it at runtime (e.g. for tests); OnBackendChanged tells the features to rebind. The cheat PulseOnlineBackend <Mock|OSS|OSSv2|Auto> does the same in a running game (see Debugging). GetBackendSource() says where the choice came from (Automatic, CommandLine, Settings, Switched).
Online service
A backend talks to an online service (GetOnlineServiceName() of the backend: EOS, Steam, NULL, Mock). GetOnlineServiceStatus() of UPulseOnlineBackendSubsystem sums it up, e.g. to show an offline mode in the menu:
| Status | Meaning |
|---|---|
Online | An online service runs (EOS, Steam, …): accounts, friends, online sessions. |
Null | The Null online subsystem runs: local play and LAN sessions only, no accounts, friends or achievements. |
None | No online service runs: online features report Pulse.Result.Failure.Online.NotSupported, or the Mock backend stands in because no other backend is available. |
Mock | The Mock backend, chosen on purpose (command line, settings, SwitchBackend). |
When no online service runs, the first game instance of the process logs one warning in LogPulseOnline with the cause and what to set:
- no
DefaultPlatformServicein[OnlineSubsystem], so the Null subsystem runs; DefaultPlatformService=Null;- a configured service that did not start (e.g.
EOSwith its plugin disabled,[OnlineSubsystemEOS] bEnabled=Falseor missing EOS settings): the engine silently falls back to the Null subsystem, the warning names the plugin and the switch to check; - the Mock backend standing in because nothing else is available.
Specs and a Mock backend chosen on purpose do not warn. Games that only play locally or in a LAN turn the warning off with Warn Without Online Service (bWarnWithoutOnlineService, Project Settings > Pulse > Online). The Pulse Debugger page Online shows the service and the status in the Backend section (yellow without an online service), and the setup step Choose the online service checks the same in the editor.
Services
| Service | Used by |
|---|---|
IPulseOnlineIdentityService | Users and login: login, logout, net ids, privileges, connection status. |
IPulseOnlineLobbyService | Lobbies, groups of players without a game server (the party is the lobby NAME_PartySession): create, find, join, leave, lobby and member attributes, kick, promote, invites, snapshots, the owner’s address (Party). |
IPulseOnlineGameSessionService | Game sessions, the game players join and travel to: host, find, join, leave, update, invites, snapshots, connect strings, reservation beacons, listen URL options (Sessions). |
IPulseOnlineFriendsService | Friends list and its changes. |
IPulseOnlinePresenceService | Rich presence. |
IPulseOnlineAvatarService | Avatar pictures of users: pixels, an encoded image or an URL (Avatars). |
IPulseOnlineAchievementService | Achievements and stats of local users. |
IPulseOnlineServerAchievementService | Achievements written by a trusted server for any player. |
IPulseOnlineStatsService | Stats of local users (Stats and Leaderboards). |
IPulseOnlineServerStatsService | Stats written by a trusted server for any player. |
IPulseOnlineLeaderboardService | Leaderboard reads (top, around a user, friends, users). |
IPulseOnlineNetworkService | NAT type (Connection and Reconnect). |
IPulseOnlineModerationService | Player reports and sanctions (Chat and Safety). |
IPulseOnlineBlockListService | Block list of the platform. |
IPulseOnlineTitleStorageService | Title files (Cloud Storage). |
IPulseOnlineUserStorageService | User files in the cloud. |
IPulseOnlineEntitlementService | What a user owns (Entitlements and Store). |
IPulseOnlineStoreService | Store offers and checkout. |
IPulseOnlineVoiceBackend | Voice chat users and channels (PulseOnlineVoice). |
IPulseOnlinePartyMessageTransport | How party messages travel (module PulseOnlineParty); without one the beacon transport of the party runs (Party). |
IPulseOnlinePlatformService | A second platform under the main backend (Steam under EOS): login ticket, friends, presence, avatars, overlay invites (Platform Service). A backend keeps a list of platforms. |
IPulseOnlineMatchmakingService | Matchmaking tickets at a matchmaking service (Matchmaking). |
IPulseOnlineAntiCheatService | Anti-cheat: PreLogin check, clients, messages, violations (Anti-Cheat). |
IPulseOnlineUserContentService | User made content: list, subscribe, download, upload (User Content). |
A service a backend does not have is null; the feature then fails its requests with Pulse.Result.Failure.Online.NotSupported. Feature code gets a service with Pulse::Online::GetService<IPulseOnlineGameSessionService>(WorldContext).
Lobbies and game sessions are split by purpose, not by technology: a backend may build its game sessions on lobbies of its online service (EOS, OSSv2); bUseLobby of the create parameters stays a hint to the game session service. Both services take the same structs (FPulseOnlineSessionInfo, ...Snapshot, ...SearchParams, ...CreateSessionParams) and the local name of the session.
All asynchronous service calls take a completion (TFunction) that is called exactly once, sometimes right away.
Order of the services
When a backend starts, its services come in this order; a later service replaces an earlier one with the same name:
- the services of the backend (
OnInitializeBackend), - the extensions (
UPulseOnlineBackendExtension, lower priority first), except those in Disabled Extensions (Project Settings > Pulse > Online; e.g. the Steam extension of PulseOnlineSteam in a build without Steam), - the service providers: Service Overrides of the settings, then the overrides set at runtime with
UPulseOnlineBackendSubsystem::SetServiceOverride(they win and surviveSwitchBackend) (Service Providers).
Then OnServicesChanged fires. GetServiceSource(Name) says where a service comes from (Backend, Extension, Provider, Runtime for services registered later by game code), GetServiceProvider(Name) returns the provider of a service. An override whose provider serves another service than its key is skipped with an error in LogPulseOnline and reported by the Check step of the Pulse window.
Platforms are a list: RegisterService with a platform service adds it (a platform with the same GetPlatformName is replaced), GetService<IPulseOnlinePlatformService>() returns the first one (the order of the registration, so an extension with a higher priority comes later), GetPlatformService(Name) finds one by its name, GetPlatformServiceNames() lists them and UnregisterPlatformService(Name) removes one (Platform Service).
OSS backend
Uses the default online subsystem (DefaultPlatformService). Notes:
- Reservation beacons and the party beacon need a
BeaconNetDriverdefinition, see Getting Started. - OSSv1 has one session interface with one global search, so the backend keeps one session core (
FPulseOnlineOSSSessionCore) behind its two services,FPulseOnlineOSSLobbyServiceandFPulseOnlineOSSGameSessionService. The core binds the session delegates once and reports events, invites and overlay joins to the service of the session’s kind: a session created or joined through the lobby service, a session withPULSE_SESSION_TYPE“Party” or the nameNAME_PartySessionis a lobby, everything else a game session. A game session search leaves party lobbies out. Pulse Online runs every search in the session queue. - Party promotion under EOS needs
PulseOnlineEOS. - User files carry the hash of their cloud header as version and hash (EOS: MD5), no time of the last write; write conditions are checked by a list right before the write, so they are not atomic (Cloud Storage).
OSSv2 backend
The backend on Online Services v2 (UPulseOnlineBackendOSSv2, module PulseOnlineBackendOSSv2, priority 50) comes with the add-on plugin PulseOnlineOSSv2: identity, lobbies and game sessions, friends, presence, stats, leaderboards, title and user files and the store on UE::Online::IOnlineServices, with the lobby schemas GameLobby and PartyLobby. Its docs describe the setup and what each service maps to. Without the add-on, -PulseOnlineBackend=OSSv2 falls back to the automatic choice and the cheats PulseOnlineBackend OSSv2 and PulseOnlineGrant OSSv2 say that the add-on is missing.
Mock backend
The Mock backend keeps users, sessions, friends, presence, achievements, stats, storage files (with time, a version counter and SHA1, write conditions checked in the same step as the write), store offers and entitlements in a process wide mock world, draws a test avatar per user, simulates a second platform (Platform Service), keeps user content in folders (User Content) and has an empty anti-cheat (Anti-Cheat). Every game instance of the process (PIE instances, specs) sees the same world, so a PIE server can host and a PIE client can find and join it.
| Property | Default | Meaning |
|---|---|---|
LatencySeconds | 0 | Delay of every completion. < 0: complete synchronously, 0: next tick. |
AchievementIds | ACH_MOCK_1..3 | Achievements of the mock service. |
bEverybodyIsFriend | true | Every mock user is a friend of every other one. |
NatType | Open | NAT type of the mock network service. |
bAcceptMockNetIds | true | Registers the mock net id type (NULL) as compatible, so game modes accept Mock players. |
bMockPlatform | true | The simulated platform MockPlatform is available. |
bMockAvatars | true | Every mock user has a test avatar (a circle in a color of its own). False: no avatars, the widgets show initials. |
bMockAntiCheat | true | The mock anti-cheat runs: lets every player join, remembers its clients, logs. |
MockContentFolder | empty | Folder of the mock user content; empty: Saved/PulseOnline/MockContent. |
FailNextOperation(Operation, ErrorId) makes the next call of an operation fail: Login, Logout, Privilege, CreateSession, FindSessions, JoinSession, LeaveSession, UpdateSession (game sessions), CreateLobby, FindLobbies, JoinLobby, LeaveLobby, UpdateLobby (lobbies, also member data), Kick, Promote, Invite, Friends, Presence, Achievements, Stats, Leaderboard, Nat, Report, Sanctions, Block, Storage, Entitlements, Offers, Checkout, QueryAvatar, PlatformTicket, PlatformFriends, PlatformPresence, PlatformAvatar, AntiCheatPreLogin, AntiCheatRegister, ContentQuery, ContentSubscribe, ContentDownload, ContentUpload. AddMockSanction(UserId, Action, Minutes) gives a user a sanction, GetMockReports() returns the sent reports, AcceptMockPlatformInvite and SetMockLaunchJoinInfo drive the mock platform, SimulateOverlayJoin(PlatformUserId, Session) reports a join request to the lobby or game session service of the session, SetMockTitleFile(Name, Text) sets a title file, SetMockOffer and GrantMockEntitlement fill the store. ResetMockWorld clears the mock world (specs).
Mock users are called PulseMock_<instance>_<local user> (PIE instance number, or from 100 for other game instances). A login method with credentials of type mock (or no type) and an id logs in as that id instead; platform credentials (e.g. the EOS dev auth tool) are ignored, so a project default login method does not put every instance into one account. Like OSS and OSSv2 the Mock keeps one session core behind a lobby service and a game session service; every mock session remembers the service that created it, and its events, invites and overlay joins go to that service of every member. Mock sessions are joined by IP (127.0.0.1:<port of the host>). Two things make this work with platform net drivers:
- The game session service adds
?bUseIPSocketsto the listen URL, soNetDriverEOSlistens on IP sockets instead of waiting for an EOS user. bAcceptMockNetIdsavoids the PreLogin errorincompatible_unique_net_idwhen the default online subsystem is not Null.
To test sessions in PIE without accounts, start the editor with -PulseOnlineBackend=Mock or set Backend Class to PulseOnlineBackendMock in a local (not checked in) config.
Writing a backend or extending one
A backend derives from UPulseOnlineBackend, answers IsBackendAvailable and GetPriority, and registers its services in OnInitializeBackend with RegisterService. Services implement the interfaces above (PULSE_ONLINE_SERVICE gives them their name) and unbind their delegates in Shutdown.
An extension (UPulseOnlineBackendExtension) is found automatically (unless the settings name it in Disabled Extensions). If ShouldExtend(Backend) returns true, ExtendBackend may register more services or replace one, e.g. a voice backend:
UCLASS()
class UMyBackendExtension : public UPulseOnlineBackendExtension
{
GENERATED_BODY()
public:
virtual bool ShouldExtend(const UPulseOnlineBackend* InBackend) const override
{
return InBackend->IsA<UPulseOnlineBackendOSS>();
}
virtual void ExtendBackend(UPulseOnlineBackend* InBackend) override
{
InBackend->RegisterService(MakeShared<FMyVoiceBackend>());
}
};
Extensions are C++. To serve a service from Blueprint, use a service provider (Service Providers).
A backend of your own registers two session services, a lobby service and a game session service (they may share one inner object, as OSS, OSSv2 and the Mock do). To replace only the lobby service of the OSS backend (lobby promotion, as PulseOnlineEOS and PulseOnlineSteam do), derive from FPulseOnlineOSSLobbyService and register it on the session core, so its delegates stay bound once:
if (const TSharedPtr<FPulseOnlineOSSSessionCore> core = FPulseOnlineOSSSessionCore::Find(InBackend))
{
const TSharedRef<FMyLobbyService> lobbies = MakeShared<FMyLobbyService>(core.ToSharedRef());
core->SetLobbyService(lobbies);
InBackend->RegisterService(lobbies);
}
Session data that only the backend understands (search results, lobbies) travels in FPulseOnlineSessionInfo::BackendData; GetBackendType lets a backend reject data of another backend after a switch.