Matchmaking Reference #

Matchmaking service SDK methods #

The Pragma SDK provides methods that developers can use to facilitate matchmaking processes, such as entering, leaving, or re-entering matchmaking. The SDK includes methods for Matchmaking service implementation through the PartyApi and the MatchApi, depending on whether the call comes from the player client or game server, respectively. The tables below contains a list of all the methods relevant to the Matchmaking service.

Party API (player client) SDK methods #

Call	description
`EnterMatchmaking`	Enters the party into matchmaking once all players are ready. Only a party leader can enter a party into matchmaking.
`LeaveMatchmaking`	Removes a party from matchmaking
`GetMatchmakingInfo`	Gets matchmaking queue information

Match API (game server) SDK methods #

Call	description
`EnterMatchmaking`	Enters an existing game instance into matchmaking to find more players
`LeaveMatchmaking`	Removes a game instance from matchmaking

The SDK calls invoke various Matchmaking Plugin methods through Matchmaking service RPCs.

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/method	description
`parties`	List of parties in the Matchable
`players`	List of players from each party in the Matchable
`findPlayer`	Finds a player within the parties in this Matchable with a given player ID
`takePartiesFrom`	Moves specified parties into the Matchable
`ext`	`ext` payload (`ExtMatchable`) to store the result of in-memory calculations performed within the Matchmaking loop

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/method	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
`secondsInQueue`	Returns an integer 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
`socialId`	Unique social ID
`displayName`	The player’s public display name
`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 teams #

Matchmaking.Team represents an in-game team within matchmaking. The object provides access to the list of players associated with that team number, for convenient evaluation of the properties of all of a team’s members.

property/method	description
`teamNumber`	Number identifying the team
`players`	List of matchmaking players on the team
`playerCount`	Returns an integer representing how many players are on the team

Matchmaking game instances #

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

property/method	description
`ext`	The `ExtMatchmakingGameInstance` created when the game instance entered matchmaking
`players`	List of players in the game instance
`parties`	List of parties in the game instance
`teams`	List of teams in the game instance
`removedPlayers`	List of players previously removed from the game instance
`gameServerZone`	The game server zone the game instance is using
`secondsInQueue`	Returns the time since the game instance joined the queue (in seconds)
`findPlayer`	Finds a player within the parties in this game instance with a given player ID

Matchmaking game instance parties #

Matchmaking.GameParty represents an in-game party within a Matchmaking.GameInstance.

property	description
`partyId`	Unique party id
`players`	List of players in the game party
`playerCount`	Number of players in the game party
`ext`	The `ExtMatchmakingGameParty` representing any custom details about the game party

Matchmaking game instance players #

Matchmaking.GamePlayer represents an in-game player within a Matchmaking.GameInstance.

property	description
`playerId`	Unique player id
`socialId`	Unique social id
`displayName`	The player’s public display name
`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 #

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

property/method	description
`ext`	The `ExtGameInstance` used to start the game
`players`	List of players in the NewGameInstance
`parties`	List of parties in the NewGameInstance
`gameServerZone`	The game server zone the NewGameInstance is using
`matchmakingQueueKey`	The key for the matchmaking queue that the game will be added to if `markedToContinueMatchmaking` is true
`addParties`	Adds multiple parties to the new game instance
`setTeamByPlayers`	Adds a player to a specific team. Default team number: 0
`setExtGamePlayer`	Updates the `ExtGamePlayer` payload for a given player in the new game instance
`setExtGameParty`	Updates the `ExtGameParty` payload for a given party 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/method	description
`parties`	List of parties that have been added to the GameInstanceUpdate
`players`	List of players that have been added to the GameInstanceUpdate
`addParties`	Adds parties to the GameInstanceUpdate, optionally setting their team number
`setTeamByPlayers`	Adds a list of players to a specific team. Default team number: 0
`setExtGamePlayer`	Updates the `ExtGamePlayer` payload for a given player in the game instance update
`setExtGameParty`	Updates the `ExtGameParty` payload for a given party in the game instance update
`stopMatchmaking`	Stops searching for more players once this game instance update is returned

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
`ExtMatchmakingGameParty`	Data specific to a party within a game instance that is currently in matchmaking. This data is populated by `buildExtMatchmakingGameParty` and persists on the engine for the duration of the party’s time in the matchmaking game instance.	matchmaking style
`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

Events #

There are several matchmaking-related events that player clients and game servers can listen to. The following tables contain bindable events relevant to the Matchmaking service, along with associated descriptions of when the event is triggered.

Player client events #

The following events are handled by the player client.

Event	Trigger	Data returned
`OnEnteredMatchmaking`	The party enters matchmaking	N/A
`OnLeftMatchmaking`	The party leaves matchmaking	N/A
`OnMatchmakingFailed`	Player is removed from matchmaking	Matchmaking failure reason (`UNSPECIFIED` or `GAME_SERVER_VERSION_NO_LONGER_COMPATIBLE`)

Game server events #

The following events are handled by the game server.

Event	Trigger	Data returned
`OnGameInstanceEnteredMatchmaking`	The given active game instance enters matchmaking	game instance ID
`OnGameInstanceLeftMatchmaking`	The given active game instance leaves matchmaking	game instance ID

Errors #

MatchmakingService_QueueNotFound
MatchmakingService_MatchAlreadyStarted
MatchmakingService_PlayerAlreadyInQueue
MatchmakingService_PartyTooBig
MatchmakingService_InfoNotAvailable
MatchmakingService_PlayerUpdateFailed
MatchmakingService_PartyUpdateFailed