Share via

Implement matchmaking in your game

This article provides a summary of the steps to implement matchmaking in your game. For detailed information, be sure to review the articles in the See also section at the end of this article.

Implement Matchmaking by using the Microsoft Azure PlayFab Lobby and Matchmaking SDK

The layFab Lobby and Matchmaking SDK is now part of the GDK.

  1. Download and set up the Azure PlayFab Lobby and Matchmaking SDK: download the C/C++ SDK for your platform, and then integrate the provider header and library files into your build.
  2. Authenticate the player: players must be authenticated with both Xbox services and Microsoft Azure PlayFab before using features that rely on these services in your games.
  3. Initialize the PlayFab Multiplayer SDK: initialize the SDK by calling PFMultiplayerInitialize. Set the entity key and token used by the library on behalf of your players by calling PFMultiplayerSetEntityToken.
  4. Configure matchmaking queues: match configuration centers around queues, which represent a place where tickets wait to be matched with each other. Each queue has some general configuration information about what's required for a match. In addition, a queue can contain a set of rules that provide further restrictions on how tickets are matched together. For specific information, see Configuring matchmaking queues.
  5. Create a matchmaking ticket: create a matchmaking ticket by using PFMultiplayerCreateMatchmakingTicket. Specify all local players that want to be part of the match and any attributes you want associated with those players. There are three different scenarios for creating a matchmaking ticket:
    • Implement matchmaking with a single local player: call PFMultiplayerCreateMatchmakingTicket with a single PFEntityKey to start matchmaking for a single local player.
    • Implement matchmaking with a group of remote players.
      1. The leader creates the ticket by using PFMultiplayerCreateMatchmakingTicket. It specifies the other players in the group through the configuration parameter.
      2. Call PFMatchmakingTicketGetTicketId to get the ticket ID.
      3. Send this ID to each other player by using an external mechanism, such as a networking mesh or a shared PlayFab Lobby. Have each client call PFMultiplayerJoinMatchmakingTicketFromId with the ticket ID to join the matchmaking ticket.
      4. The ticket status will be PFMatchmakingTicketStatus::WaitingForPlayers while waiting for the specified players to join. The status changes to PFMatchmakingTicketStatus::WaitingForMatch after all the players have joined the ticket.
    • Implement matchmaking with multiple local players.
      1. Pass a list of PFEntityKey and a corresponding list of attributes for each player to the PFMultiplayerCreateMatchmakingTicket or PFMultiplayerJoinMatchmakingTicketFromId functions.
      2. Ensure each list entry position matches, so that the first entry in the attributes list corresponds to the first player in the PFEntityKey list.
  6. Check the status of the matchmaking ticket: check for updates to the ticket by calling PFMultiplayerStartProcessingMatchmakingStateChanges to receive state changes. Call PFMultiplayerFinishProcessingMatchmakingStateChanges when you're done processing those state changes. The SDK returns a TicketStatusChanged state change whenever the status of the ticket changes and a TicketCompleted state change when matchmaking is done.
  7. Get the match: after receiving the PFMatchmakingStateChangeType::TicketCompleted state change, call PFMatchmakingTicketGetMatch to get the details of the match.
  8. Cancel a matchmaking ticket: to cancel the matchmaking process prior to the timeout set in the PFMatchmakingTicketConfiguration, call PFMatchmakingTicketCancel with the ticket handle.
  9. Connecting your players together into a lobby (optional): after the players have matched, they can join up together in a lobby. The PFMatchmakingMatchDetails from the matched ticket contains a lobbyArrangementString field, which can be used to join the players into the same lobby. This allows integration between the features. If you have your own technology, you can use it.
  10. Allocating server functionality (optional): matchmaking includes an option that can automatically create a game server for the resulting match. The allocated server runs a build, which is configured in the queue's configuration file. On startup, the server is passed in the members of the match as the list of initial players. A matchmaking queue is tied to a single multiplayer server build or to a build alias. For specific information, see Integrating with PlayFab Multiplayer Servers.

See also

The PlayFab documentation is the best source of up-to-date information. For details, see the following articles and sample.