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.

Common Party service tasks include:

• Create a party
• Send invites
• Join or leave a party
• Assign the leader role
• Update party and player selections
• Customize broadcasted party and player data
• Set ready states
• Manage game server compatibility
• Manage game server zones
• Enter matchmaking
• Return from matchmaking
• Return from a game instance

For a full list of all available Party service SDK calls and events, see Party SDK and Events. For Party Plugin methods, see the PartyPlugin reference page.

Create a party #

A party is initialized and the first player is added as the leader.

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).
  Unreal

  Player->GameLoopApi().CreateParty(
    ExtCreateRequest,
    ExtPlayerJoinRequest,
    PreferredGameServerZones,
    GameServerZoneToPing,
    OnComplete
  );
  

  Unity

  player.GameLoopApi.CreateParty(
    extCreateRequest, 
    extPlayerJoinRequest,
    preferredGameServerZones,
    gameServerZoneToPing
  );
  

  JSON

    {
      "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 invokes the Party Plugin’s initializeParty method. The initializeParty method uses data in ExtCreateRequest to customize the initial party state.

suspend fun initializeParty(
  party: Party,
  requestExt: ExtCreateRequest,
  partyConfig: PartyConfig
)

After the Party Plugin 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.

Send an invite #

Players invite their friends to the party.

One way that players can join a party is through party invites. Any player can invite another player using the invitee’s player ID. To do this, the player client calls the SendPartyInvite SDK method with the ID of the player to invite.

Player->GameLoopApi().SendPartyInvite(
  PlayerId,
  OnComplete
);

player.GameLoopApi.SendPartyInvite(
   inviteePlayerId,
   OnComplete
);

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

If the invitation sender is not currently in a party, the request will fail with PartyService_NotInParty. If the invited player is already in the same party as the inviting player, the request will fail with PartyService_AlreadyInParty.

The SendPartyInvite call sends an invitation to the listed player, who receives an OnPartyInviteReceived event. The player client responds to the invite with the RespondToPartyInvite SDK method, indicating whether they want to join the party (true) or decline to join (false). The Join a party. section in this topic explains the RespondToPartyInvite SDK method.

Join a party #

Players join parties.

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->GameLoopApi().RespondToPartyInvite(
  ExtPlayerJoinRequest,
  InviteId,
  Accepted,
  FOnCompleteDelegate
);

player.GameLoopApi.RespondToPartyInvite(
  extPlayerJoinRequest,
  inviteId,
  accepted,
  CompleteDelegate
);

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

Join by 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 friend via Discord.

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

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
• 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).
  Unreal

  Player->GameLoopApi().JoinPartyWithInviteCode(
    ExtPlayerJoinRequest,
    InviteCode,
    GameClientVersion,
    GameServerZoneToPing,
    FOnCompleteDelegate
  );
  

  Unity

  player.Party.JoinPartyWithInviteCode(
    extPlayerJoinRequest,
    inviteCode,
    gameClientVersion,
    gameServerZoneToPing,
    CompleteDelegate
  );
  

  JSON

  {
    "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 GameLoopApi 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
• 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).
  Unreal

  Player->GameLoopApi().JoinPartyWithId(
    ExtPlayerJoinRequest,
    PartyId,
    FOnCompleteDelegate
  );
  

  Unity

  player.GameLoopApi.JoinPartyWithId(
    extPlayerJoinRequest,
    partyId,
    CompleteDelegate
  );
  

  JSON

  {
    "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
)

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->GameLoopApi().AssignPartyLeader(
  PlayerId,
  FOnCompleteDelegate
);

player.GameLoopApi.AssignPartyLeader(
  playerId,
  CompleteDelegate
);

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

Update party data #

Players update stored party data.

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->GameLoopApi().UpdateParty(
  ExtUpdatePartyRequest,
  FOnCompleteDelegate
);

player.GameLoopApi.UpdateParty(
  extUpdatePartyRequest,
  CompleteDelegate
);

{
  "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
)

Update player selections #

Players update stored data for players in the party.

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->GameLoopApi().UpdatePartyPlayer(
  ExtUpdatePartyPlayerRequest
  FOnCompleteDelegate
);

player.GameLoopApi.UpdatePartyPlayer(
  extUpdatePartyPlayerRequest,
  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
)

Broadcast party and player data #

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

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 OnPartyChanged 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.

Set ready states #

Determine whether players are ready to enter matchmaking.

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->GameLoopApi().SetPartyPlayerReady(
  bIsReady,
  FOnCompleteDelegate
);

player.GameLoopApi.SeetPartyPlayerReady(
  isReady,
  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.

Manage game server compatibility #

Game servers and clients must be updated in parallel as updates are added to live service games. You can define a list of game server versions and corresponding compatible game client versions in the serviceConfig/PartyConfig block of your configuration file.

The PartyConfig section includes:

• enableGameServerVersionDefault: Set to true to allow undefined client versions to map to gameServerVersionDefault.
• gameServerVersionDefault: The default game server version. Any client version not specified in the gameServerVersionCompatibility section will map to the gameServerVersionDefault.
• a gameServerVersionCompatibility configuration block that defines server/client version mapping. Unique compatibility keys (positive integers) define the priority of the server/client version mappings. Higher numbers indicate higher priority. Each mapping includes:
  • a user-defined serverVersion
  • one or more corresponding clientVersions. Note that this value can contain a trailing wildcard character (*).
  • unique compatibility keys (positive integers) that define the priority of the client version. Higher numbers indicate higher priority.

If you do not want to use the PartyConfig mapping feature, set the party’s overrideGameServerVersion value to true.

The following is an example PartyConfig configuration block:

game:
  core:
  serviceConfigs:
    PartyConfig:
        enableGameServerVersionDefault: true
        gameServerVersionDefault: "GameServerVersion1"
        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-*"

Pragma Engine checks for server/client compatibility whenever a party changes (players added/removed, party enters matchmaking, etc.). 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.

Manage game server zones #

Set player’s GameServerZoneToPing for the party, or manually specify one or more preferred 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()->GameLoopApi().SetPartyPlayerGameServerZoneToPing(
  GameServerZoneToPing,
  FOnCompleteDelegate
);

Player.Party.SetPartyPlayerGameServerZoneToPing(
  gameServerZoneToPing
  CompleteDelegate
);

{
  "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()->GameLoopApi().SetPartyPreferredGameServerZones(
  GameServerZones,
  FOnCompleteDelegate
);

Player.GameLoopApi.SetPartyPreferredGameServerZones(
  gameServerZones
  CompleteDelegate
);

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

Enter matchmaking #

Enter matchmaking and send custom match data.

This action is only available to party leaders.

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.

If a player without the leader role attempts to make this call, they receive the PlayerNotLeader error. If any player’s ready value is false, the leader who called EnterMatchmaking receives the PlayersNotReady error.

Player->GameLoopApi().EnterMatchmaking(FOnCompleteDelegate);

player.GameLoopApi.EnterMatchmaking(CompleteDelegate);

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

When the party leader issues the EnterMatchmaking call, 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.

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
)

Return from a game instance #

Process game instance exit scenarios.

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. Upon returning from a game instance, players are returned to their original 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.

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->GameLoopApi().LeaveParty(FOnCompleteDelegate);

player.GameLoopApi.LeaveParty(CompleteDelegate);

{
  "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->GameLoopApi().KickPlayerFromParty(
  PlayerId, 
  FOnCompleteDelegate
);

player.GameLoopApi.KickPlayerFromParty(
  playerToKickId, 
  CompleteDelegate
  )

{
  "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.