Requests

Every online operation is a UPulseOnlineRequestBase. The request contains the whole logic of the operation; the subsystems only run requests one after another and provide shared state.

Lifecycle

NotStarted → Queued → InProgress → Success | Failed | Cancelled

  • TryStartRequest(WorldContext, OnComplete) checks the request (ValidateRequest, CheckRequest, then CanStartRequest) and hands it to the queue of its category. Returns false if it could not be queued; GetErrorText() says why.
  • ValidateRequest(OutContext) is public and Blueprint callable. It only checks the parameters of the request and needs no world, so it can be called before starting (e.g. to check user input). The reason ends up in FPulseOnlineRequestValidationContext::Error.
  • CheckRequest() is a Blueprint native event for the rules of the game (see Check Request).
  • The queue runs one request at a time (ExecuteRequest). The request ends with FinishRequest(Result) (the result of the backend), FinishRequestFrom(OtherRequest) (the answer of a sub-request) or FinishRequest(bSuccess, Error).
  • GetRequestResult() (Blueprint: Get Request Result) is the answer of the last run as an FPulseResult: success, or the reason with its text. A backend error has its reason (see Results as Pulse results), a request that failed on its sub-request has the reason of the sub-request, a cancelled or aborted one Pulse.Result.Failure.Cancelled, a timed out one .Timeout, one that could not start .Invalid with the text why, any other failure Pulse.Result.Failure.Online.Error with the text of the request. GetErrorText() keeps the text of the backend.
  • CancelRequest() always works while queued. While in progress only for requests that support it (searches, quick play, matchmaking).
  • In-progress requests time out after GetTimeoutSeconds() (default: DefaultRequestTimeoutSeconds). The timer uses the game instance timer manager, so it survives map travel.
  • A completed request can run again after ResetRequest().
  • Late online subsystem callbacks after a timeout or cancel are ignored.

Queues

Queue Owner Requests
Session UPulseOnlineSessionSubsystem Host, find, find by key, join, quick play, leave, party matchmaking / follow / return
Party UPulseOnlinePartySubsystem Create, join, leave, member data, party data, kick, promote (on the lobby service)
Local player (one per player) UPulseOnlineLocalPlayerSubsystem Login, logout, query friends, send invite, voice channels

Queues run independently: a friends query of player 2 does not wait for a session search of player 1.

Party requests that search or join game sessions run in the session queue, because the online subsystem can only run one session search at a time (OSSv1 EOS keeps one global search state).

Messages and debugging

Every queue also reports through the free base plugin PulseFoundation:

  • When a request finishes, the message Pulse.Message.Online.RequestCompleted (payload FPulseOnlineRequestMessage: request, queue name, success, error text, Result, duration) is broadcast on the message bus of the game instance, e.g. for error toasts without binding every request.
  • Every request is a span on the Timeline page of Tools > Debug > Pulse Debugger (source Online, category = queue name): one row and one bar from start to result, with duration and error. A request cancelled before it started is a single event.
  • The session and party subsystems are snapshot providers (category Online): the Live page shows the session state and the active and waiting requests of their queues.

Sub-requests

A running request can run other requests inline with ExecuteSubRequest(SubRequest, Callback):

  • The sub-request does not go through a queue, it runs in the slot of its parent, also when it belongs to another category. This can never deadlock.
  • The sub-request inherits the game instance and the owning player.
  • Cancelling or timing out the parent cancels the active sub-request; its callback is not called then.
  • A parent that fails because its sub-request failed ends with FinishRequestFrom(SubRequest): the reason of the sub-request becomes its own (quick play answers Full when the session it found is full).

Example: quick play runs Find → Join or Host; party matchmaking runs state update → Find → Join → publish. Sub-requests are made from the request class table.

Blueprint

  • Create a request with Create Pulse Online Request or with the factory functions of the subsystems (CreateHostSessionRequest, …). Create Pulse Online Request works like Construct Object from Class (the parameters are exposed on spawn), but creates the request through the subsystem of its category, so it gets the subsystem’s defaults (e.g. bUseLobbies from the settings). The node does not start the request.
  • Execute Online Request (async node) starts the request and continues on Success or Failure (cancelled counts as failure). The pins return the request; cast it to read results such as Results. On Failure, Get Request Result of the request says why (the reason with its text).
  • If the request is already queued or running, the node just waits for it.

Blueprint: Run any request with Execute Online Request

Blueprint: Create a request of an own class with Create Pulse Online Request

  1. Create Pulse Online Request → class e.g. My Host Session Request. The exposed pins (Owning Player, Map ID, Max Player Count, …) set the parameters; the subsystem fills its defaults first.
  2. Execute Online Request (Request = the new request).
  3. Success / Failure as usual.

Request class table

Request Classes (Project Settings > Pulse > Online, category Requests) maps a request class of Pulse Online to a class of the project: base class → class made instead (a child of the base, not abstract). Every request Pulse Online makes goes through this table: Create Request of every subsystem (also with a class you pass) and every sub-request (the search, join and host requests of Quick Play, the ratings, search, join and host requests of matchmaking, the requests of party matchmaking, follow and return). So a project changes the host request once, and Quick Play, matchmaking and party matchmaking host with it. Only a class named as a base is replaced, not its children. An entry whose class does not load or is no creatable child of its base is logged once (LogPulseOnline) and the base class is made; the Pulse Check (Check All) reports such an entry as an error with the base class it expects.

In C++ make requests with Pulse::Online::NewRequest<T>(Outer) (Online/PulseOnlineRequestLibrary.h) and resolve a class with Pulse::Online::ResolveRequestClass(Class), so own code follows the table too.

[/Script/PulseOnline.PulseOnlineSettings]
RequestClasses=(("/Script/PulseOnlineSession.PulseOnlineHostSessionRequest", "/Game/Online/BP_MyHostRequest.BP_MyHostRequest_C"))

Check Request

CheckRequest (Blueprint native event, returns an FPulseResult) runs after ValidateRequest and before CanStartRequest, also for sub-requests. Override it for rules of the game (a mode that needs a purchase, a party that must be full): a failure stops the request, its reason and text reach GetRequestResult unchanged (a failure without a reason gets Pulse.Result.Failure.Invalid). Call the parent first. The main hooks of the host, find and matchmaking requests are Blueprint native events as well (Sessions, Matchmaking).

Blueprint: Refuse a request in Check Request

  1. Blueprint child of Pulse Online Host Session Request → override Check Request (Blueprint native event, returns a Pulse Result).
  2. Parent: Check Request → Is Success → Branch; False → return the parent’s result.
  3. True → the rule of the game (e.g. Has Entitlement of the commerce subsystem) → Branch; False → return Make Pulse Failure (Reason of your game, Message empty so the text of the reason shows).
  4. True → return Make Pulse Success. Project Settings > Pulse > Online > Request Classes: Pulse Online Host Session Request → the Blueprint.

Own request classes

Every subsystem function that creates a request takes an optional RequestClass (null = the default class); the Blueprint output pin has the type of the selected class. This lets a game use a subclass (e.g. a host request that adds own travel options) and still get the defaults of the factory:

  • UPulseOnlineSessionSubsystem: CreateHostSessionRequest, CreateFindSessionsRequest, CreateJoinSessionRequest, CreateQuickPlayRequest, CreateLeaveSessionRequest.
  • UPulseOnlinePartySubsystem: CreateParty, JoinParty, LeaveParty, SetLocalMemberData, SetPartyData, KickMember, PromoteMember, StartMatchmaking, FollowPartyMatch, ReturnToPartyLobby (these also start the request).
  • UPulseOnlineSocialSubsystem: QueryFriends, SendSessionInvite (start the request).
  • UPulseOnlineUserSubsystem: LoginUser, LogoutUser (start the request).
  • UPulseOnlineVoiceSubsystem: JoinGameChannel, LeaveGameChannel (start the request).

The session, party and local player subsystems also have a generic CreateRequest(OwningPlayer, RequestClass) that creates any request of their category without starting it. UPulseOnlineRequestLibrary::CreateRequest picks the subsystem from the class (UPulseOnlineRequestBase::CreateRequestOfThisClass); the Blueprint node uses it.

In C++ every factory has a template version that returns the given type:

UMyHostSessionRequest* host = SessionSubsystem->CreateHostSessionRequest<UMyHostSessionRequest>(PlayerController);
UMyJoinPartyRequest* join = PartySubsystem->JoinParty<UMyJoinPartyRequest>(PlayerController, SearchResult);

C++

UPulseOnlineFindSessionsRequest* search = SessionSubsystem->CreateFindSessionsRequest(PlayerController);
search->OnRequestCompleteNative.AddWeakLambda(this, [this](UPulseOnlineRequestBase* InRequest, bool bInSuccess)
{
	const UPulseOnlineFindSessionsRequest* completed = CastChecked<UPulseOnlineFindSessionsRequest>(InRequest);
	// completed->Results
});
search->TryStart(PlayerController);

Results as Pulse results

Online operations answer with FPulseOnlineResult (success, an error id of Pulse::Online::Errors or of the backend, and a text). Pulse::Online::ToResult(Result) (Blueprint: To Pulse Result) turns it into the FPulseResult every Pulse plugin answers with: the common ids become reasons of Pulse Foundation (InvalidParams: Invalid, Cancelled, Timeout, NotFound, AlreadyPending: Busy, NotAuthorized: Authority) or of the online layer (Pulse.Result.Failure.Online.NotSupported, .NotLoggedIn, .Full, .PrivilegeMissing; .NotInvited refuses a player at the login of a game hosted for the party), each with a text a project can replace (Project Settings > Pulse > Foundation > Result Texts); any other error id of a backend becomes Pulse.Result.Failure.Online.Error with the text of the backend as its message. The online result is the details of the Pulse result.

Requests (GetRequestResult), the node Login Pulse Online User, GetLastError of a user, the session events and the message of a finished request answer with this Pulse result already; the services of the backends keep FPulseOnlineResult.

Writing own requests

Derive from the category base (UPulseOnlineSessionRequest, UPulseOnlinePartyRequest, UPulseOnlineLocalPlayerRequest), or from UPulseOnlineRequestBase with an own EnqueueRequest.

  • ExecuteRequest(): start the operation; call FinishRequest synchronously or from the callback, with the result of the service (FinishRequest(Result)), so its reason reaches GetRequestResult().
  • OnRequestFinished(FinalState): unbind online subsystem delegates (runs for success, failure, cancel and timeout).
  • ValidateRequest: parameter checks without world or online services (missing search result, empty key, …). Call Super first. Also runs for sub-requests.
  • CheckRequest_Implementation: rules of the game, answering with an FPulseResult.
  • CanStartRequest: runtime checks before queueing that need the world context (local player, party state, …).
  • CanCancelWhileInProgress / OnCancelInProgress: support cancellation.
  • ResetRequestInternal: clear results for reuse.

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