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:

  1. the command line -PulseOnlineBackend=<Name> (OSS, Mock, OSSv2 with the add-on, or a class name),
  2. otherwise Backend Class in Project Settings > Pulse > Online,
  3. 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 DefaultPlatformService in [OnlineSubsystem], so the Null subsystem runs;
  • DefaultPlatformService=Null;
  • a configured service that did not start (e.g. EOS with its plugin disabled, [OnlineSubsystemEOS] bEnabled=False or 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:

  1. the services of the backend (OnInitializeBackend),
  2. 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),
  3. the service providers: Service Overrides of the settings, then the overrides set at runtime with UPulseOnlineBackendSubsystem::SetServiceOverride (they win and survive SwitchBackend) (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 BeaconNetDriver definition, see Getting Started.
  • OSSv1 has one session interface with one global search, so the backend keeps one session core (FPulseOnlineOSSSessionCore) behind its two services, FPulseOnlineOSSLobbyService and FPulseOnlineOSSGameSessionService. 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 with PULSE_SESSION_TYPE “Party” or the name NAME_PartySession is 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 ?bUseIPSockets to the listen URL, so NetDriverEOS listens on IP sockets instead of waiting for an EOS user.
  • bAcceptMockNetIds avoids the PreLogin error incompatible_unique_net_id when 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.


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