Multiplayer Backend Reference #

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

Party service #

Plugins #

Plugin	Description
`PartyPlugin`	Use to define and implement custom party functionality.

Classes #

Class	Description
`Player` object	Includes a `PlayerOverview` interface that allows Party objects to access a player’s social ID, player ID, and display name.
`Party`	Represents a party within the party service.
`PartyPlayer`	Represents a player within the party service.
`PartyInvite`	Represents an invitation to join a party sent from one player to another.
`PartyApi.kt` backend class	Entrypoint to the party service from other backend services or plugins.

Configuration #

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

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.

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.

Game Instance service #

Plugins #

Plugin	Description
`GameInstancePlugin`	Use to define custom interactions throughout the lifecycle of a game instance.
`GameInstanceMatchmakingPlugin`	Use to define custom interactions for a game instance and its players when entering matchmaking.

Classes #

Class	Description
`GameInstance`	Represents a running game instance, and includes details about the parties, players, and a custom-defined payload of extra game information that will be used to create the game instance.
`GamePlayer`	Represents a player within a game instance.
`DataStore`	Use to store custom data about both the game instance and its players.
`PlayerSync`	Determines accessibility of information on the game instance’s data store. Information in a data store can be synced with one or more players in the game instance, or hidden.
`GameInstanceApi.kt` backend class	Entrypoint to the game instance service from other backend services or plugins.
`GameInstanceSummary`	Represents a subset of game instance data.
`GamePlayerSummary`	Represents a subset of game player data.
`GameStart`	Represents data sent to the game server when a game server is allocated for a game instance.

Configuration #

The GameInstanceServiceConfig provides a place to define default values for game instance and game server operations.

config	description
`gameServerAllocationTimeoutMillis`	Time, in milliseconds, to wait for a game server to send a `getGameStartData` request before allocation is marked as failed. If using the Pragma Fleet Service, this configuration value should match the Fleet Service `serverMaxStartDurationMillis` config value.
`connectPlayersTimeoutMillis`	Time, in milliseconds, to wait for a game server to send a connect players request before releasing the players attached to the game instance
`enableKeepAlive`	Enables the keep alive interval, which specifies the interval within which a game server needs to send a keep alive request. If the game server does not send a request within this interval, the the game instance will be released from the service.
`keepAliveIntervalMillis`	Interval, in milliseconds, to wait between keep alive requests. This value will be ignored if `enableKeepAlive` is `false`.
`keepAliveMissesLimit`	Number of keep alive request the game server can miss before releasing the game instance from the service. This value will be ignored if enableKeepAlive is false.
`assessTimeoutsIntervalSeconds`	Interval, in seconds, between checking for expiration of timeouts on the service
`removePlayersOnDisconnect`	Determines whether the player is removed from their game instance upon disconnect. Defaults to `false`.
`enableExtraCreateGameInstanceTimers`	Enables additional timing metrics to diagnose performance issues within the `CreateGameInstanceV1` endpoint
`enableStaleGameInstanceExpiration`	Enables the absolute timeout that will release a game from the service after a specific amount of time has elapsed. Defaults to `true`.
`staleGameInstanceExpirationMinutes`	Time, in minutes, to wait before releasing a game instance. A 0 or negative values means games will never timeout. This value will be ignored if `enableStaleGameInstanceExpiration` is `false`.

See the Game Server section in the documentation for more information on game server operations.

Extension data #

You can use Extension Data (exts) to pass custom information between different Pragma components for the duration of the game instance. Fields in the various exts can be stored on the engine, or forwarded to plugins, game servers, and player clients through other exts.

The following table lists the ext payloads relevant to game instance information.

`ext`	description	Example data
`ExtData`	Defines the structure of game instance and game player data stored within the DataStore. Populated in any method of the GameInstancePlugin and used in the backend, player clients, and game servers.	player’s team color, game mode
`ExtGameStart`	Game instance data provided to the game server starting the game. When the game server is allocated for a game instance, it calls `getGameStartDataV1()`, which invokes the Game Instance Plugin’s `buildExtGameStart()` method.	game instance duration
`ExtGameServerPlayer`	Player data provided to the game server by the Game Instance service. When the game server is allocated for a game instance, it calls `getGameStartDataV1()`, which invokes the Game Instance Plugin’s `buildExtGameServerPlayer()` method for each player in the game instance.	Steam ID
`ExtPlayerConnectionDetails`	Connection details populated by the game server and used when a game instance is ready for players to join. Players receive the connect details in the `OnHostConnectionDetailsReceived` notification.	game server zone/region
`ExtBackendCreateRequest`	Data about a new game instance that is forwarded from a backend request to create a game instance.	game mode
`ExtPlayerCreateRequest`	Data about a new game instance that is forwarded from the player client’s request to create a game instance.	game mode
`ExtAllocateGameServer`	Data to assist in game server allocation. Populated by `GameServerProviderPlugin.startAllocationForGameInstance()`	game mode (3v3, 1v1, etc.) or game version (beta, trial, etc.)
`ExtPlayerUpdateRequest`	Payload populated by player clients defining what updates to make to a game instance	connection details in peer-to-peer setups
`ExtBackendUpdateRequest`	Payload sent via the game server’s `UpdateGameInstance()` SDK method defining what updates to make to a game instance	advance the current game phase
`ExtBackendAddPlayersRequest`	Payload containing data to use when adding a player to an existing game instance via backend services or processes.
`ExtBackendAddPlayer`	Payload for a specific player being added to a game instance via the `handleBackendAddPlayersRequest()`.	character selection
`ExtPlayerJoinGameInstanceRequest`	Data about the player joining the game instance via the Game Instance API.	character selection
`ExtPlayerLeaveRequest`	Data about the player requesting to leave the game instance.	reason for leaving
`ExtBackendRemovePlayersRequest`	Payload containing data to use when removing a player from a game instance via backend services or processes.
`ExtBackendRemovePlayer`	Payload for a specific player being removed from a game instance via the `handleBackendRemovePlayersRequest()`.
`ExtRemovedFromGame`	Player data populated by the Game Instance Plugin’s `handleBackendRemovePlayersRequest()` method and sent to the removed player client in the `OnRemovedFromGame` notification when the player is removed from a game instance	rewards delta
`ExtEndGameRequest`	Game instance data sent from the game server to the Game Instance Plugin’s `onEndGame()` method when a game instance ends	game metrics
`ExtPlayerGameResult`	Player data passed from the game server to the Game Instance Plugin’s `onEndGame()` method via the `PlayerGameResult` list when a game instance ends	completed missions, points gained
`ExtGameEnded`	Player data populated by the Game Instance Plugin’s `onEndGame()` method and sent to the player in the `OnGameEnded` notification when a game instance ends. Players previously removed from the game instance can still receive this information.	rewards delta

Matchmaking service #

Plugins #

Plugin	Description
`MatchmakingPlugin`	Use to define and implement custom matchmaking logic.
`WarmBodyMatchmakingPlugin`	An implementation of the `MatchmakingPlugin` that builds matches with any parties available based on the configurable `numberOfTeams` and `playersPerTeam`.

Classes #

Class	Description
`Matchable`	Represents a party or group of parties involved in the matchmaking process. Parties in Matchable objects are not yet active, and can be moved between Matchable objects.
`Party`	Represents a party in matchmaking. The object provides access to any party details that might be necessary to evaluate when making matchmaking decisions.
`Player`	Represents a single player within matchmaking. The object provides access to any player-specific data that might be necessary to evaluate when making matchmaking decisions.
`GameInstance`	Represents a game that has re-entered matchmaking to find more players.
`GamePlayer`	Represents an active player in a `Matchmaking.GameInstance`.
`NewGameInstance`	Represents a successful matchmaking result that will be used to allocate a new game.
`GameInstanceUpdate`	Represents an update to an active game instance that is in matchmaking.
`MatchmakingApi.kt` backend class	Entrypoint to the matchmaking service from other backend services or plugins.

Configuration #

The MatchmakingConfig provides a place to define default values for matchmaking operations.

config	description
`matchmakingDelayMillis`	Delay, in milliseconds, between matchmaking runs.
`enableGetMatchmakingInfo`	Enables the player-facing endpoint to retrieve operational info about the matchmaking service.
`enableExtraEnterMatchmakingTimers`	Enables some additional timing metrics to diagnose performance issues within the EnterMatchmakingV2 endpoint.
`divertResultsToMatchmakingSimulator`	Flag used to divert all matchmaking results to matchmaking simulator. This takes priority over sampleMatchResults if set to true.
`sampleMatchResults`	Percent chance (from 0 - 1) to divert results to matchmaking simulator.

Extension data #

The following table lists the ext payloads relevant to matchmaking. These exts are passed to the matchParties() and matchPartiesWithGame() plugin methods to inform matchmaking logic.

`ext`	description	Example data
`ExtMatchmakingKey`	Data that defines a matchmaking queue’s unique properties. When the matchmaking service adds parties to queues, it only allows a party to join a specific queue if the party’s properties match those defined in the queue’s `ExtMatchmakingKey`. Populated by `PartyPlugin.buildExtMatchmakingKey`	game mode
`ExtMatchmakingParty`	Party data the matchmaking service needs to know during the matchmaking process. This data is populated by `buildExtMatchmakingParty` and persists on the engine for the duration of the party’s time in matchmaking.	matchmaking style, game instance duration
`ExtMatchmakingPlayer`	Player data the matchmaking service needs to know during the matchmaking process. This data is populated by `buildExtMatchmakingPlayer` and persists on the engine for the duration of the player’s time in the party that is in matchmaking.	selected character
`ExtMatchmakingGameInstance`	Game instance data the matchmaking service needs to know during the matchmaking process. This data is populated by `buildExtMatchmakingGameInstance` and persists on the engine for the duration of the game instance’s time in matchmaking.	game phase
`ExtMatchmakingGamePlayer`	Data specific to a player within a game instance that is currently in matchmaking. This data is populated by `buildExtMatchmakingGamePlayer` and persists on the engine for the duration of the player’s time in the matchmaking game instance.	selected character
`ExtMatchable`	Stores the result of in-memory calculations performed within the Matchmaking loop. Modifiable in any MatchmakingPlugin method that accepts a Matchable object as a parameter.	aggregate MMR

Game server management #

Plugins #

Plugin	Description
`GameServerProviderPlugin`	Use to allocate a game server for a game instance.
`LocalProcessGameServerProviderPlugin`	A `GameServerProviderPlugin` implementation that will run a game server executable on the local machine. Use this plugin to make your local development more similar to your non-local environments.
`FleetPlugin`	Use to define a game server fleet management model.
`LocalProcessFleetPlugin`	A `FleetPlugin` implementation to use when running game servers using local hardware.
`FleetGameServerProviderPlugin`	A `GameServerProviderPlugin` implementation to use with the Pragma Fleet service.

Classes #

Class	Description
`ServerPool`	Contains data for the server pools in your environment.
`GameServerAllocation`	Maps game servers with the `PartnerClientTokens` it should use when authenticating to Pragma.
`PartnerClientTokens`	Contains data for partner client tokens that the game server should use when authenticating to Pragma.

Configuration #

FleetServiceConfig #

Fleet service configuration.

config	description
`serverPoolManagementPolicies`	Configuration for each server pool policy.

ServerPoolManagementPolicyConfig #

The configuration for a server pool management policy.

config	description
`id`	Unique ID for this server capacity pool management policy
`gameCapacityPerServer`	Maximum number of game instances that can run on a single game server. Value must be at least 1.
`capacityFloor`	Minimum game capacity allocated at all times
`capacityCeiling`	Maximum game capacity allocated at all times
`capacityBuffer`	Preferred available game capacity defined as a percentage of used game capacity
`serverMaxStartDurationMillis`	Maximum duration, in milliseconds, a game server can take to start before the allocation is declared failed. This configuration value should match the Game Instance Service `gameServerAllocationTimeoutMillis` config value.
`serverHeartbeatPeriodMillis`	Millisecond interval at which a game server should report its capacity
`serverHeartbeatExpiryFactor`	Number of heartbeats that can be missed before a game server is considered unresponsive
`gameCapacityResolvedTimeoutMillis`	Maximum duration, in milliseconds, the platform will wait for capacity to resolve for a game instance before ejecting it

Consider what capacityFloor and capacityCeiling values are appropriate for your environment. Setting these values too low or too high can lead to undesirable game instance load.

Extension data #

`ext`	description	example data
`ExtServerPool`	Populated by the Fleet Plugin `selectServerPool()` method and used when allocating game servers	game mode (3v3, tutorial, etc.) or game version (0.4, 0.5, etc.)

Multiplayer Backend Reference #

Party service #

Plugins #

Classes #

Configuration #

Extension data #

Game Instance service #

Plugins #

Classes #

Configuration #

Extension data #

Matchmaking service #

Plugins #

Classes #

Configuration #

Extension data #

Game server management #

Plugins #

Classes #

Configuration #

FleetServiceConfig #

ServerPoolManagementPolicyConfig #

Extension data #

Helpful? Yes No

What did you like?

What went wrong?