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/methoddescription
partiesList of parties in the Matchable
playersList of players from each party in the Matchable
findPlayerFinds a player within the parties in this Matchable with a given player ID
takePartiesFromMoves 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/methoddescription
partyIDUnique party ID
playersList of Matchmaking.Players in the party
extext payload (ExtMatchmakingParty) containing customer-defined information about the matchmaking party
perferredGameServerZonesList of game server zones
playerCountInteger representing the number of players in the party
secondsInQueueReturns 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.

propertydescription
playerIdUnique player ID
socialIdUnique social ID
displayNameThe player’s public display name
gameServerZoneToPingMap key representing the game server zone to ping
partyIdParty ID for the party the player belongs to
teamNumberPlayer’s assigned team number
extext 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/methoddescription
teamNumberNumber identifying the team
playersList of matchmaking players on the team
playerCountReturns 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/methoddescription
extThe ExtGameInstance used to start the game
playersList of players in the NewGameInstance
partiesList of parties in the NewGameInstance
gameServerZoneThe game server zone the NewGameInstance is using
matchmakingQueueKeyThe QueueKey containing an ExtMatchmakingKey and a GameServerVersion
addPartiesAdds multiple parties to the new game instance
setTeamByPlayersAdds a player to a specific team. Default team number: 0
setExtGamePlayerUpdates the ExtGamePlayer payload for a given player in the new game instance
setExtGamePartyUpdates the ExtGameParty payload for a given party in the new game instance
continueMatchmakingContinues 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/methoddescription
extThe ExtMatchmakingGameInstance created when the game instance entered matchmaking
playersList of players in the game instance
partiesList of parties in the game instance
teamsList of teams in the game instance
removedPlayersList of players previously removed from the game instance
gameServerZoneThe game server zone the game instance is using
secondsInQueueReturns the time since the game instance joined the queue (in seconds)
findPlayerFinds 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.

propertydescription
partyIdUnique party id
playersList of players in the game party
playerCountNumber of players in the game party
extThe ExtMatchmakingGameParty representing any custom details about the game party.

Matchmaking Game Instance Players #

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

propertydescription
playerIdUnique player id
socialIdUnique social id
displayNameThe player’s public display name
partyIdParty id for the party to player belongs to
teamNumberTeam number for the team the player is on
extThe 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/methoddescription
partiesList of parties that have been added to the GameInstanceUpdate
playersList of players that have been added to the GameInstanceUpdate
addPartiesAdds parties to the GameInstanceUpdate, optionally setting their team number
setTeamByPlayersAdds a list of players to a specific team. Default team number: 0
setExtGamePlayerUpdates the ExtGamePlayer payload for a given player in the game instance update
setExtGamePartyUpdates the ExtGameParty payload for a given party in the game instance update
stopMatchmakingStops 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.

extdescriptionExample data
ExtMatchmakingKeyData 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
ExtMatchmakingPartyParty 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
ExtMatchmakingPlayerPlayer 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
ExtMatchmakingGameInstanceGame 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
ExtMatchmakingGamePartyData 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
ExtMatchmakingGamePlayerData 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.