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, thenCanStartRequest) 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 inFPulseOnlineRequestValidationContext::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 withFinishRequest(Result)(the result of the backend),FinishRequestFrom(OtherRequest)(the answer of a sub-request) orFinishRequest(bSuccess, Error). GetRequestResult()(Blueprint: Get Request Result) is the answer of the last run as anFPulseResult: 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 onePulse.Result.Failure.Cancelled, a timed out one.Timeout, one that could not start.Invalidwith the text why, any other failurePulse.Result.Failure.Online.Errorwith 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(payloadFPulseOnlineRequestMessage: 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.bUseLobbiesfrom 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
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.Execute Online Request(Request = the new request).- 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
- Blueprint child of
Pulse Online Host Session Request→ overrideCheck Request(Blueprint native event, returns a Pulse Result). Parent: Check Request→Is Success→ Branch; False → return the parent’s result.- True → the rule of the game (e.g.
Has Entitlementof the commerce subsystem) → Branch; False → returnMake Pulse Failure(Reason of your game, Message empty so the text of the reason shows). - 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; callFinishRequestsynchronously or from the callback, with the result of the service (FinishRequest(Result)), so its reason reachesGetRequestResult().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, …). CallSuperfirst. Also runs for sub-requests.CheckRequest_Implementation: rules of the game, answering with anFPulseResult.CanStartRequest: runtime checks before queueing that need the world context (local player, party state, …).CanCancelWhileInProgress/OnCancelInProgress: support cancellation.ResetRequestInternal: clear results for reuse.