Party Tasks #

Party features are built and customized using a combination of calls and plugin methods. This page describes common party operations, along with descriptions of SDK actions and related Party Plugin methods.

Prerequisites

Party player management

Party data and configuration

Party lifecycle

For a full list of all available Party SDK and plugin functions, see Party Reference.

Initialize the Party SDK (Required) #

Before you can use the Party API with the Unreal or Unity SDK, you must initialize the Party service using the Party API Initialize method. This step will synchronize party states between the SDK and the Pragma backend so that newly created SDK sessions can correctly determine what party a player is in, if any.

Initialize() can only be called after login. Upon logout, the service is un-initialized and the On* action-handlers are unbound. You must call initialize() on the service when you log back in.
Player->PartyApi().Initialize(
  const FOnCompleteDelegate& OnComplete
);

player.PartyApi.Initialize(
   PragmaId inviteePlayerId,
   CompleteDelegate onComplete
);

If the player is already in a party on the platform side when they login (such as when a disconnect/reconnect occurs), calling initialize() will fire the GameLoopApi notifications related to joining a new party because, to the client, the player is going from not in a party to in a party.

When the OnComplete callback to Initialize() fires, calling the GetPartyState() returns an IPragmaPartyState* object that can be used to determine the state of the user’s party.

While the Pragma SDK constantly attempts to stay in sync with the Pragma Engine backend, there may be instances where you want to explicitly force the SDK party cache to sync with the backend data. To forcibly synchronize the client’s state with the platform, call the Unreal Party API ForceSync function.

Create a party #

Create a party and add first player as leader

Create a party

The party creation process uses the CreateParty SDK function as well as the Party Plugin initializeParty and onAddPlayer methods.

First, the player client calls the Pragma SDK CreateParty function. The CreateParty function includes the following data:

  • ExtCreateRequest: Use this payload to specify custom party data that the platform needs to know when a party is being created. For example, you may want the user to select certain party preferences. This data will be stored on the ExtParty payload.
  • ExtPlayerJoinRequest: Use this payload to specify custom player data, such as a selected champion, to pass to the onAddPlayers method when a player is added to a party. This data will be stored on the ExtPartyPlayer payload.
  • preferredGameServerZones:(optional) preferred game server zones. You can change this value later (see SetPartyPreferredGameServerZones).
  • gameServerZoneToPing: (optional) a ping map. You can change this value later (see SetPartyPlayerGameServerZoneToPing).
Player->PartyApi().CreateParty(
  FPragma_Party_ExtCreateRequest& ExtCreateRequest,
  FPragma_Party_ExtPlayerJoinRequest& ExtPlayerJoinRequest,
  TArray<FString>& PreferredGameServerZones,
  TMap<FString, int32>& GameServerZoneToPing,
  FOnCompleteDelegate& OnComplete
);

player.PartyApi.CreateParty(
  ExtCreateRequest extCreateRequest, 
  ExtPlayerJoinRequest extPlayerJoinRequest,
  List<string> preferredGameServerZones,
  Dictionary<string, int> gameServerZoneToPing,
  CompleteDelegate onComplete
);

  {
    "requestId": 1,
    "type": "PartyRpc.CreateV1Request",
    "payload": {
      "createRequestExt":{},
      "playerJoinRequestExt":{},
      "gameClientVersion":"gameClientVersion1",
      "preferredGameServerZones": [ "gameServerZone1", "gameServerZone2" ],
      "gameServerZoneToPing": { "gameServerZone1": 10, "gameServerZone2": 20 }
    }
  }

After issuing CreateParty, the Party service creates a new party and uses data in ExtCreateRequest to customize the initial party state.

After the Party service creates the empty party, it adds the player that created the party to the party, assigns them the leader role, and invokes onAddPlayer to apply customization options.

If a player is in a party when they attempt to make a new party, the player is removed from the existing party. To learn more about what happens when a player is removed, see Leave a party.

Related events:

Related errors:

Send a party invite #

Players invite other players to the party

Send an invite

One way that players can join a party is through party invites. Party invites are sent using the Party.Party.sendInvite() method on the Party interface. No invite is sent until this method is called. Party.Party.sendInvite() can be called from any Party Plugin method.

interface Party {
  fun sendInvite(
    inviterPlayerId: PlayerId, 
    inviteePlayerId: PlayerId
  )
}

To facilitate sending an invitation through the Party API for Unreal and Unity, use PartyApi.SendPartyInvite:

Player->PartyApi().SendPartyInvite(
  const FString& PlayerId,
  const FOnInviteSentDelegate& OnComplete
);

player.PartyApi.SendPartyInvite(
  PragmaId inviteePlayerId,
  CompleteDelegate onComplete
);

{
  "requestId": 2,
  "type": "PartyRpc.SendInviteV1Request",
  "payload": {
    "inviteePlayerId": "f9525239-cd99-425d-9f14-1ff948c02553"
  }
}

PartyApi.SendPartyInvite() calls the Party Plugin’s handlePlayerSendInviteRequest() method, which you can customize to allow/disallow a player to send a party invite. By default, handlePlayerSendInviteRequest() calls Party.Party.sendInvite():

suspend fun handlePlayerSendInviteRequest(
 party: Party.Party,
 requestingPlayer: Party.PartyPlayer,
 inviteePlayerId: PlayerId
) {
    party.sendInvite(requestingPlayer.playerId, inviteePlayerId)
}

The player who receives the invite gets an OnPartyInviteReceived event.

If a player sends a party invite to another player who already has a pending invite from the first player, the original invite is revoked and replaced with the new invite. On the platform side, the revoking process is the same as the invite cancellation process (see Cancel party invite).

Related events:

Related errors:

Cancel a party invite #

Cancel a sent pending party invite

Players can cancel a sent party invite provided the invite has not yet been accepted or rejected (i.e. is still pending).

Cancel a sent party invite

Party invite cancellations are requested using the Party.Party.cancelInvite() method with the invite ID on the Party interface. No invite is canceled until this method is called. The Party.Party.cancelInvite() method can be called from any Party Plugin method.

interface Party {
  fun cancelInvite(
    inviteId: InviteId
  )
}

To facilitate cancelling an invitation through the Party API for Unreal and Unity, use PartyApi.CancelPartyInvite:

Player->PartyApi().CancelPartyInvite(
  const FString& InviteId, 
  const FOnCompleteDelegate& OnComplete
);

player.PartyApi.CancelPartyInvite(
  PragmaId inviteId,
  CompleteDelegate onComplete
);

PartyApi.CancelPartyInvite() calls the Party Plugin’s handlePlayerCancelInviteRequest() method, which you can customize to allow/disallow a player to cancel a party invite. By default, handlePlayerCancelInviteRequest() calls Party.Party.cancelInvite() with the invite ID if the requesting player is the inviter or the party leader:

suspend fun handlePlayerCancelInviteRequest(
    party: Party.Party,
    requestingPlayer: Party.PartyPlayer,
    invite: Party.PartyInvite
) {
    if (invite.inviter.playerId != requestingPlayer.playerId || !requestingPlayer.isLeader) {
        partyApplicationError(
            PragmaError.PartyService_CancelInviteFailed,
            "Player '${requestingPlayer.playerId}' cannot cancel invite '${invite.id}'. A party invite can only be canceled by the inviter or a leader of the party.")
    }

    party.cancelInvite(invite.id)
}

The player who originally received the invite gets an OnReceivedPartyInviteCancelled event and the invite is removed from their pending party invite list.

Related events:

Related errors:

Get pending party invites #

View list of pending party invites

When a player logs in, synchronizes party data, receives or responds to an invite, or joins a party, all of their received party invites will be updated from the platform. This allows players to view received party invites after crashing or missing a notification. To view a list of currently pending party invites, use the Party API GetPendingPartyInvites() method, which returns the player’s party invite cache.

Player->PartyApi().GetPendingPartyInvites();

player.PartyApi.GetPendingPartyInvites();

Join a party #

Players join parties

Join a party

Players can join an existing party by responding to an invite (RespondToPartyInvite), joining with an invite code (JoinPartyWithInviteCode), or joining using the party ID (JoinPartyWithId). The Party service invokes the Party Plugin onAddPlayer method to apply party customization.

If a player is in a party when they attempt to join a new party, the player is removed from the existing party. To learn more about what happens when a player is removed, see Leave a party.

Respond to an invite #

The RespondToPartyInvite call determines whether the player will join the party they’ve been invited to.

This request contains the following information:

  • ExtPlayerJoinRequest: Use this payload to specify custom player data, such as a selected champion, to pass to the onAddPlayers method when a player is added to a party. This data will be stored on the ExtPartyPlayer payload
  • InviteID: the invite ID including in the SendPartyInvite call
  • true or false: boolean stating whether the player accepts (true) or declines (false) the invite
  • gameClientVersion: (optional) game client version, which is used to calculate compatible game servers
  • gameServerZoneToPing: (optional) a ping map. You can change this value later (see SetPartyPlayerGameServerZoneToPing).
Player->PartyApi().RespondToPartyInvite(
  const FPragma_Party_ExtPlayerJoinRequest& ExtPlayerJoinRequest,
  const FString& InviteId,
  const bool Accepted,
  const FOnCompleteDelegate& FOnCompleteDelegate
);

player.PartyApi.RespondToPartyInvite(
  ExtPlayerJoinRequest extPlayerJoinRequest,
  PragmaId inviteId,
  bool accepted,
  CompleteDelegate onComplete
);

{
  "requestId": 3,
  "type": "PartyRpc.RespondToInviteV1Request",
  "payload": {
    "requestExt":{},
    "inviteId":"89962f84-7edd-45b9-97c0-b6fd49fc8497",
    "accepted":true,
    "gameClientVersion":"gameClientVersion1"
  }
}

Join by party invite code #

A user can join an existing party by providing a valid invite code. For example, a player may want to join a party with an invite code they received from a player via Discord.

After an invite code is obtained, the player client calls the JoinPartyWithInviteCode SDK function.

Party invite codes are case sensitive. Ensure the code you issue in the join request uses the same capitalization as the invite code generator. The Pragma Engine default code generator uses a combination of numbers and capital letters. Inconsistent capitalization could lead to routing errors.

The JoinPartyWithInviteCode function accepts the following information:

  • ExtPlayerJoinRequest: Use this payload to specify custom player data, such as a selected champion, to pass to the onAddPlayers method when a player is added to a party. This data will be stored on the ExtPartyPlayer payload
  • inviteCode: invite code obtained by the player joining the party
  • gameServerZoneToPing: (optional) a ping map. You can change this value later (see SetPartyPlayerGameServerZoneToPing).
    Player->PartyApi().JoinPartyWithInviteCode(
  const FPragma_Party_ExtPlayerJoinRequest& ExtPlayerJoinRequest,
  const FString& InviteCode,
  const TMap<FString, int>& GameServerZoneToPing,
  const FOnCompleteDelegate& OnComplete
);

    player.PartyApi.JoinPartyWithInviteCode(
  ExtPlayerJoinRequest extPlayerJoinRequest,
  string inviteCode,
  Dictionary<string, int> gameServerZoneToPing,
  CompleteDelegate onComplete
);

    {
  "requestId": 4,
  "type": "PartyRpc.JoinWithInviteCodeV1Request",
  "payload": {
    "requestExt":{},
    "inviteCode":"CDCLGP",
    "gameClientVersion":"gameClientVersion1"
  }
}

Join by party ID #

A user can join an existing party by providing a valid party ID. This could happen if you want a player to be able to join a party by right-clicking on a player to join their party without an invite.

To join by party ID, the player client calls the Api JoinPartyWithId SDK function, which accepts the following information:

  • ExtPlayerJoinRequest: Use this payload to specify custom player data, such as a selected champion, to pass to the onAddPlayers method when a player is added to a party. This data will be stored on the ExtPartyPlayer payload
  • partyId: party ID of the party the player is attempting to join
  • gameServerZoneToPing: (optional) a ping map. You can change this value later (see SetPartyPlayerGameServerZoneToPing).
    Player->PartyApi().JoinPartyWithId(
  const FPragma_Party_ExtPlayerJoinRequest& ExtPlayerJoinRequest,
  const FString& PartyId,
  const TMap<FString, int>& GameServerZoneToPing,
  const FOnCompleteDelegate& Delegate
);

    player.PartyApi.JoinPartyWithId(
  ExtPlayerJoinRequest extPlayerJoinRequest,
  PragmaId partyId,
  Dictionary<string, int> gameServerZoneToPing,
  CompleteDelegate onComplete
);

    {
  "requestId": 5,
  "type": "PartyRpc.JoinWithPartyIdV1Request",
  "payload": {
    "requestExt":{},
    "partyId":"5e359a34-8112-4a84-81d5-86f11f261f67",
    "gameClientVersion":"gameClientVersion1"
  }
}

The onAddPlayer method #

When a player joins a party by responding true to an invite, or by joining directly by providing an invite code or party ID, the Party service adds the player to the party object and the Party Plugin onAddPlayer method is invoked with the ExtPlayerJoinRequest to allow for initial customization of the player object. All party members are notified with the updated party state.

suspend fun onAddPlayer(
  requestExt: ExtPlayerJoinRequest,
  playerToAdd: PartyPlayer,
  party: Party,
  partyConfig: PartyConfig
)

Related events:

Related errors:

Assign the leader role #

Assign the leader role to another player

This action is only available to party leaders.

When a party is created, the first player added to the party is automatically assigned the leader role. To assign the leader role to another player, use the AssignPartyLeader SDK function. If PartyConfig.enableTransferPartyLeader is set to true, this call transfers the party leader role to the indicated player by setting the player’s leader property to true. If PartyConfig.enableTransferPartyLeader set to false, a new leader is made, resulting in multiple leaders.

Player->PartyApi().AssignPartyLeader(
  const FString& PlayerId,
  const FOnCompleteDelegate& FOnCompleteDelegate
);

player.PartyApi.AssignPartyLeader(
  PragmaId playerId,
  CompleteDelegate CompleteDelegate
);

{
  "requestId": 6,
  "type": "PartyRpc.AssignPartyLeaderV1Request",
  "payload": {
    "playerId":"5e359a34-8112-4a84-81d5-87f11f261f77"
  }
}

Related events:

Related errors:

Update party data #

Players update stored party data

Update party selections

Update party data, such as matchmaking duration, by adding custom data to the ExtUpdatePartyRequest payload and passing it to the UpdateParty SDK method.

The UpdateParty call can be restricted to leader-only by writing the plugin implementation to reject changes based on roles.
Player->PartyApi().UpdateParty(
  const FPragma_Party_ExtUpdatePartyRequest& RequestExt,
  const FOnCompleteDelegate& OnComplete
);

player.PartyApi.UpdateParty(
  ExtUpdatePartyRequest extUpdatePartyRequest,
  CompleteDelegate onComplete
);

{
  "requestId": 7,
  "type": "PartyRpc.UpdatePartyV1Request",
  "payload": {
    "requestExt": {}
  }
}

When a player client calls UpdateParty, the Party service invokes the Party Plugin’s updateParty method and passes it the ExtUpdatePartyRequest payload, which can be used to update the data stored in ExtParty.

suspend fun updateParty(
 requestingPlayer: PartyPlayer,
 requestExt: ExtUpdatePartyRequest,
 party: Party,
 partyConfig: PartyConfig
)

Related events:

Related errors:

Update player selections #

Players update stored data for players in the party

Update player selections

Update player selections, such as character or costume, by adding custom data to the ExtUpdatePartyPlayerRequest payload and passing it to the UpdatePartyPlayer SDK method.

Player->PartyApi().UpdatePartyPlayer(
  const FPragma_Party_ExtUpdatePartyPlayerRequest& ExtUpdatePartyPlayerRequest
  const FOnCompleteDelegate& FOnCompleteDelegate
);

player.PartyApi.UpdatePartyPlayer(
  ExtUpdatePartyPlayerRequest extUpdatePartyPlayerRequest,
  CompleteDelegate CompleteDelegate
);

{
  "requestId": 8,
  "type": "PartyRpc.UpdatePartyPlayerV1Request",
  "payload": {
    "requestExt": {}
  }
}

When a player client calls UpdatePartyPlayer, the Party service invokes the Party Plugin’s updatePlayer method and passes it the ExtUpdatedPlayerSelectionsRequest payload. This new data can be used to update the data stored in ExtPartyPlayer.

suspend fun updatePartyPlayer(
 playerToUpdate: PartyPlayer,
 requestExt: ExtUpdatePartyPlayerRequest,
 party: Party,
 partyConfig: PartyConfig
)

Related events:

Related errors:

Broadcast party and player data #

Determine what party and player data to send to party members when party is updated

Broadcast data

When a party is updated, created, or destroyed, the Party Plugin’s buildExtBroadcastParty, buildExtPrivatePlayer, and buildExtBroadcastPlayer methods are invoked. Use these methods to customize the specific party and player data that player clients receive when a party changes. You specify this data on the ExtBroadcastParty, ExtPrivatePlayer, and ExtBroadcastPlayer fields, which are sent to the party players in the OnPartyUpdated event. Players receive an ExtBroadcastParty payload, ExtBroadcastPlayer payloads for each player in the party, and their own ExtPrivatePlayer payload.

For example, you might list party difficulty levels on ExtBroadcastParty. The ExtPrivatePlayer payload could include a player’s private voice chat service token, and the ExtBroadcastPlayer payload could broadcast data about each player’s team number.

Related events:

Set ready states #

Determine whether players are ready to enter matchmaking

Set ready states

For a party to enter matchmaking, all players in the party must have their ready property set to true. By default this value is false and can be changed manually or programmatically. If the party attempts to enter matchmaking with any players that are not ready, the party will not enter matchmaking and the leader who called EnterMatchmaking receives the PlayersNotReady error.

Set ready state manually #

If you want each individual player to manually set their ready state, players within a party can use the SetPartyPlayerReady SDK call to specify whether or not they are ready to enter matchmaking. When SetPartyPlayerReady is called with a true value, the Party service first uses the Party Plugin’s canChangeReady method to verify whether the player is able to change their own ready state. If the player is allowed to make the change, the Party service sets the player’s ready value to true.

Player->PartyApi().SetPartyPlayerReady(
  bool bIsReady,
  const FOnCompleteDelegate& OnComplete
);

player.PartyApi.SetPartyPlayerReady(
  bool isReady,
  CompleteDelegate CompleteDelegate
);

{
  "requestId": 9,
  "type": "PartyRpc.SetReadyStateV1Request",
  "payload": {
    "ready": "true"
  }
}

suspend fun canChangeReady(
  player: PartyPlayer,
  newReadyState: Boolean,
  party: Party,
  partyConfig: PartyConfig
): Boolean

Set ready state programmatically #

Instead of having players manually set their own ready state, you can design your game to change a player’s ready state programmatically. For example, you might want a player’s ready state to change to true when they select a character. To do so, you can customize the UpdatePlayer plugin to set a player’s ready state based on when the player’s loadout is changed.

Related events:

Related errors:

Manage game server compatibility #

Define compatibility maps for game servers

Game servers and clients must be updated in parallel as updates are added to live service games. Pragma Engine checks for server/client compatibility whenever a party changes (players added/removed, party enters matchmaking, etc.).

Pragma specifies a defaultGameServerVersion in the dev-defaults.yml config as a fallback configuration for all game client versions.

You can define a list of game server versions and corresponding compatible game client versions in the gameServerVersionCompatibility block of your config file. Unique compatibility keys (positive integers) define the priority of the server/client version mappings. Each mapping includes:

  • server version
  • one or more corresponding client versions. Note that this value can contain a wildcard character (*).
  • unique compatibility keys (positive integers) that define the priority of the client version. Higher numbers indicate higher priority.

The following is an example PartyConfig configuration block:

game:
  core:
  serviceConfigs:
    PartyConfig:
        gameServerVersionCompatibility:
          1:
            serverVersion: "server0"
            clientVersions:
              1: "client0-*"
              2: "client1-*"
              3: "client2-pc"
          2:
            serverVersion: "server1"
            clientVersions:
              1: "client1-*"
              2: "client2-ps4"
              3: "client2-xbox"
              4: "client3-*"

If any player client in the party is incompatible with the server version, the player client(s) with incompatible client versions will receive the OnGameClientVersionUpdateRequired notification. Every player in the party will receive the OnPartyClientVersionMismatch notification. If all player clients are supported but cannot match to the same game server, all players will receive the OnPartyClientVersionMismatch notification.

The only action Pragma Engine prevents as a result of server/client version mismatch is entering matchmaking. If a party with mismatched server/client versions attempts to enter matchmaking, Pragma Engine throws an error and does not allow add the party to the matchmaking queue.

If you want to override the game server version mapping, configure your party plugin to set the party’s overrideGameServerVersion value to true and manually set thegameServerVersion value.

Related events:

Related errors:

Manage game server zones #

Set player’s GameServerZoneToPing for the party, or manually specify one or more preferred game server zones

Manage game server zones

Set map to ping #

Individual player clients can call SetPartyPlayerGameServerZoneToPing to update the map of their ping to different game server zones. When called, the Party service updates the gameServerZoneToPing value.

Player()->PartyApi().SetPartyPlayerGameServerZoneToPing(
  const TMap<FString, int32>& GameServerZoneToPing,
  const FOnCompleteDelegate& OnComplete
);

Player.PartyApi.SetPartyPlayerGameServerZoneToPing(
  Dictionary<string, int> gameServerZoneToPing,
  CompleteDelegate onComplete
);

{
  "requestId": 10,
  "type": "PartyRpc.SetGameServerZoneToPingV1Request",
  "payload": {
    "gameServerZoneToPing": {"us-west": 100}
  }
}

Set preferred game server zone #

This action is only available to party leaders.

To manually specify preferred game server zones, party leaders can use the SetPartyPreferredGameServerZones call. This sets a list of acceptable game server zones for the entire party. Matchmaking can then take into account both manual game server zone selections and all party members’ pings to each game server zone as part of its game server allocation logic.

Player()->PartyApi().SetPartyPreferredGameServerZones(
  TArray<FString> GameServerZones,
  const FOnCompleteDelegate& FOnCompleteDelegate
);

Player.PartyApi.SetPartyPreferredGameServerZones(
  IEnumerable<string> gameServerZones,
  CompleteDelegate onComplete
);

{
  "requestId": 11,
  "type": "PartyRpc.SetPreferredGameServerZonesV1Request",
  "payload": {
    "preferredGameServerZones": ["us-west"]
  }
}

Related events:

Related errors:

Enter matchmaking #

Enter matchmaking and send custom match data

This action is only available to party leaders. Parties with players currently in a game instance cannot enter matchmaking.

Enter matchmaking

After all players in the party are ready to join matchmaking (have their ready value set to true) a party leader can call the EnterMatchmaking SDK method to enter the party into matchmaking.

Player->PartyApi().EnterMatchmaking(
  const FOnCompleteDelegate& FOnCompleteDelegate
);

player.PartyApi.EnterMatchmaking(
  CompleteDelegate CompleteDelegate
);

{
  "requestId": 12,
  "type": "PartyRpc.EnterMatchmakingV1Request",
  "payload": {
  }
}

When the party leader issues the EnterMatchmaking call, the party is placed in a new Matchable object and the Matchmaking Plugin’s initialize method is invoked. (See Initialize matchmaking).

In addition, the Party Plugin invokes the buildMatchmakingKey, buildExtMatchmakingParty, and buildExtMatchmakingPlayer, functions. These functions allow for customization of matchmaking keys and any other custom matchmaking content.

suspend fun buildMatchmakingKey(
  party: Party
): ExtMatchmakingKey

suspend fun buildExtMatchmakingParty(
  party: Party
): ExtMatchmakingParty

suspend fun buildExtMatchmakingPlayer(
  party: Party
  player: Player
): ExtMatchmakingPlayer

When entering matchmaking, a snapshot of the party’s state is captured, including player and party selections. The Matchmaking service uses the values stored in this snapshot even if a user makes changes to the player or party while the party is in matchmaking. The exception to this is when a player leaves a party. If a player leaves a party while the party is in matchmaking, the whole party is removed from the Matchmaking service.

Related events:

Related errors:

See Matchmaking Tasks to see what happens once a party enters matchmaking.

Return from matchmaking #

Process matchmaking instance exit scenarios

When players return from matchmaking, the Party Plugin’s returnFromMatchmaking method is invoked. Use this method to perform any necessary updates to player or party states. For example, if the party leaves matchmaking due to a player disconnecting, you may want to retain character selections so players don’t need to reselect their character. By default, no selections or relevant party fields are changed when a party leaves matchmaking.

suspend fun returnFromMatchmaking(
  party: Party,
  returningPlayers: List<PartyPlayer>,
  config: PartyConfig
)

Related events:

Return from a game instance #

Process game instance exit scenarios.

Return from game

The Party Plugin’s returnFromGameInstance method provides a way to perform any updates on player and party states when a player is removed from a game or when a game instance ends. For example, you can use returnFromGameInstance to require players to reselect a character after completing a game instance to encourage diverse character pools.

suspend fun returnFromGameInstance(
  party: Party,
  returningPlayers: List<PartyPlayer>,
  config: PartyConfig
)

When a player leaves a game instance, the game server calls the removeplayers SDK method. When a game instance ends, the game server calls the EndGame SDK method. Both methods invoke returnFromGameInstance. When a game instance ends, players remain in their party, allowing them to quickly prepare for the next game instance and queue again.

Leave a party #

Voluntarily leave a party or remove a player from a party

Enter matchmaking

The LeaveParty SDK method allows players to voluntarily leave a party. In addition, party leaders can remove players from a party using the KickPlayerFromParty SDK method.

Leave a party voluntarily #

If a leader leaves a party, a random player in the party is made leader.
Player->PartyApi().LeaveParty(
  const FOnCompleteDelegate& FOnCompleteDelegate
);

player.PartyApi.LeaveParty(
  CompleteDelegate onComplete
);

{
  "requestId": 13,
  "type": "PartyRpc.LeaveV1Request",
  "payload": {
  }
}

Kick a player from a party #

In the case of multiple leaders, one leader can kick another leader.
Player->PartyApi().KickPlayerFromParty(
  const FString& PlayerId, 
  const FOnCompleteDelegate& OnComplete
);

player.PartyApi.KickPlayerFromParty(
  PragmaId playerToKickId, 
  CompleteDelegate onComplete
  )

{
  "requestId": 14,
  "type": "PartyRpc.KickV1Request",
  "payload": {
    "playerId":"5e359a34-8112-4a84-81d5-87f11f261f77"
  }
}

The onRemovePlayers method #

When the LeaveParty or KickPlayerFromParty call is made, or if a player is removed automatically, such as when a session is terminated, the Party service removes the target player from the party and invokes the Party Plugin’s onRemovePlayer method, which is used to perform any necessary updates to the party state.

suspend fun onRemovePlayer(
  party: Party,
  removedPlayer: PartyPlayer,
  removalReason: RemovalReason
)

The RemovalReason indicates why the player was removed from the party (disconnected, unsupported client version, kicked by leader, or unspecified). The removed player will receive a OnLeftParty notification indicating this reason. The remaining party members receive a notification with the updated party state. If the removed player is in a party that is in matchmaking, the party will be removed from matchmaking. See Leave matchmaking for more information.

Related events:

Related errors:

Set party expiration #

Set a party to automatically expire

You can configure parties to automatically expire after a certain duration (measured from time of party creation). This configuration is set system-wide and can be used as a backstop to prevent situations where a party isn’t properly removed/cleaned up due to bugs or connection issues.

By default, the expiration feature is enabled, with an expiration time of seven days. After seven days the party will be removed, regardless of party activity. If current parties already passed the configured time, they will be immediately removed. You can disable expiration functionality or change the time limit in the PartyConfig block of your yaml file:

game:
  serviceConfigs:
    PartyConfig:
      enableStalePartyExpiration: true
      stalePartyExpirationMinutes: 10080
Once enabled, it could take up to five minutes for the configuration to take effect.

Party Overview
Party Reference