Matchmaking Backend Reference #

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

Matchmaking plugin #

The Matchmaking Plugin is used to define all custom matchmaking logic within the engine.

method	description
`initialize()`	Use to initialize the matchmaking service. Perform any validation logic or initial transformations to party, players, or `ExtMatchable` here.
`matchParties()`	Called during the main matchmaking loop to match parties to form a game instance. This method is called many times, evaluating each party that has joined the matchmaking queue.
`matchPartiesWithGame()`	Called during the main matchmaking loop when a live game instance enters matchmaking to request more players
`endOfLoop()`	Called after completing a matchmaking loop to give the plugin a chance to start a new game instance even if it was not filled during the iteration
`getQueueName()`	Allows you to specify a concise name for your matchmaking queues when represented in logs and metrics

Data classes #

Matchables #

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

property	description
`parties`	List of parties in the Matchable
`players`	List of players from each party in the Matchable
`ext`	`ext` payload (`ExtMatchable`) to store the result of in-memory calculations performed within the Matchmaking loop

method	description
`getPlayer()`	Returns a player in this Matchable, identified by player ID
`takePartiesFrom()`	Moves specified parties into the Matchable

Matchmaking parties #

Matchmaking.Party represents a party in matchmaking. The object provides access to any party details that might be necessary to evaluate when making matchmaking decisions.

property	description
`partyID`	Unique party ID
`players`	List of `Matchmaking.Players` in the party
`ext`	`ext` payload (`ExtMatchmakingParty`) containing customer-defined information about the matchmaking party
`preferredGameServerZones`	List of game server zones
`playerCount`	Integer representing the number of players in the party

method	description
`secondsInQueue()`	Returns a long representing the number of seconds the party has been in the matchmaking queue

Matchmaking players #

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

property	description
`playerId`	Unique player ID
`gameServerZoneToPing`	Map key representing the game server zone to ping
`partyId`	Party ID for the party the player belongs to
`teamNumber`	Player’s assigned team number
`ext`	`ext` payload (`ExtMatchmakingPlayer`) containing customer-defined information about the matchmaking player

Matchmaking game instances #

Matchmaking.GameInstance represents a game that has re-entered matchmaking to find more players.

property	description
`id`	Unique identifier for the game instance
`players`	List of players in the game instance
`removedPlayers`	List of players previously removed from the game instance
`gameServerVersion`	The GameServerVersion the game instance is running within
`gameServerZone`	The game server zone the game instance is using
`ext`	The `ExtMatchmakingGameInstance` created when the game instance entered matchmaking

method	description
`getPlayer()`	Returns an active GamePlayer from the game instance, identified by player ID
`getPlayersByPartyId()`	Returns all active GamePlayers, organized by party ID
`getPlayersByTeamNumber()`	Returns all active GamePlayers, organized by team number
`secondsInQueue()`	Returns the time since the game instance joined the queue (in seconds)

Matchmaking game instance players #

Matchmaking.GamePlayer represents an active player in a Matchmaking.GameInstance.

property	description
`playerId`	Unique player id
`partyId`	Party id for the party to player belongs to
`teamNumber`	Team number for the team the player is on
`ext`	The `ExtMatchmakingGamePlayer` representing any custom details about the game player

New game instances #

Matchmaking.NewGameInstance represents a successful matchmaking result that will be used to allocate a new game.

property	description
`requestExt`	The `ExtBackendCreateRequest` used to start the game
`gameServerZone`	The game server zone the `NewGameInstance` is using
`markedToContinueMatchmaking`	Calculated as `true` if `NewGameInstance.continueMatchmaking` has been called
`matchmakingQueueKey`	The key for the matchmaking queue that the game will be added to if `markedToContinueMatchmaking` is true
`players`	List of players in the `NewGameInstance`.

method	description
`addPlayers()`	List of players to add to the `NewGameInstance`
`setTeamByPlayers()`	Adds a player to a specific team (Default team number: 0)
`setExtForPlayer()`	Updates the `ExtBackendAddPlayer` payload for a given player in the new game instance
`continueMatchmaking()`	Continues the matchmaking process after the game instance is created

Game instance updates #

GameInstanceUpdate represents an update to an active game instance that is in matchmaking.

property	description
`requestExt`	The `ExtBackendAddPlayersRequest` used to update a game instance
`players`	List of players that have been added to the GameInstanceUpdate
`markedToContinueMatchmaking`	Calculated as `true` if `GameInstanceUpdate.stopMatchmaking` has not been called

method	description
`addPlayers()`	List of players to add to the `GameInstanceUpdate`
`setTeamByPlayers()`	Adds a list of players to a specific team (Default team number: 0)
`setExtForPlayer()`	Updates the `ExtBackendAddPlayer` payload for a given player in the game instance update
`stopMatchmaking()`	Stops searching for more players once this game instance update is returned

Matchmaking API backend class #

The MatchmakingApi.kt backend class is the entrypoint to the matchmaking service from other backend services or plugins.

method	description
`isInMatchmaking()`	Checks whether a single player or list of players, identified by player ID, is/are in matchmaking

Extension data #

You can use Extension Data (exts) to define custom data about parties and game instances while they are in the matchmaking process. These fields are passed to other plugins as necessary. See Matchmaking Tasks for sample implementation.

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

Errors #

MatchmakingService_QueueNotFound
MatchmakingService_MatchAlreadyStarted
MatchmakingService_PlayerAlreadyInQueue
MatchmakingService_PartyTooBig
MatchmakingService_InfoNotAvailable
MatchmakingService_PlayerUpdateFailed
MatchmakingService_PartyUpdateFailed