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::ShouldWaitForStartInputreturns the setting Wait For Start Input (bWaitForStartInput, Project Settings > Pulse > Online). Set it per platform in the platform’sGame.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 Inputstops 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):
- The platform user has a local player: a login key logs it in, unless it is logged in or logging in.
- 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.
- Otherwise a new player key adds a local player for the platform user (
UGameInstance::CreateLocalPlayerwith a player controller, on a client through a split screen join) and logs it in, up to the maximum. - 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
- The user goes to
LoggingIn. - 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 reasonPulse.Result.Failure.Online.PrivilegeMissing(error idPulse.Online.PrivilegeMissing). - The net id is stored on the local player (
ULocalPlayer::SetCachedUniqueNetId), so travel URLs, player states and the other features see it. - The user goes to
LoggedInOnlineorLoggedInLocal(orFailedwithGetLastError).
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.