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.

Party tasks include:

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:

Party invite tasks #

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 can handle the OnPartyInviteReceived and OnReceivedPartyInvitesChanged events.

If a player sends a party invite to another player who already has an unanswered 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).

Cancel a party invite #

Cancel a sent party invite

Players can cancel a sent party invite provided the invite has not yet been accepted or rejected.

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 and OnReceivedPartyInvitesChanged events. All players in the party get the OnPartyInviteCancelled event.

Accept a party invite #

The AcceptInvite() SDK method allows players to accept a received party invite.

This request contains the following information:

  • InviteID: ID of the party invite to accept
  • ExtPlayerJoinRequest: Use this payload to specify custom player data, such as a selected champion, to pass to the onAddPlayers() plugin method when a player is added to a party
  • gameServerZoneToPing: Optional map representing the player’s ping value and game server zone. You can change this map later using SetPartyPlayerGameServerZoneToPing.
Player->PartyApi().AcceptPartyInvite(
  const FString& InviteId,
  const FPragma_Party_ExtPlayerJoinRequest& ExtPlayerJoinRequest,
  const TMap<FString, int>& GameServerZoneToPing,
  const FOnCompleteDelegate& FOnCompleteDelegate
);

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

When a player accepts a party invite, all players in the party are notified with the OnPartyInviteAccepted event and the PartyPlugin onAddPlayer() method is invoked. See the onAddPlayerMethod.

Decline a party invite #

The DeclineInvite() SDK method allows players to decline a received party invite, identified by invite ID.

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

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

When a player declines a party invite, all players in the party are notified with the OnPartyInviteDeclined event.

Related events:

Related errors:

Join a party by ID or code #

Players join parties

Join a party

In addition to responding to invites, players can join an existing party using an invite code (JoinPartyWithInviteCode) or 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.

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.

override suspend fun onAddPlayer(
    requestExt: ExtPlayerJoinRequest, 
    playerToAdd: Party.PartyPlayer, 
    party: Party.Party, 
    partyConfig: PartyConfig,
) {
    playerToAdd.ext.selectedCharacter = requestExt.requestedCharacter
    //...
}

Related events:

Related errors:

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() SDK 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.

override suspend fun onRemovePlayer(
    party: Party,
    removedPlayer: PartyPlayer,
    removalReason: RemovalReason
) {
    party.player.forEach {
        it.isReady = false
    }
}

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:

Manage party data #

Players update stored party data

Update party #

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.

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.

override suspend fun updateParty(
    requestingPlayer: Party.PartyPlayer,
    requestExt: ExtUpdatePartyRequest,
    party: Party.Party,
    partyConfig: PartyConfig
) {
    if (!requestingPlayer.isLeader) {
        throw Exception("Only party leaders can change the party settings")
    }
    ...
}

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 party expiration #

Set a party to automatically expire

You can configure parties to automatically expire after a certain duration (measured from time of access). Parties will be removed after they haven’t been accessed for the full duration of the expiration. This includes actions such as player/partner client synchronization operations.

By default, the expiration feature is enabled with an expiration time of one day. If you change the configuration value, any existing parties that have not been accessed during the expiration duration will be 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: 1440
Once enabled, it could take up to five minutes for the configuration to take effect.

Manage party players #

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 players #

Update stored data for players in the party

Update players

Update player data, 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.

override suspend fun updatePlayer(
    playerToUpdate: PartyPlayer,
    requestExt: ExtUpdatePartyPlayerRequest,
    party: Party,
    partyConfig: PartyConfig
) {
    if (requestExt.hasNewCharacterSelection()) {
        playerToUpdate.ext.selectedCharacter = requestExt.newCharacterSelection
    }
}

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:

Set ready states #

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.

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

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

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

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.

override suspend fun canChangeReady(
    player: PartyPlayer,
    newReadyState: Boolean,
    party: Party,
    partyConfig: PartyConfig
): Boolean {
    return true
}

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.

Send party to matchmaking #

Enter matchmaking and send custom match data

A party leader can send their party to the Matchmaking service when all players are ready.

Enter matchmaking

Enter matchmaking #

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

After all players in the party are ready to join matchmaking, 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.

override suspend fun buildMatchmakingKey(
    party: Party.Party
): ExtMatchmakingKey {
    return ExtMatchmakingKey.newBuilder()
        .setGameMode(party.ext.selectedGameMode)
        .build()
}

override suspend fun buildExtMatchmakingParty(
    party: Party.Party,
): ExtMatchmakingParty {
    return ExtMatchmakingParty.newBuilder()
        .setMatchStyle(party.ext.matchStyle)
        .build()
}

override suspend fun buildExtMatchmakingPlayer(
    party: Party.Party,
    player: Party.PartyPlayer
): ExtMatchmakingPlayer {
    return ExtMatchmakingPlayer.newBuilder()
        .setMmr(player.ext.mmr)
        .build()
}

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.

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. By default, no selections or relevant party fields are changed when a party leaves matchmaking.

override suspend fun returnFromMatchmaking(
    party: Party,
    returningPlayers: List<PartyPlayer>,
    config: PartyConfig
) {
    returningPlayers.forEach {
        it.isReady = false
    }
}

Related events:

Related errors:

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

Return from a game instance #

Process game instance exit scenarios.

Return from game

When a player leaves a game instance, the game server calls the MatchApi RemovePlayers() method. When a game instance ends, the game server calls the MatchApi EndGame() method. Both methods invoke the Party Plugin’s returnFromGameInstance() method, which provides a way to perform any updates on player and party states. For example, you can use returnFromGameInstance() to require players to reselect a character after completing a game instance to encourage diverse character pools.

override suspend fun returnFromGameInstance(
    party: Party,
    returningPlayers: List<PartyPlayer>,
    config: PartyConfig
) {
    returningPlayers.forEach {
        it.ext = ExtPartyPlayer.getDefaultInstance()
    }
}

When a game instance ends, players remain in their party, allowing them to quickly prepare for the next game instance and queue again.


Party Overview
Party Backend Reference