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 theExtParty
payload.ExtPlayerJoinRequest
: Use this payload to specify custom player data, such as a selected champion, to pass to theonAddPlayers
method when a player is added to a party. This data will be stored on theExtPartyPlayer
payload.preferredGameServerZones
:(optional) preferred game server zones. You can change this value later (seeSetPartyPreferredGameServerZones
).gameServerZoneToPing
: (optional) a ping map. You can change this value later (seeSetPartyPlayerGameServerZoneToPing
).Player->GameLoopApi().CreateParty( ExtCreateRequest, ExtPlayerJoinRequest, PreferredGameServerZones, GameServerZoneToPing, OnComplete );
player.GameLoopApi.CreateParty( extCreateRequest, extPlayerJoinRequest, preferredGameServerZones, gameServerZoneToPing );
{ "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 withPartyService_NotInParty
. If the invited player is already in the same party as the inviting player, the request will fail withPartyService_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 theonAddPlayers
method when a player is added to a party. This data will be stored on theExtPartyPlayer
payloadInviteID
: the invite ID including in theSendPartyInvite
calltrue
orfalse
: boolean stating whether the player accepts (true) or declines (false) the invitegameClientVersion
: (optional) game client version, which is used to calculate compatible game serversgameServerZoneToPing
: (optional) a ping map. You can change this value later (seeSetPartyPlayerGameServerZoneToPing
).
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 theonAddPlayers
method when a player is added to a party. This data will be stored on theExtPartyPlayer
payloadinviteCode
: invite code obtained by the player joining the partygameClientVersion
: (optional) game client version, which is used to calculate compatible game serversgameServerZoneToPing
: (optional) a ping map. You can change this value later (seeSetPartyPlayerGameServerZoneToPing
).Player->GameLoopApi().JoinPartyWithInviteCode( ExtPlayerJoinRequest, InviteCode, GameClientVersion, GameServerZoneToPing, FOnCompleteDelegate );
player.Party.JoinPartyWithInviteCode( extPlayerJoinRequest, inviteCode, gameClientVersion, gameServerZoneToPing, CompleteDelegate );
{ "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 theonAddPlayers
method when a player is added to a party. This data will be stored on theExtPartyPlayer
payloadpartyId
: party ID of the party the player is attempting to joingameClientVersion
: (optional) game client version, which is used to calculate compatible game serversgameServerZoneToPing
: (optional) a ping map. You can change this value later (seeSetPartyPlayerGameServerZoneToPing
).Player->GameLoopApi().JoinPartyWithId( ExtPlayerJoinRequest, PartyId, FOnCompleteDelegate );
player.GameLoopApi.JoinPartyWithId( extPlayerJoinRequest, partyId, CompleteDelegate );
{ "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
)
If the player you are attempting to add is already in a party, they will be removed from their party before theonAddPlayer
method is called. Because of this workflow, ifonAddPlayer
fails, the player will not belong to any party.
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 totrue
to allow undefined client versions to map togameServerVersionDefault
.gameServerVersionDefault
: The default game server version. Any client version not specified in thegameServerVersionCompatibility
section will map to thegameServerVersionDefault
.- 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.
- a user-defined
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.