Party / Lobby

Concept

The party is an online lobby (NAME_PartySession), created, joined, left and changed directly through the lobby service of the backend (IPulseOnlineLobbyService: an EOS lobby with the OSS backend, ILobbies with OSSv2 (add-on PulseOnlineOSSv2), a mock lobby with Mock); the game it plays is a game session (Sessions). It lives in the online service, not in a world:

  • Party members are not connected through the game network. Every client builds the party scene itself in its own menu world, from the member data. Joining, leaving, changing the character or the leader never travels anywhere.
  • The world changes exactly once: when the party enters the match, because the match runs on another server.
  • The party survives map travel and the match. After the match everybody is still in the same party.

UPulseOnlinePartySubsystem keeps the party state up to date and broadcasts what changed: OnPartyJoined, OnPartyLeft, OnPartyMembersChanged, OnPartyMemberDataChanged(Member), OnPartyDataChanged, OnPartyLeaderChanged(Leader), OnPartyStateChanged(State), OnPartyMatchFound(MatchKey), OnPartyLobbyReady, OnPartyMessageReceived, OnPartyBeaconConnectionChanged.

State and data

  • GetPartyMembers(): FPulseOnlinePartyMember (net id, display name, leader, local, status Lobby/InMatch, match key, game Data). Stable order: local player first, then by net id, so each member has the same slot on every client.
  • Member data (SetLocalMemberData): every member writes its own data (character, ready state, cosmetics).
  • Party data (SetPartyData): the leader writes party wide attributes.
  • Existing keys that are not in the map stay unchanged. Keys starting with PULSE_ are reserved.

The party state comes from GetLobbySnapshot, member data goes through UpdateMemberSettings, party data through UpdateLobby, kick and promote through KickMember and PromoteMember of the lobby service.

How a member data update works (OSSv1 / EOS): the lobby service copies the party session settings, writes the values into MemberSettings[LocalId] and calls UpdateSession of OSSv1. EOS turns that into EOS_Lobby_UpdateLobbyModification + AddMemberAttribute + EOS_Lobby_UpdateLobby (a backend call). Non-owners only send their own member attributes. The other members get an EOS notification, the online subsystem fires OnSessionParticipantSettingsUpdated, Pulse Online compares old and new data and broadcasts OnPartyMemberDataChanged — also on the sender, once its update completed. Latency is one backend round trip; EOS rate-limits lobby updates, so use data for state, not for frequent events.

Messages

Events without a state change (emote, ping, “ready check”) go through the party transport. By default it is the party beacon: the leader hosts a beacon, every member connects automatically (party create/join, leader change, map travel). Messages are real RPCs — reliable and ordered (or unreliable), no backend rate limit, low latency. Messages go through the leader, which passes them on and sets the sender.

TMap<FName, FPulseOnlineSetting> payload;
payload.Add(TEXT("Id"), FPulseOnlineSetting::Make(TEXT("Wave")));
PartySubsystem->SendPartyMessage(TEXT("Emote"), payload);

Blueprint: Send an emote as party message

  1. Input action Emote → Make Map with Id = Make String Setting (“Wave”).
  2. Pulse Online Party Subsystem → Send Party Message (Type Emote, Payload = map, Reliable = true).

Blueprint: Receive the emote

  1. Event BeginPlay → Pulse Online Party Subsystem → Bind Party Message (Type Emote, Event = custom event OnEmote).
  2. OnEmote (Sender, Message) → Get Message Payload (Message) → Find String (Key Id).
  3. Sender → Net Id → find the spot of that member → play the montage for the emote id on its display character.

Blueprint: Send Party Message / Send Party Message To, receive with On Party Message Received(Sender, Message) or only one type with Bind Party Message(Type, Event). Read the payload with Get Message Payload(Message). The sender does not receive its own message. While the transport is (re)connecting or refuses a message, messages are kept in order (PartyBeaconMessageBufferSize, category Messages of the party settings, for every transport).

Recommendation: trigger an emote as message; if a later joiner must see it (a persistent pose, ready state), also store it as member data.

Party transport

IPulseOnlinePartyMessageTransport (module PulseOnlineParty) is how party messages travel. The party subsystem uses the transport the backend or an extension registers (RegisterService, e.g. lobby P2P of EOS or the lobby chat of a platform), otherwise the beacon transport (bUsePartyBeacon); without both there are no party messages (SendPartyMessage returns false). GetMessageTransport() returns the transport in use, PulseOnlineStatus names it. A transport registered later is picked up when the services of the backend change.

Part Who
UpdateParty(Context) The subsystem calls it on every party change: party id, lobby name, local user, leader, members, lobby attributes. An empty party id closes the transport.
SendMessage(Message, bReliable) The subsystem sends through it once the transport is connected. A message the transport refuses (false) is kept with every later one, so the order stays; they go out first on the next message, connection or party change.
OnConnectionChanged The transport reports its connection; the subsystem then sends the messages it kept (PartyBeaconMessageBufferSize, dropped after PartyBeaconReconnectTimeoutSeconds) in order, the same for every transport.
OnMessageReceived The transport hands over a message with its sender; the subsystem broadcasts it.
OnPublishLeaderAttributes The leader’s transport has lobby attributes for the members (the beacon address); the subsystem writes them into the party lobby.

The beacon transport hosts BeaconHostObjectClass and connects with BeaconClientClass of the party settings (defaults APulseOnlinePartyBeaconHostObject and APulseOnlinePartyBeaconClient), so a project can derive its own beacon classes. It publishes PULSE_PARTY_BEACON_URL (the address from GetOwnerAddress of the lobby service with the listen port), a new PULSE_PARTY_BEACON_SEQ and the beacon port, and members reconnect when the sequence or the leader changes.

Example: four characters in the lobby world

  1. Create a solo party after login, so friends can join through invites or the overlay:

    PartySubsystem->CreateParty(PlayerController);
    
  2. Lobby map with four spots (game code, e.g. ALobbySpot actors with a SlotIndex). Slot 0 is the local player.

  3. Character selection writes member data:

    TMap<FName, FPulseOnlineSetting> data;
    data.Add(TEXT("Character"), FPulseOnlineSetting::Make(TEXT("Knight")));
    data.Add(TEXT("Ready"), FPulseOnlineSetting::Make(false));
    PartySubsystem->SetLocalMemberData(PlayerController, data);
    
  4. Build the scene on OnPartyMembersChanged, OnPartyMemberDataChanged, OnPartyLeaderChanged and OnPartyLobbyReady: iterate GetPartyMembers() and spawn or update one purely local display character per spot (no replication), with leader crown and ready indicator:

    const TArray<FPulseOnlinePartyMember>& members = PartySubsystem->GetPartyMembers();
    for (int32 slot = 0; slot < Spots.Num(); ++slot)
    {
        if (members.IsValidIndex(slot))
        {
            const FPulseOnlinePartyMember& member = members[slot];
            Spots[slot]->ShowCharacter(UPulseOnlineSettingLibrary::FindString(member.Data, TEXT("Character"), TEXT("Default")),
                member.bIsLeader, UPulseOnlineSettingLibrary::FindBool(member.Data, TEXT("Ready"), false),
                member.Status == EPulseOnlinePartyMemberStatus::InMatch);
        }
        else
        {
            Spots[slot]->ShowEmpty();
        }
    }
    

    With MVVM, bind the spots / widgets to Members[i] of the party view model instead (see UI (MVVM)).

  5. Invites: UPulseOnlineSocialSubsystem::SendSessionInvite(Friend) invites into the party while the player is in one. The receiver accepts with AcceptInvite, which joins as party.

  6. Emotes: SendPartyMessage("Emote", {Id: Wave}); every client plays the montage on its local display character of the sender in On Party Message Received.

  7. Play: the leader calls StartMatchmaking. Members see the state Matchmaking, then the leader publishes the match and everybody travels. After the match ReturnToPartyLobby travels back to PartyLobbyMap; the party is still there, OnPartyLobbyReady fires and the scene is rebuilt. Members still in the match have the status InMatch.

Steps 1, 3 and 4 in Blueprint:

Blueprint: Create a solo party after login

  1. Event BeginPlay of the lobby (or after login) → Get Game Instance Subsystem (Pulse Online Party Subsystem).
  2. Is In Party → Branch false → Create Party (Owning Player = Get Player Controller).
  3. Return value → Execute Online Request → Failure: retry or show an error.

Blueprint: Character selection writes member data

  1. Character button On Clicked → Make Map (Name → Pulse Online Setting).
  2. Character: Make String Setting (“Knight”), Ready: Make Bool Setting (false).
  3. Pulse Online Party Subsystem → Set Local Member Data (Owning Player, Data = the map) → optional Execute Online Request.
  4. Other members get On Party Member Data Changed.

Blueprint: Build the lobby scene from the party members

  1. Event BeginPlay → Pulse Online Party Subsystem → Bind Event to On Party Members Changed, On Party Member Data Changed, On Party Leader Changed and On Party Lobby Ready, all to the custom event RebuildScene.
  2. RebuildScene → Get Party Members → For Each Loop (Array Index = slot).
  3. Per member: Break Pulse Online Party Member → Data → Find String (Key Character, Default Default) and Find Bool (Key Ready).
  4. Spots[Array Index] → Show Character (character, Is Leader, ready). Slots behind the last member → Show Empty.

Play together (co-op)

HostPartyGame(PlayerController, HostRequest) (UPulseOnlineHostPartyGameRequest) is the usual start of a co-op game with friends: when the player is in no party it makes a party of one first, then hosts the game without a search and publishes it as the match of the party (party matchmaking with bHostWithoutSearch), so every member follows the leader into his listen server. Leader only (a member gets “Only the party leader can start the game”). bTravel false publishes without travel; bCreatedParty tells whether the request made the party.

UPulseOnlineHostSessionRequest* host = Sessions->CreateHostSessionRequest(PlayerController);
host->Level = TSoftObjectPtr<UWorld>(FSoftObjectPath(TEXT("/Game/Maps/Island.Island")));
host->MaxPlayerCount = 4;
PartySubsystem->HostPartyGame(PlayerController, host);

Friends join through an invite (SendSessionInvite invites into the party) or the platform overlay (Steam, EOS: join the party lobby), also while the leader plays: with bFollowRunningMatchOnJoin (default on) a player who joins the party while the leader is in a match follows into that match. A player that joined the party from inside the match does not travel again. Off: only matches the leader starts later are followed (matchmaking games where the match may be full).

Who may join

PartyGameAccess of the party settings (Project Settings > Pulse > Online Party) decides who may join the game; a request may choose otherwise with bOverrideAccess and Access:

Access Game session Login on the host
PartyAndInvited (default) Not advertised: not in searches or the server browser, only private slots (EOS: a lobby with the permission JoinViaPresence), invites allowed. Only members of the host’s party and players the host invited (into the party or the game) get in; everybody else is refused in PreLogin with Pulse.Result.Failure.Online.NotInvited (“This game is only open to the host’s party and invited players.”), the text the player sees as the reason of the failed connection.
Public Advertised, anyone who finds it may join (as before). Everybody.

Friends that join the party later (invite, platform overlay) are party members and follow into the running game. SendSessionInvite remembers the invited player on the host (AddInvitedPlayer; call it yourself for invites the game sends another way). The check runs while the host is in the game session it hosted for the party (IsHostingPartyGame, CheckPartyGameLogin); the rule itself is Pulse::Online::Party::CheckGameJoin.

UPulseOnlineHostPartyGameRequest* request = PartySubsystem->CreateRequest<UPulseOnlineHostPartyGameRequest>(PlayerController);
request->HostRequest = host;
request->bOverrideAccess = true;
request->Access = EPulseOnlinePartyGameAccess::Public;
request->TryStart(PlayerController);

The leader publishes the backend id of the game with the match (PULSE_PARTY_MATCH_SESSION_ID); members find it by its id (FindSessionById of the game session service: OSS backend IOnlineSession::FindSessionById, Mock), so a game that is not advertised is found; backends without it (OSSv2, NULL) fall back to the key search, which only finds an advertised game. With PulseOnlineHUDBridge and the Pulse frontend the main menu has this as Play Together (see UI Widgets).

Matchmaking, follow and return

StartPartyMatchmaking (leader, session queue, cancellable):

  1. Party state Matchmaking.
  2. Search with MinOpenSlots = party size. Nothing found: host with the optional HostRequest, otherwise fail.
  3. Join without travel; the reservation beacon reserves slots for every member.
  4. Publish the match: PULSE_PARTY_MATCH_ID (the PULSE_SESSION_KEY of the match), PULSE_PARTY_MATCH_LOBBY, PULSE_PARTY_MATCH_ADDRESS (only for a server address without a session), PULSE_PARTY_MATCH_SESSION_ID (the backend id of the game session), PULSE_PARTY_MATCH_SEQ, state InMatch.
  5. Travel (bTravel, default on; off publishes only). On failure or cancel the state goes back to Idle.

Members see a new match sequence, OnPartyMatchFound fires (with the key, or the address) and with bAutoFollowPartyLeader a FollowPartyMatch request runs: find the match by its id (GetPartyMatchSessionId) or its key, join without reservation, travel; a match with only an address (GetPartyMatchAddress) is a plain travel there. The key search stays the fallback because OSSv1 EOS finds only lobbies by id.

ReturnToPartyLobby leaves the game session, resets the party state if the leader returns, and travels to PartyLobbyMap. With PartyReturnPolicy = FollowLeader members in the same match return automatically when the leader does. An involuntary match end (kick, server shutdown, travel failure) cleans up the game session; the party stays.

bRequireAllMembersInLobbyToMatchmake only allows matchmaking while every member is in the lobby.

For queues, rules and skill ratings use Matchmaking: its ticket runs this request for the whole party with a rule based search, and repeats it while the rules open up (bNoMatchFound tells a failed search from other failures). With a matchmaking service the leader holds the ticket for every member and hands the found match to this request: Match (join it without a search), MatchAddress (a server address: published, then everyone travels) or bHostWithoutSearch with a HostRequest; the match is then published to the party as usual. While the ticket waits the party is in the state Matchmaking (nobody joins); a member that leaves meanwhile ends the ticket (cancelled at the service, the request fails, the party goes back to Idle).

Create, join and leave of the party run in the party queue, not in the session queue: they come in order with the party data requests that follow them (member data right after a join), and OSSv1 shares only its session search between lobbies and game sessions, not the lobby calls. Match requests (start, follow, return) use the session queue.

Blueprint: Leader starts matchmaking

  1. Play button On Clicked → Pulse Online Party Subsystem → Can Start Matchmaking → Branch.
  2. True → Start Matchmaking (Owning Player, Search Request = Create Find Sessions Request, Host Request = Create Host Session Request) → Execute Online Request.
  3. Cancel button → Cancel Matchmaking.
  4. All members: On Party State Changed (State) → show “Searching…” while Matchmaking.

The party is lost when the game restarts or crashes (EOS removes the member when the connection closes).

Leader, kick, promote

  • The leader leaves: the service picks a new leader automatically (EOS host migration; SETTING_HOST_MIGRATION can turn that off). OnPartyLeaderChanged fires, the transport learns the new leader (the beacon transport starts the beacon on the new leader and the members reconnect).
  • KickMember (leader).
  • PromoteMember (leader): PromoteMember of the lobby service. OSSv2 uses PromoteLobbyMember, the Mock backend supports it, and with the OSS backend the PulseOnlineEOS bridge plugin replaces the lobby service with one that calls EOS_Lobby_PromoteMember (PulseOnlineSteam: SetLobbyOwner). Otherwise the request fails with Pulse.Result.Failure.Online.NotSupported. SETTING_HOST_MIGRATION cannot be used to promote a specific member, EOS picks the new owner itself.

The party on the game server

A game server sees players, not lobbies. So that it can keep a party together (one team, spawn points next to each other, the same squad when it balances teams), every client tells the server which party it is in:

  • Joining a session (Join, Quick Play, Rejoin, following the leader) adds ?PulsePartyId=<id> to the travel URL, and ?PulsePartyLeader=1 for the leader. The id is GetPartyId() of the party subsystem: the session id of the party lobby (escaped as %XX).
  • The server reads the options when the player logs in and keeps them on the player state, in a UPulseOnlinePartyStateComponent it adds to every player state (also after a seamless travel).
  • When the party changes during the match (somebody joins or leaves, a new leader), the client reports it with a server RPC. The host of a listen server and a standalone game set their own party directly.
Blueprint C++ Where
Get Player Party Id(PlayerState) Pulse::Online::GetPartyId Server; on a client only for its own player state
Is Player Party Leader(PlayerState) Pulse::Online::IsPartyLeader Server; on a client only for its own player state
Get Player Party Members(PartyId) Pulse::Online::GetPartyMembers Server: the active player states of one party
- Pulse::Online::ListsPartyMember(Voucher, Player) Server: whether another player of the party lists the player in its party lobby (see below)
On Player Party Changed(PlayerState, OldPartyId, NewPartyId, bLeader) OnPlayerPartyChangedNative Event of the party subsystem: on the server for every player, on a client for its own

The same change goes out on the message bus as Pulse.Message.Online.PlayerPartyChanged (payload FPulseOnlinePlayerPartyMessage, the player state is the player of the context). The component replicates to its owning client only, so the lobby ids of other parties never reach other players.

The id comes from the client and is not checked. Use it to group players, never for rights (kicking, admin commands, prices, ratings).

With the party every client also reports its own id in the party lobby (MemberId) and the ids of all lobby members (MemberIds, at most 64). Where a claim matters, check one player against another: ListsPartyMember(Voucher, Player) is true only if both report the same party, the voucher’s lobby lists the player’s member id, and no other player of that party claims the same member id. A client can make up any party id, but only a real member lists it. Pulse Quest’s party quests let a player into a party’s host this way.

Example: party members join the team of their party, in a game mode (teams of Pulse Foundation):

void AMyGameMode::HandleStartingNewPlayer_Implementation(APlayerController* NewPlayer)
{
	// The party of a joining player is known after PostLogin, before the pawn spawns
	const FString partyId = Pulse::Online::GetPartyId(NewPlayer->PlayerState);
	for (APlayerState* member : Pulse::Online::GetPartyMembers(GetWorld(), partyId))
	{
		if (member != NewPlayer->PlayerState)
		{
			Pulse::Team::SetTeam(NewPlayer->PlayerState, Pulse::Team::GetTeam(member));
			break;
		}
	}
	Super::HandleStartingNewPlayer_Implementation(NewPlayer);
}

After a seamless travel and for changes during the match the party arrives a moment later, through On Player Party Changed. With PulseQuest, the bridge PulseQuestOnlineBridge keeps one shared quest host per party on the server (party quests). With Pulse Build, the bridge PulseBuildOnlineBridge gives the members of a player’s party its building rights (the player’s client reports its party members; see the Pulse Build docs). bSharePlayerParties (Project Settings > Pulse > Online > Party) turns all of it off. The Online page of the Pulse Debugger lists the parties of the players under “Player parties”.

Alternative with a real game connection

If the lobby needs shared gameplay (physics, movement), the leader can be a listen server of the menu map and the members connect to it; later the whole group seamless-travels. Downsides: the leader must host (NAT / relay), and if it leaves everybody is disconnected. Not recommended for dedicated server games.

Presence and invites

The party has presence; game session joins are made without presence while in a party. Invites carry PULSE_SESSION_TYPE, so AcceptInvite and overlay joins join parties as party and everything else as game session.


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