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 #

Calldescription
EnterMatchmakingEnters the party into matchmaking once all players are ready. Only a party leader can enter a party into matchmaking.
LeaveMatchmakingRemoves a party from matchmaking
GetMatchmakingInfoGets matchmaking queue information

Match API (game server) SDK methods #

Calldescription
EnterMatchmakingEnters an existing game instance into matchmaking to find more players
LeaveMatchmakingRemoves 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.

methoddescription
initializeUse to initialize the matchmaking service. Perform any validation logic or initial transformations to party, players, or ExtMatchable here.
matchPartiesCalled 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.
matchPartiesWithGameCalled during the main matchmaking loop when a live game instance enters matchmaking to request more players
endOfLoopCalled 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
getQueueNameAllows 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/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
extext 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/methoddescription
partyIDUnique party ID
playersList of Matchmaking.Players in the party
extext payload (ExtMatchmakingParty) containing customer-defined information about the matchmaking party
preferredGameServerZonesList 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

Matchmaking game instances #

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

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

New game instances #

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

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 key for the matchmaking queue that the game will be added to if markedToContinueMatchmaking is true
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

Game instance updates #

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

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. Populated by PartyPlugin.buildExtMatchmakingKeygame 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
ExtMatchableStores 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.

EventTriggerData returned
OnEnteredMatchmakingThe party enters matchmakingN/A
OnLeftMatchmakingThe party leaves matchmakingN/A
OnMatchmakingFailedPlayer is removed from matchmakingMatchmaking failure reason (UNSPECIFIED or GAME_SERVER_VERSION_NO_LONGER_COMPATIBLE)

Game server events #

The following events are handled by the game server.

EventTriggerData returned
OnGameInstanceEnteredMatchmakingThe given active game instance enters matchmakinggame instance ID
OnGameInstanceLeftMatchmakingThe given active game instance leaves matchmakinggame instance ID

Errors #

  • MatchmakingService_QueueNotFound
  • MatchmakingService_MatchAlreadyStarted
  • MatchmakingService_PlayerAlreadyInQueue
  • MatchmakingService_PartyTooBig
  • MatchmakingService_InfoNotAvailable
  • MatchmakingService_PlayerUpdateFailed
  • MatchmakingService_PartyUpdateFailed