Party Components #

Party Service SDK #

Developers can use the Pragma GameLoopApi SDK to implement Party service capabilities, such as assigning a party leader and leaving a party. In the Party Tasks topic we’ll see how to use these calls to invoke Party Plugin methods and customize party functionality. You can view a list of the Party service SDK methods in the Party SDK and Events topic.

The Party Plugin #

The Party Plugin provides a location for developers to implement custom party functionality. In the Party Service Tasks topic we’ll see how to use these the Party Plugin methods, along with the SDKs that invoke them. You can view all the Party Plugin methods and their properties on the PartyPlugin reference page.

The Party Data Classes #

There are two main data classes within the Party service: Party and PartyPlayer. These classes are created by the platform and handed to plugins to customize at the extension points described later on this page.

The Party Class #

property	description
`id`	unique identifier for the party
`players`	list of PartyPlayer objects in the party
`inviteCode`	invite code for the party that players can use to join
`maxPlayerCount`	number representing the maximum amount of players for the party set via the `PartyService` config
`gameServerVersion`	game server version that maps to the `PartyPlayer`s `gameClientVersion`, according to the values in the PartyConfig. This value is updated whenever a player joins or leaves the party, or attempts to join matchmaking.
`overrideGameServerVersion`	boolean indicating whether to use the game server/client mapping specified in the PartyConfig.
`preferredGameServerZones`	list of game server zones that the party can play a match on
`ext`	custom `ExtParty` payload containing party data for the platform to use

The PartyPlayer Class #

property	description
`playerID`	unique identifier for the player in the party
`socialId`	unique social identifier for the player
`displayName`	`PragmaDisplayName` object containing the player’s name and discriminator
`inventory`	snapshot of the player’s inventory from when they entered the party or last completed a match
`gameClientVersion`	version of the game client the player is currently running
`isReady`	boolean indicating if this player ready to play a match
`isLeader`	boolean indicating if this player is a leader in this party
`gameServerZoneToPing`	map of this player’s ping to various game server zones
`ext`	custom `ExtPartyPlayer` payload containing player data for the platform to use

Party Service Configuration #

The PartyConfig configuration class provides a place to define default values for the Party service. The following configuration values are available:

config	description
`maxPlayersPerParty`	maximum players allowed in each party
`disableMaxPlayerCount`	whether to disable maximum player count limits in each party
`enableLocalGameServerVersions`	whether to allow local game clients to override their game server version for local development purposes
`repeatInviteDelaySeconds`	defines the delay (in number of seconds) between a player sending a party invite to another player consecutive times
`inventoryTagsToInclude`	tags used to filter player inventories. Items that match one or more tags will be included
`enableTransferPartyLeader`	whether to transfer party leader status from one player to another when invoking `AssignPartyLeader`
`enableGameServerVersionDefault`	if enabled, use the `gameServerVersionDefault` server version for clients not defined in the `gameServerVersionCompatibility` map
`gameServerVersionDefault`	default game server version for clients not defined in the `gameServerVersionCompatibility` map. This value is used if `enableGameServerVersionDefault` is true. See Manage game server compatibility for more details.
`gameServerVersionCompatibility`	map of all the server versions to compatible game client versions

Broadcast Objects #

The BroadcastParty and BroadcastPlayer objects are sent to party players in the OnPartyChanged event when the party is updated (including party creation and destruction). These objects allow you to customize what party and player data is sent to the player clients. By default, this information is hidden. The objects contain the following properties:

BroadcastParty #

property	description
`id`	unique identifier for the party
`players`	a list of `BroadcastPlayer` objects, one for each player in the party
`inviteCode`	invite code the `players` can send to other players who want to join the party
`preferredGameServerZones`	list of game server zones the party prefers
`ext`	custom `ExtBroadcastParty` payload containing party data to send to the player clients
`extPlayer`	custom `ExtPrivatePlayer` payload containing private player data

BroadcastPlayer #

property	description
`playerId`	unique identifier for the player in the party
`socialId`	unique social identifier for the player
`displayName`	`PragmaDisplayName` object containing the player’s name and discriminator
`isReady`	boolean indicating if this player ready to play a match
`isLeader`	boolean indicating if this player is a leader in this party
`ext`	custom `ExtBroadcastPlayer` payload containing public player data to send to all players in the party

Extension Data #

You can use Extension Data (exts) to define custom data about players and parties as the party travels through the game loop. These fields are stored on the Party or PartyPlayer classes, and are passed to other plugins as necessary. See Party Service Tasks for sample implementation.

The following table lists the ext payloads relevant to party and player information.

`ext`	description	example data
`ExtCreateRequest`	Party data passed from the player client to the Party Plugin’s `initialize` method during party creation.	map or game mode
`ExtPlayerJoinRequest`	Data related to the player joining the party. This `ext` is passed from the player client to the Party Plugin when the player is added to a party.	selected character
`ExtParty`	Additional party data for the platform to use. This `ext` is populated when a party is created, and is stored in the engine for the life of the party. This data is for platform use and is hidden by default.	matchmaking style, game instance duration
`ExtPartyPlayer`	Additional data about a single player in a party. This `ext` is populated when a player joins a party, and is stored in the engine for as long as the player is in the party. This data is for platform use and is hidden by default.	costume catalog id
`ExtBroadcastParty`	Party data that is populated by the Party Plugin’s `buildExtBroadcastParty` method and passed to all player clients on the `OnPartyChanged` event when their party is updated (including party creation and destruction).	game mode, game instance duration
`ExtBroadcastPlayer`	Player data that is populated by the Party Plugin’s `buildExtBroadcastPlayer` method and passed to all player clients when their party is updated (including party creation and destruction). Players receive a separate `ExtBroadcastPlayer` payload on the `OnPartyChanged` event for each player in the party.	selected character
`ExtPrivatePlayer`	Private player data that is populated by the Party Plugin’s `buildExtPrivatePlayer` method and passed to a player client when their party is updated (including party creation and destruction). Each player receives only their own `ExtPrivatePlayer` payload on the `OnPartyChanged` event.	VoIP token
`ExtUpdatePartyRequest`	Party data passed from a player client to the Party Plugin’s `updateParty` method. Information sent on this payload updates the data stored in the `ExtParty` proto.	updated game mode
`ExtUpdatePartyPlayerRequest`	Player data passed from a player client to the Party Plugin’s `updatePlayer` method. Information sent on this payload updates the data stored in the `ExtPartyPlayer` proto.	updated inventory version, costume, character