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.

Prerequisites

Party player management

Party data and configuration

Party lifecycle

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.

Prerequisite: Initialize the Game Loop API #

To use the Unreal SDK and Game Loop API, you need to call the Initialize() function. 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.

Upon logout, the service is un-initialized. You must call initialize() on the service when you log back in.

If you haven’t done so already, call the Initialize() function:

Player->GameLoopApi().Initialize(
  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 GameLoopApi ForceSync function.

Create a party #

A party is initialized and the first player is added as the 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->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.

Related events:

Related errors:

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. 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. If you want to invite a player currently on your friend list, you can retrieve their player ID using the Friend Service Get friend list information call.

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

player.GameLoopApi.SendPartyInvite(
   inviteePlayerId,
   OnComplete
);

{
  "requestId": 2,
  "type": "PartyRpc.SendInviteV1Request",
  "payload": {
    "inviteePlayerId": "f9525239-cd99-425d-9f14-1ff948c02553"
  }
}
If the inviter is not currently in a party, the request will fail with PartyService_NotInParty. If the invitee is already in the same party as the inviter, 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.

Related events:

Related errors:

Join a party #

Players join parties.

Join a party

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 player via Discord.

After an invite code is obtained, the player client calls the GameLoopApi 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
  • 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().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 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).
    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
)

Related events:

Related errors:

Assign the leader role #

Assign the leader role to another player.

This action is only available to party leaders.

Assign leader role

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

Related events:

Related errors:

Update party data #

Players update stored party data.

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.

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
)

Related events:

Related errors:

Update player selections #

Players update stored data for players in the party.

Update player selections

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
)

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

Related events:

Set ready states #

Determine whether players are ready to enter matchmaking.

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

Related events:

Related errors:

Set party expiration #

You can configure parties to automatically expire after a certain duration. This configuration is set system-wide and can be used as a backstop to prevent situations where a party isn’t properly removed/cleaned up due to bugs or connection issues.

By default, the expiration feature is disabled, meaning a party will never expire. To enable the expiration feature, set enableStalePartyExpiration to true:

game:
  serviceConfigs:
    PartyConfig:
      enableStalePartyExpiration: true

Once enabled, Pragma Engine will, by default, remove parties 24 hours after party creation, regardless of party activity. The duration starts at the time of party creation, thus parties that have already existed past the configured time will be immediately removed when enableStalePartyExpiration is set to true.

To change the duration, set stalePartyExpirationMinutes:

game:
  serviceConfigs:
    PartyConfig:
      enableStalePartyExpiration: true
      stalePartyExpirationMinutes: 2880

When a party expires, players in the party will receive the OnRemovedFromParty notification with the EXPIRED removal reason.

Once enabled, it could take up to five minutes for the configuration to take effect.

Related events:

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.

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

Related events:

Related errors:

Enter matchmaking #

Enter matchmaking and send custom match data.

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

Enter matchmaking

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.

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

player.GameLoopApi.EnterMatchmaking(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.

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.

Related events:

Related errors:

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

Return from matchmaking #

Process matchmaking instance exit scenarios.

Return from matchmaking

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
)

Related events:

Return from a game instance #

Process game instance exit scenarios.

Return from game

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. When a game instance ends, players remain in their 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.

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

Related events:

Related errors:


Party Overview
Party Reference