Manage Parties and Party Players #

This topic provides instructions on how manage data related to parties and party players, including updating and broadcasting data, and managing party expirations.

Update party data #

Use SDK or backend services to update party data

Update from player client #

To request party data updates from the player client, use the Party API’s UpdateParty() method with the ExtUpdatePartyRequest payload, which describes how the party data should be updated. Players can only request updates for parties they are in.

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 called, PartyApi.UpdateParty() 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")
    }
    ...
}

Update from a backend service #

To request party data updates from backend services or plugins, use the PartyApi.kt backend class’s update() method with the ExtBackendUpdatePartyRequest payload, which describes how the party data should be updated.

1. Create an instance of the PartyApi.kt class in a Pragma plugin or custom service:

private val partytApi: PartyApi = PartyApi(service)

2. Call the PartyApi class’s update() method with the party ID and ExtBackendUpdatePartyRequest payload:

partyApi.update(partyId, requestExt)

When called, the PartyApi backend class’s update() method invokes the Party Plugin’s handleBackendUpdateRequest() method and passes it the Party object and the ExtBackendUpdateRequest payload, which can be used to update the data stored in ExtParty.

override suspend fun handleBackendUpdateRequest(
    party: Party.Party,
    requestExt: ExtBackendUpdateRequest
) {
    party.ext.selectedMatchmakingStyle = requestExt.requestedMatchmakingStyle
    //...
}

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

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 AssignPartyLeader(). 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"
  }
}

Update party players #

Update stored data for players in the party

Update player data, such as character or skin, by adding custom data to the ExtUpdatePartyPlayerRequest payload and passing it to the Party API’s UpdatePartyPlayer() 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 ExtUpdatePartyPlayerRequest 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
    }
}

Manage game server zones #

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

Set player ping for game server zones #

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

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, which you can use in matchmaking and 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"]
  }
}

Set ready states #

Set player ready state so they can 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 Party API’s SetPartyPlayerReady() method 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.

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 updating party data, adding/removing players, and 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

Handle party expirations #

Define what happens when a party expires

Using the Party plugin onPartyExpired() method, you can define other actions that should occur when a party expires.

suspend fun onPartyExpired(
    readOnlyParty: ReadOnlyParty
) {
}

The readOnlyParty is a read-only version of the Party class.

Related events and errors #

Related events:

• OnPartyUpdated
• OnExtBroadcastPartyChanged
• OnPartyPlayerDataChanged
• OnExtPrivatePlayerChanged

Related errors:

• PartyService_NotInParty
• PartyService_PlayerNotLeader
• PartyService_PlayerIsLeader