Matchmaking Components #

This section provides a baseline understanding of key components used in the Matchmaking service.

The Matchmaking Plugin #

Matchmaking-related logic can be implemented via the Matchmaking Plugin. By default, this plugin provides the most basic skeleton of a matchmaking flow, with the initialize, matchParties, matchPartiesWithGame, and endOfLoop function. In the Matchmaking Tasks topic, we’ll use these functions to guide us through understanding all relevant fields and customization options for the Matchmaking service. You can view all the Matchmaking Plugin methods and their properties on the MatchmakingPlugin reference page.

Matchmaking Service SDK #

Developers can use the Pragma SDK to communicate matchmaking tasks such as leaving matchmaking or getting matchmaking information. In the Matchmaking Tasks topic you’ll see examples of tasks that use the Pragma SDK for matchmaking purposes. You can view a list of the Matchmaking service SDK methods in the Matchmaking SDK and Events topic.

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

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.
`perferredGameServerZones`	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

New Game Instance #

When the Matchmaking service successfully matches two Matchables, a new game instance is generated and player and party data is sent to the game server.

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 QueueKey containing an `ExtMatchmakingKey` and a `GameServerVersion`
`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

Matchmaking Game Instances #

Matchmaking.GameInstance represents a game instance that has entered matchmaking to find more players. While Matchmaking Game Instances can still accept new parties, parties currently in the Matchmaking Game Instance can’t be removed by the Matchmaking service.

Matchmaking Game Instance Properties and Methods #

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.

Game Instance Update #

When an active game instance reenters the matchmaking process after calling EnterMatchmaking from the game server, the matchmaking plugin matchPartiesWithGame method is called. This method allows new parties to be added to the active game instance. If the matchmaking process determines that new parties can be added, the plugin will create a GameInstanceUpdate and return it. This results in parties being added to the active game instance and/or the game instance being removed from matchmaking.

Parties already on the MatchmakingGameInstance are available to assist in matchmaking but cannot be removed by the matchmaking service.

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

Testing #

Pragma Engine provides the MatchmakingTestFactory to test custom implementations of the MatchmakingPlugin. The test factory has methods to easily create a Matchable or MatchmakingGameInstance in various different states to test specific matchmaking scenarios.