Matchmaking Reference #
Matchmaking service SDK methods #
The table below contains a list of the SDK methods relevant to the Matchmaking service. These methods are available via the
|Allows a player to leave matchmaking. Removes their whole party from matchmaking.
|Queries information on matchmaking queues.
The SDK calls invoke various Matchmaking Plugin methods through Matchmaking service RPCs. For a list of Matchmaking service RPCs, see the MatchmakingService reference page.
Data classes #
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.
|List of parties in the Matchable
|List of players from each party in the Matchable
|Finds a player within the parties in this Matchable with a given player ID
|Moves specified parties into the Matchable
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.
|Unique party ID
Matchmaking.Players in the party
ext payload (
ExtMatchmakingParty) containing customer-defined information about the matchmaking party
|List of game server zones
|Integer representing the number of players in the party
|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.
|Unique player ID
|Unique social ID
|The player’s public display name
|Map key representing the game server zone to ping
|Party ID for the party the player belongs to
|Player’s assigned team number
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.
|Number identifying the team
|List of matchmaking players on the team
|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.
ExtMatchmakingGameInstance created when the game instance entered matchmaking
|List of players in the game instance
|List of parties in the game instance
|List of teams in the game instance
|List of players previously removed from the game instance
|The game server zone the game instance is using
|Returns the time since the game instance joined the queue (in seconds)
|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
|Unique party id
|List of players in the game party
|Number of players in the game party
ExtMatchmakingGameParty representing any custom details about the game party.
Matchmaking game instance players #
Matchmaking.GamePlayer represents an in-game player within a
|Unique player id
|Unique social id
|The player’s public display name
|Party id for the party to player belongs to
|Team number for the team the player is on
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.
ExtGameInstance used to start the game
|List of players in the NewGameInstance
|List of parties in the NewGameInstance
|The game server zone the NewGameInstance is using
|The key for the matchmaking queue that the game will be added to if
markedToContinueMatchmaking is true
|Adds multiple parties to the new game instance
|Adds a player to a specific team. Default team number: 0
ExtGamePlayer payload for a given player in the new game instance
ExtGameParty payload for a given party in the new game instance
|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.
|List of parties that have been added to the GameInstanceUpdate
|List of players that have been added to the GameInstanceUpdate
|Adds parties to the GameInstanceUpdate, optionally setting their team number
|Adds a list of players to a specific team. Default team number: 0
ExtGamePlayer payload for a given player in the game instance update
ExtGameParty payload for a given party in the game instance update
|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.
|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
|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
|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.
|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.
|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.
|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.
|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.
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.
|The party enters matchmaking
|The party leaves matchmaking
|A player is added to the game instance. The game server is not yet ready
|Player is removed from matchmaking
Game server events #
The following events are handled by the game server.
|The given active game instance enters matchmaking
|The given active game instance leaves matchmaking