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 #

Update party data using the API or backend methods

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. In the following example, we use the game mode from the ExtUpdatePartyRequest to set the game mode in the party data store (party.ext).

override suspend fun updateParty(
    requestingPlayer: Party.PartyPlayer,
    requestExt: ExtUpdatePartyRequest,
    party: Party.Party,
    partyConfig: PartyConfig
) {
    
    if (requestingPlayer.isLeader) {
        val partyExt: ExtParty.Builder = party.ext.toBuilder()
        partyExt
            .setGameMode(requestExt.gameMode)
        party.ext = partyExt.build()
    }
    ...
}

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

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

Assign the leader role #

Transfer of assign leadership roles

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 from the current leader to the indicated player. If PartyConfig.enableTransferPartyLeader is set to false, the specified player is added as an additional leader.

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"
  }
}

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 the Party API’s SetPartyPlayerGameServerZoneToPing() method 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 call the Party API’s SetPartyPreferredGameServerZones() method. 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 PartyPlugin.updatePlayer() method to set a player’s ready state based on when the player’s loadout is changed.

Broadcast party and player data #

Send party and player data to players

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 the party and player data on the ExtBroadcastParty, ExtPrivatePlayer, and ExtBroadcastPlayer fields, which are sent to the party players in the OnPartyUpdated event. 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.

Players receive an ExtBroadcastParty payload and ExtBroadcastPlayer payloads for each player in the party, and their own ExtPrivatePlayer payload.

Set party expiration #

Set a party to automatically expire

By default, the expiration feature is enabled with an expiration time of one day. 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 actions that should occur when a party expires.

suspend fun onPartyExpired(
    readOnlyParty: ReadOnlyParty
) {
    //handle party expiration
}

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