Users and Login

Every local player has a Pulse Online user (UPulseOnlineUser). A user is logged in either online (it has a net id of the online service and its privileges) or locally (local play without the online service). All other features act for a logged in user: sessions, party, friends, presence, achievements, voice.

Logging in from Blueprint

Use the node Login Pulse Online User (category *Pulse Online User*):
Pin Meaning
Player Controller The local player that logs in.
bOnline True: log in to the online service. False: local play only.
Login Method How to log in (see below). Empty: the default method of the settings, or Local Only if bOnline is false.
Logged In / Failed Exec outputs with the User and the Result (FPulseResult: success, or the reason with its text; the online result of the backend is its details).

A player that is logged in already continues on Logged In right away. On Failed, show Get Display Text of the result to the player and offer to play offline (log in again with bOnline false):

Event On Activated
  -> Login Pulse Online User (Owning Player, bOnline = true)
       Logged In -> continue to the main menu
       Failed    -> Show Modal And Wait ("Login failed: {Get Display Text(Result)}", "Play offline", "Quit")
                      Confirmed -> Login Pulse Online User (Owning Player, bOnline = false) -> continue
                      Cancelled -> Quit Game

The node runs a UPulseOnlineLoginRequest through UPulseOnlineUserSubsystem::LoginUser. Use that function (or the generic Execute Request node) when you need a request subclass or want to wait for the request yourself.

“Press any key” screens

Consoles usually wait for a key press before the first login, so the player who pressed the key is logged in. Pulse Online has these helpers for that:

  • UPulseOnlineUserSubsystem::ShouldWaitForStartInput returns the setting Wait For Start Input (bWaitForStartInput, Project Settings > Pulse > Online). Set it per platform in the platform’s Game.ini.
  • Listen For Login Input (ListenForLoginInput, below) logs the pressing player in right away and adds split screen players.
  • The node Wait For Start Input only fires Pressed with the key and the platform user once any key (or one of the given Keys) is pressed; the login is up to you. The key is not consumed. Cancel Wait For Start Input stops all running waits of the game instance, e.g. in On Deactivated of the start screen.

Log in by key press and split screen

UPulseOnlineUserSubsystem::ListenForLoginInput(Params) listens to the key presses of all input devices until StopListeningForLoginInput and logs the pressing player in. Every input device belongs to a platform user (on PC with the default input device mapping, keyboard, mouse and the first gamepad belong to the first one and every further gamepad to one of its own; on consoles it is the account signed in on the controller). A press does this (Pulse::Online::DecideLoginInput):

  1. The platform user has a local player: a login key logs it in, unless it is logged in or logging in.
  2. Otherwise, while the first local player is not logged in, a login key lets it take the platform user of the device and logs it in: whoever presses first is player one.
  3. Otherwise a new player key adds a local player for the platform user (UGameInstance::CreateLocalPlayer with a player controller, on a client through a split screen join) and logs it in, up to the maximum.
  4. Everything else does nothing. Keys are not consumed.
FPulseOnlineLoginInputParams Default Meaning
LoginKeys empty Keys that log a player in; empty: every key, mouse button and gamepad button (no axes, no touch).
NewPlayerKeys empty Keys that add a local player on a device without one, e.g. Gamepad Special Right (Start); empty: no split screen.
MaxLocalPlayers 0 New player keys add players up to this number; 0: MaxSplitscreenPlayers of the game viewport.
bOnline true Online login, or local play only.
LoginMethod empty How to log in; empty: Default Login Method of the settings (Local Only when bOnline is false).
bStopAfterFirstLogin false Stops listening once the first login started (“Press any key”).

OnLoginInputHandled (native and Blueprint: local player, action, key, login request) tells what a press did; the request is null when the login could not start. IsListeningForLoginInput tells whether it listens; a new call replaces the running listener. The listener stays across level changes: stop it when the screen closes. Use LoginLocalPlayer(LocalPlayer, ...) to log a player in without a player controller yourself.

Start screen: On Activated
  -> Listen For Login Input (Login Keys = {}, New Player Keys = {Gamepad Special Right}, Max Local Players = 2)
On Login Input Handled (Local Player, Action, Key, Request)
  -> show "Player <index> joined", wait for the Request
Start screen: On Deactivated -> Stop Listening For Login Input

Split screen also needs Use Splitscreen in Project Settings > Maps & Modes, and the game must handle more than one local player (HUD per player, input per player controller).

Login methods

The login method is an instanced struct (FPulseOnlineLoginMethod), so projects and bridges add their own:

Method Module What it does
Auto Login PulseOnline The backend decides: command line credentials, a saved token or the platform account. Default.
Credentials PulseOnline Fixed Type, Id, Token as the backend expects them.
Local Only PulseOnline No online identity. Offline sessions still work.
Steam, Steam Web API Ticket PulseOnlineSteam The running Steam client; a ticket of the Steam account for an own backend.
EOS Account Portal, EOS Persistent Auth, EOS Dev Auth Tool, EOS Exchange Code, EOS External Auth, EOS Platform Ticket PulseOnlineEOS The EOS login types; Platform Ticket asks the platform (Steam) for its ticket. Dev Auth Tool takes the host, a credential name (default: -DevAuthName=<Name> or Player<PIE instance>) and optionally one credential name per PIE instance (PIECredentialNames).

An own method derives from FPulseOnlineLoginMethod and overrides BuildCredentials (and IsOnlineLogin for a local method). A method that has to wait for something, such as a login ticket of the platform, overrides BuildCredentialsAsync instead; the login request always calls that one, and its default calls BuildCredentials:

USTRUCT(BlueprintType, meta = (DisplayName = "My Token Login"))
struct FMyTokenLogin : public FPulseOnlineLoginMethod
{
	GENERATED_BODY()

	virtual bool BuildCredentials(const FPulseOnlineLoginContext& InContext, FPulseOnlineCredentials& OutCredentials, FText& OutError) const override
	{
		OutCredentials.Type = TEXT("externalauth");
		OutCredentials.Token = LoadMyToken();
		return !OutCredentials.Token.IsEmpty();
	}
};

The default method for requests without an own method is Default Login Method in the settings. Methods of other modules (PulseOnlineEOS) are read again after engine start, so they can be set there too.

For PIE tests with EOS accounts, put the Dev Auth Tool method into a local, not checked in config, one account per PIE window:

[/Script/PulseOnline.PulseOnlineSettings]
DefaultLoginMethod=/Script/PulseOnlineEOS.PulseOnlineLoginMethod_EOSDevAuthTool(Address="localhost:8081",PIECredentialNames=("Player0","Player1"))

What a login does

  1. The user goes to LoggingIn.
  2. Online logins call the identity service of the active backend (see Backends) and then query the required privileges of the request (RequiredPrivileges, default Can Play Online). A missing privilege fails the login with the reason Pulse.Result.Failure.Online.PrivilegeMissing (error id Pulse.Online.PrivilegeMissing).
  3. The net id is stored on the local player (ULocalPlayer::SetCachedUniqueNetId), so travel URLs, player states and the other features see it.
  4. The user goes to LoggedInOnline or LoggedInLocal (or Failed with GetLastError).

Logins time out after Login Timeout Seconds (180 s by default; the EOS account portal waits for the browser). bReuseExistingLogin (default true) lets a request finish right away for a user that is logged in already.

Users and lookups

UPulseOnlineUserSubsystem (game instance) keeps one user per local player:

Function Returns
GetUsers, GetPrimaryUser All users, the first local player’s user.
FindUserForLocalPlayer, FindUserForPlayerController, FindUserByNetId, FindUserByPlatformUserId One user.
IsLocalNetId Whether a net id belongs to a local user.
GetServerNetId The identity of a dedicated server (backends that have one), invalid on clients.
GetConnectionStatus Connected, connection lost, service unavailable.
LoginUser, LogoutUser Start a login / logout request.
LoginLocalPlayer Start a login for a local player without a player controller.
ListenForLoginInput, StopListeningForLoginInput, IsListeningForLoginInput Log in by key press, add split screen players.
QueryPrivilege Ask the backend again for one privilege.

UPulseOnlineUser has GetLoginState, IsLoggedIn, IsLoggedInOnline, GetNetId, GetDisplayName, GetPlatformUserId, GetLocalUserNum, GetPrivilegeResult / HasPrivilege and GetLastError (why the last login or privilege check failed, as an FPulseResult; in C++ GetLastOnlineError has the error id of the backend).

Privileges: Can Play, Can Play Online, Can Communicate Via Text, Can Communicate Via Voice, Can Use User Generated Content, Can Use Cross Play.

Events and messages

The subsystem has native and Blueprint events:

Event When
OnLoginStateChanged The login state of a user changed.
OnPrivilegeChanged A privilege query returned a different answer.
OnUserLoggedOutUnexpectedly The backend logged a user out without a logout request (token expired, account signed out).
OnConnectionStatusChanged The connection to the online service changed.
OnLoginInputHandled ListenForLoginInput logged a player in, let player one take a device or added a player.

The message bus of PulseFoundation gets Pulse.Message.Online.User.LoginStateChanged (payload FPulseOnlineUserLoginMessage), so other plugins can react without depending on Pulse Online.

Dedicated servers

Dedicated servers have no local players and no users. They act with the server identity of the backend (GetServerNetId); session and achievement requests on the server use it automatically.


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