Party Backend Reference #

This section provides references for Party plugins, classes, configuration values, and ext data defined in the Pragma Engine backend. For specifics on using the Pragma SDK for party tasks, see Party SDK Reference.

Party Plugin #

The Party Plugin provides a location for developers to implement custom party functionality. The Party Service Tasks topic explains how to use the Party Plugin methods, along with the SDKs that invoke them.

method	description
`initializeParty()`	Called when a new party is created, before any players have been added. Use to initialize any party state.
`onAddPlayer()`	Called before the player has been added to the party. Use to prepare the new player to be added to the party.
`handlePlayerSendInviteRequest()`	Called when receiving a player request to send a party invite. Use to determine whether the player should be allowed to send the party invite.
`handleBackendUpdateRequest()`	Called when receiving a backend request to update party data.
`onRemovePlayer()`	Called after a player has been removed from the party. Use to perform any necessary updates to the party state.
`updateParty()`	Called when receiving an update party selections request. Use to perform any necessary updates to the party state.
`updatePlayer()`	Called when receiving an update player selections request. Use to perform any necessary updates to the player or party state.
`canChangeReady()`	Called when receiving a change ready state request. Use to determine whether a player can change their ready state.
`handlePlayerCancelInviteRequest()`	Called when receiving a player request to cancel a party invite. Use to determine whether the player should be allowed to cancel the party invite.
`buildExtBroadcastParty()`	Called when broadcasting a change to the party. Use to build any ext data that should be shared about the party.
`buildExtPrivatePlayer()`	Called when broadcasting a change to the party member. Use to build any private ext data that should only be sent to the player.
`buildExtBroadcastPlayer()`	Called when broadcasting a change to the party member. Use to build any ext data that should be shared about a player.
`buildMatchmakingKey()`	Called when the party is attempting to enter matchmaking. Use to build the matchmaking key they will use to enter matchmaking.
`buildExtMatchmakingParty()`	Called when the party is attempting to enter matchmaking. Use to build any ext data the matchmaking system will need to know about the party.
`buildExtMatchmakingPlayer()`	Called for each player within a party when the party is attempting to enter matchmaking. Use to build any ext data the matchmaking system will need to know about each player.
`returnFromMatchmaking()`	Called when players are returning from matchmaking. Use to perform any necessary updates to the player or party state.

Player object #

The Player object includes a PlayerOverview interface that allows Party objects to access a player’s social ID, player ID, and display name.

property	description
`socialId`	Social identifier of the player
`playerId`	Game identifier of the player
`displayName`	Player’s display name

Party interfaces #

There are three main interfaces within the Party service: Party, PartyPlayer, and PartyInvite. These interfaces represent parties, their players, as well as information about invitations sent for the party.

Party #

Party.Party represents a party within the party service.

property	description
`id`	Unique identifier for the party
`players`	List of `PartyPlayer` objects in the party
`invites`	List of outstanding `PartyInvite` objects for players to join the party
`inviteCode`	Auto-generated unique string 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

method	description
`sendInvite()`	Facilitates sending a party invite from an `inviterPlayerId` to a `inviteePlayerId`. This method must be called for an invite to be sent.
`cancelInvite()`	Facilities canceling a party invite, identified by inviteId. This method must be called for an invite to be canceled.

PartyPlayer #

Party.PartyPlayer represents a player within the party service.

property	description
`playerId`	A user’s identifier within a specific game
`socialId`	Unique social identifier for the player
`displayName`	`PragmaDisplayName` object containing the player’s name and discriminator
`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

PartyInvite #

Party.PartyInvite represents an invitation to join a party sent from one player to another.

property	description
`id`	Unique identifier for the party invite
`inviter`	`PlayerOverview` for the player who sent the invite
`inviteePlayerId`	Player ID of the player invited to join the party

Party API backend class #

The PartyApi.kt backend class is the entrypoint to the party service from other backend services or plugins.

method	description
`getIdPlayer()`	Returns a party ID for a specific player, identified by player ID
`getForPlayer()`	Returns a `PartySummary` for a specific player, identified by player ID
`get()`	Returns a `PartySummary` for a specific party ID
`update()`	Request to update a Party. Triggers the PartyPlugin `handleBackendUpdateRequest()` method.

PartySummary #

property	description
`id`	Unique identifier for the party
`inviteCode`	Invite code for the party
`players`	List of PartyPlayerSummary for each party player.
`ext`	`ExtParty`

PartyPlayerSummary #

property	description
`playerId`	Unique identifier for the party player
`isLeader`	Whether or not the player is the party leader
`ext`	`ExtPartyPlayer`

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 per party restriction
`repeatInviteDelaySeconds`	Time (in seconds) a player has to wait before sending another party invite to the same player
`enableTransferPartyLeader`	Whether to transfer party leader status from one player to another when invoking `AssignPartyLeader`
`enableGameServerVersionDevelopmentOverride`	Whether to allow game clients to override their game server version for local development purposes
`gameServerVersionCompatibility`	Map of all the server versions to compatible game client versions
`enableStalePartyExpiration`	Whether to enable the party expiration feature. Defaults to `true`.
`stalePartyExpirationMinutes`	Time (in minutes) to wait before terminating a party. 0 or negative values means parties will never timeout. Will be ignored if `enableStalePartyExpiration` is false.
`assessTimeoutsIntervalSeconds`	Interval, in seconds, between checking for expiration of timeouts on the service

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
`ExtBackendUpdatePartyRequest`	Party data passed from a backend service via the PartyApi backend class. Populated by the `PartyPlugin.handleBackendUpdateRequest()` method.

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
PartyService_SendInviteFailed
PartyService_CancelInviteFailed