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

AssignPartyLeaderAssigns a party leader
CreatePartyCreates a new party
EnterMatchmakingAllows party leader to enter the party into matchmaking once all players are ready
ForceSyncForcibly synchronize the player client party cache with the party information in the Pragma Engine backend
GetLocalPartyPlayerReturns the current session’s party player (Deprecated in 0.0.101. Use GetPartyState()->LocalPartyPlayer())
GetPartyReturns the associated party object (Deprecated in 0.0.101. Use GetPartyState()->Party())
GetPartyInviteByInviteIdReturns the party invite according to the provided invite id
GetPartyInviteByInviterIdReturns the party invite according to the provided id of the inviter
GetPendingPartyInvitesReturns pending received invites
HasPartyReturns true if the player has an associated party object (Deprecated in 0.0.101. Use GetPartyState()->IsInParty())
InitializeInitialize the client’s game loop API state and synchronizes party state with the platform. Must be called prior to using other functionality on the API.
IsInPartyReturns true if the player has an associated party object and the session’s party ID attribute is present (Deprecated in 0.0.101. Use GetPartyState()->IsInParty())
IsLeaderOfPartyReturns true if provided player ID is the leader of the party (Deprecated in 0.0.101. Use GetPartyState()->Party()->IsLeader(PlayerId))
JoinPartyWithInviteCodeAllows player to join a party using an invite code
JoinPartyWithIdAllows player to join a party using a party ID
LeavePartyAllows a player to leave a party voluntarily
KickPlayerFromPartyRemoves a player from a party involuntarily
RespondToPartyInviteAllows player to accept or reject another player’s invite to a party
SendPartyInviteSends a party invite to a specific player
SessionNotInPartyReturns true if the session’s party ID attribute is null (Deprecated in 0.0.101. Use GetPartyState()->IsInParty())
SetPartyPlayerGameServerZoneToPingUpdates the GameServerZoneToPing value for the party
SetPartyPreferredGameServerZonesUpdates the GameServerZones value for the party
SetPartyPlayerReadySets the player’s Ready value
UpdatePartyPlayerUpdates custom party player information when in a party
UpdatePartyUpdates 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: 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 #

idUnique identifier for the party
playersList of PartyPlayer objects in the party
inviteCodeAuto-generated unique string for the party that players can use to join
maxPlayerCountNumber representing the maximum amount of players for the party set via the PartyService config
gameServerVersionGame server version that maps to the PartyPlayers 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.
overrideGameServerVersionBoolean indicating whether to use the game server/client mapping specified in the PartyConfig.
preferredGameServerZonesList of game server zones that the party can play a match on
extCustom ExtParty payload containing party data for the platform to use

The PartyPlayer class #

playerIdA user’s identifier within a specific game
socialIdUnique social identifier for the player
displayNamePragmaDisplayName object containing the player’s name and discriminator
inventorySnapshot of the player’s inventory from when they entered the party or last completed a match
gameClientVersionVersion of the game client the player is currently running
isReadyBoolean indicating if this player ready to play a match
isLeaderBoolean indicating if this player is a leader in this party
gameServerZoneToPingMap of this player’s ping to various game server zones
extCustom ExtPartyPlayer payload containing player data for the platform to use

Configuration #

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

maxPlayersPerPartyMaximum players allowed in each party
disableMaxPlayerCountWhether to disable maximum player count limits in each party
enableLocalGameServerVersionsWhether to allow local game clients to override their game server version for local development purposes
repeatInviteDelaySecondsDefines the delay (in number of seconds) between a player sending a party invite to another player consecutive times
inventoryTagsToIncludeTags used to filter player inventories. Items that match one or more tags will be included
enableTransferPartyLeaderWhether to transfer party leader status from one player to another when invoking AssignPartyLeader
enableGameServerVersionDefaultIf enabled, use the gameServerVersionDefault server version for clients not defined in the gameServerVersionCompatibility map
gameServerVersionDefaultDefault 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.
gameServerVersionCompatibilityMap of all the server versions to compatible game client versions
enableStalePartyExpirationWhether to enable the party expiration feature
stalePartyExpirationMinutesTime, in minutes, to wait before terminating a party. 0 or negative values means parties will never timeout. Will be ignored if enableStalePartyExpiration is false.

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.

extdescriptionexample data
ExtCreateRequestParty data passed from the player client to the Party Plugin’s initialize method during party or game mode
ExtPlayerJoinRequestData 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
ExtPartyAdditional 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
ExtPartyPlayerAdditional 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
ExtBroadcastPartyParty 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
ExtBroadcastPlayerPlayer 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
ExtPrivatePlayerPrivate 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
ExtUpdatePartyRequestParty 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
ExtUpdatePartyPlayerRequestPlayer 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

Events #

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.

EventTriggerData returned
OnJoinedPartyA player joins a partyParty
OnPartyChanged(Unreal) OnPartyDataChanged(Unity)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.
OnPartyInviteCodeChangedA new invite code is made for the partyinvite code
OnExtBroadcastPartyChangedThe public ext party selections changeExtBroadcastParty
OnPartyPreferredGameServerZonesChangedA party’s preferred game server zones changeParty.preferredGameServerZones
OnLeftPartyYour player leaves the party voluntarilyN/A
OnRemovedFromPartyYour player leaves a party for reasons outside of your controlRemoval reason (REMOVAL_REASON_UNSPECIFIED, KICKED, LEFT, DISCONNECTED, or EXPIRED)
OnPlayerJoinedPartyA new player joins the party. All players in the party can handle this eventPartyPlayer
OnPartyPlayersChangedOne or more players join or leave the party.PartyPlayer for each player that joins
OnPartyPlayerDataChangedAny player information changesPartyPlayer
OnExtPrivatePlayerChangedA player’s private selections changesExtPrivatePlayer
OnPlayerLeftPartyA player leaves the partyPartyPlayer
OnPartyInvitesChangedAn invite is created or responded toinvite ID, inviter’s player ID
OnPartyInviteReceivedA party invite is received from another playerinvite ID, inviter’s player ID
OnPartyInviteRevokedA party invite is revoked, such as when pending invites are canceled by a game starting a matchinvite ID
OnPartyInviteAcceptedAn invitee accepts the invite. Only inviters can handle this eventinvite ID
OnPartyInviteDeclinedAn invitee declines the invite. Only inviters can handle this eventinvite ID
OnGameClientVersionUpdateRequiredThe player client needs to update their GameClientVersionN/A
OnPartyClientVersionMismatchCannot find a game server version that is compatible with every player in the partyN/A

Errors #

The following errors are relevant to the Party service.

  • PartyService_PartyNotFound
  • PartyService_AlreadyInParty
  • PartyService_InvalidState
  • PartyService_NotInParty
  • PartyService_PlayerNotLeader
  • PartyService_PlayersNotReady
  • PartyService_FailedToEnterMatchmaking
  • PartyService_InviteNotFound
  • PartyService_PartyFull
  • PartyService_InvalidSession
  • PartyService_PartyClientVersionMismatch
  • PartyService_OverrideGameServerVersionDisabled
  • PartyService_GameServerNoLongerCompatible
  • PartyService_LeavePartyFailed
  • PartyService_PlayerNotFound
  • PartyService_PlayerIsKicked
  • PartyService_CanNotKickSelf
  • PartyService_PlayersAlreadyInGameLoop
  • PartyService_PlayerIsLeader
  • PartyService_FailedToLeaveMatchmaking