Party Reference #
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.
The table below contains a list of the SDK methods relevant to the Party service. These methods are available via the
|Assigns a party leader
|Creates a new party
|Allows party leader to enter the party into matchmaking once all players are ready
|Returns the current session’s party player
|Returns the associated party object
|Returns the party invite according to the provided invite id
|Returns the party invite according to the provided id of the inviter
|Returns pending received invites
true if the player has an associated party object
true if the player has an associated party object and the session’s party ID attribute is present
true if provided player ID is the leader of the party
|Allows player to join a party using an invite code
|Allows player to join a party using a party ID
|Allows a player to leave a party voluntarily
|Removes a player from a party involuntarily
|Allows player to accept or reject another player’s invite to a party
|Sends a party invite to a specific player
true if the session’s party ID attribute is null
GameServerZoneToPing value for the party
GameServerZones value for the party
|Sets the player’s
|Updates custom party player information when in a party
|Updates custom party information
The Party Tasks explains how to use these calls to invoke Party Plugin methods and customize party functionality.
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 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.
Data classes #
There are two main data classes within the Party service:
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 #
|Unique identifier for the party
|List of PartyPlayer objects in the party
|Auto-generated unique string for the party that players can use to join
|Number representing the maximum amount of players for the party set via the
|Game server version that maps to the
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.
|Boolean indicating whether to use the game server/client mapping specified in the PartyConfig.
|List of game server zones that the party can play a match on
ExtParty payload containing party data for the platform to use
The PartyPlayer class #
|A user’s identifier within a specific game
|Unique social identifier for the player
PragmaDisplayName object containing the player’s name and discriminator
|Snapshot of the player’s inventory from when they entered the party or last completed a match
|Version of the game client the player is currently running
|Boolean indicating if this player ready to play a match
|Boolean indicating if this player is a leader in this party
|Map of this player’s ping to various game server zones
ExtPartyPlayer payload containing player data for the platform to use
PartyConfig configuration class provides a place to define default values for the Party service. The following configuration values are available:
|Maximum players allowed in each party
|Whether to disable maximum player count limits in each party
|Whether to allow local game clients to override their game server version for local development purposes
|Defines the delay (in number of seconds) between a player sending a party invite to another player consecutive times
|Tags used to filter player inventories. Items that match one or more tags will be included
|Whether to transfer party leader status from one player to another when invoking
|If enabled, use the
gameServerVersionDefault server version for clients not defined in the
|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.
|Map of all the server versions to compatible game client versions
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
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.
|Party data passed from the player client to the Party Plugin’s
initialize method during party creation.
|map or game mode
|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.
|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
|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
|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
|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.
|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
|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
|updated game mode
|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
|updated inventory version, costume, character
There are several party-related events that player clients can listen to. The following table contains bindable events relevant to the Party service, along with associated descriptions of when the event is triggered.
The following events are handled by the player client.
|A player joins a party
|Party information changes, including creation and destruction
Note: All other applicable
On* events fire in addition to this one, so developers will need to account for handling multiple events at once.
|A new invite code is made for the party
ext party selections change
|A party’s preferred game server zones change
|Your player leaves the party voluntarily
|Your player leaves a party for reasons outside of your control
|A new player joins the party. All players in the party can handle this event
|One or more players join or leave the party. Will fire if the number stays the same (e.g. +1, -1 in one update)
|Any player information changes
|A player’s private selections changes
|A player leaves the party
|An invite is created or responded to
|A party invite is received from another player
|A party invite is revoked, such as when pending invites are canceled by a game starting a match
|An invitee accepts the invite. Only inviters can handle this event
|An invitee declines the invite. Only inviters can handle this event
|The player client needs to update their
|Cannot find a game server version that is compatible with every player in the party
The following errors are relevant to the Party service.