How to Implement Simple, Advanced and Browse Matchmaking

This topic will show you how to implement matchmaking in you apps. Its recommended that you integrate matchmaking in steps, starting with the basics and then introducing data settings, queries, and skill components. You can find more details about these features and how add them in Skill, Data Settings and Queries for Matchmaking](/documentation/platform/latest/concepts/dg-matchmaking-4skill_queries/) page.

First, determine what kind of game you’re making and the type of matchmaking it needs. Read about the different types of matchmaking in the Matchmaking Overview.

Simple Quickmatch

The most basic Matchmaking scenario is a 2 player game where the match is not based on skill. For example, a board game like checkers or tic-tac-toe may want to use Simple Quickmatch. Simple Quickmatch will match users into system-generated rooms.

  1. Create a matchmaking pool, in the Matchmaking section of the Developer Center, with the following settings:
    • Pool Key = TicTacToe, BestOfThree or any value you’d like to use in your game.
    • Mode = Quickmatch
    • Users per Match = 2 for all fields.
    • Skill Component = None
    • Advanced Quickmatch = No
    • Should Consider Ping Time? = No
    • Save and Deploy to save the pool.
  2. After you’ve created the pool, add code to to add the user to the matchmaking queue. To do so, call ovr_Matchmaking_Enqueue2() from the client code. The user will be continually re-enqueued until they are successfully matched or cancel the process.
  3. After enqueueing the user, listen for the match notification ovrMessage_Notification_Matchmaking_MatchFound. Information about how the Platform SDK uses notifications can be found on the Requests and Messages page.
  4. (Optional) Review the methods in the OVR_MatchmakingEnqueueResult.h file for a list of methods you can call for information about the health of the queue that you may display to the user at this time.
  5. In your notification handler, call ovr_Room_Join2 with the roomID from the notification to place the user into the room.
  6. Your game will be listening for ovrNotification_Room_RoomUpdate for the number of users in the room. When the desired number of users is reached, your app will launch the game.
  7. Note that at any time in the matchmaking process, the user can call ovr_Matchmaking_Cancel2() to remove themselves from the queue and exit the matchmaking process.

Example Implementation

Our Unity sample app, VRHoops, is a simple ball shooting game that uses Simple Quickmatch. Please see the Sample Apps page for more information about the available sample apps.

Advanced Quickmatch

If we’re building a multiplayer game that involves more players (2-8) and has multiple modes, using Advanced Quickmatch will allows both users and the Matchmaking service to create rooms and matches for multiple users. For example, a first-person shooter may want to use Advanced Quickmatch as there may be multiple maps or users may wish to join matches already in progress.

  • Create your matchmaking pool, in the Matchmaking section of the Developer Center, with the following configurations:

    • Pool Key = CaptureTheFlag_TwoVsTwo or any value you’d like to use in your game.
    • Mode = Quickmatch
    • Users per Match = 2 for Min Users. 4 for Min Preferred. 6 for Max Preferred. 8 for Max Users.
    • Skill Component = None
    • Advanced Quickmatch = Yes
      1. Who can create rooms? - Choose Users and System
      2. Can unmatched people join matchmaking rooms? - Yes
      3. Can the matchmaking service keep matching into the same room? - Yes
      4. Enable host migration when the room owner leaves the room? - No (Please review the Room Ownership section below for more information about host migration. This feature requires an additional integration.)
    • Should Consider Ping Time? - No
    • Select Save and Deploy to save the pool.
  • Next, add code to the client-side app to support matchmaking. The example configuration allows both users and the system to create rooms, so these instruction describe how to handle both scenarios. You may need to support different/multiple scenarios depending on the configuration settings you chose when creating your pool and how the user wants to use the matchmaking service.

    If a user wants to join a match:

    1. Call ovr_Matchmaking_Enqueue2. The user will be continually re-enqueued until they are successfully matched or cancel the process.
    2. Handle the notification that the user was enqueued, ovrMessage_Matchmaking_Enqueue2. Information about how the Platform SDK uses notifications can be found on the Requests and Messages page.
    3. (Optional) Review the methods in the OVR_MatchmakingEnqueueResult.h file for a list of methods you can call for information about the health of the queue to display to the user.
    4. Be listening for the match notification, ovrMessage_Notification_Matchmaking_MatchFound.
    5. In your notification handler, call ovr_Room_Join2 to place the user into the room identified in the MatchFound notification.

    If the user wants to create a room and host a match:

    1. To create and enqueue the user and room, call either ovr_Matchmaking_CreateAndEnqueueRoom2 or ovr_Matchmaking_CreateRoom2, handle the response, and then call ovr_Matchmaking_EnqueueRoom2. The Room will be continually re-enqueued until canceled or a match is found.
    2. Handle the ovrMessage_Matchmaking_CreateAndEnqueueRoom2 or ovrMessage_Matchmaking_EnqueueRoom2 response.
    3. (Optional) Review the methods in the OVR_MatchmakingEnqueueResult.h file for a list of methods you can call for information about the health of the queue to display to the user.
    4. The Matchmaking service will search for matches.
    5. Your game will be listening for ovrNotification_Room_RoomUpdate for the number of users in the room. When the desired number of users is reached, your app will launch the game.
    6. At any time in the matchmaking process, the user can call ovr_Matchmaking_Cancel2() to remove themselves from the queue and exit the matchmaking process.

Browse

The following steps show how to implement matchmaking in a simple game users can browse and select the match that they want to join.

  • Create your matchmaking pool, in the Matchmaking section of the Developer Dashboard**, with the following configurations:

    • Pool Key = FreeForAll_Browse or any value you’d like to use in your game.
    • Mode = Browse
    • Users per Match = 2 for Min Users. 8 for Max Users. (We don’t specify Min or Max Preferred users for browse. The user will define this when they create the room.) * Skill Component = None
    • Should Consider Ping Time? = No
    • Select Save and Deploy to save the pool.
  • Next, add matchmaking support in your client code. Your code will need to support multiple scenarios depending on the configuration settings you chose when creating your pool and how the user wants to use the service.

    If the user wants to join a match:

    1. Call ovr_Matchmaking_Browse2 to get a list of the available rooms.
    2. Handle the ovrMessage_Matchmaking_Browse2 response and display the list of rooms to the user. You may wish to periodically refresh the list by periodically calling the browse method.
    3. Call ovr_Room_Join2 when the user has chosen a room.

    If the user wants to create a room and host a match:

    1. To create and enqueue the user and room, call either ovr_Matchmaking_CreateAndEnqueueRoom2 or call ovr_Matchmaking_CreateRoom2, handle the response, and then call ovr_Matchmaking_EnqueueRoom2.
    2. Handle the ovrMessage_Matchmaking_CreateAndEnqueueRoom2 or ovrMessage_Matchmaking_EnqueueRoom2 response.
    3. (Optional) Review the methods in the OVR_MatchmakingEnqueueResult.h file for a list of methods you can call for information about the health of the queue to display to the user.
  • Your game will be listening for ovrNotification_Room_RoomUpdate for the number of users in the room. When the desired number of users is reached, your app will launch the game.
  • At any time in the matchmaking process, you can call ovr_Matchmaking_Cancel2() to remove a user from the queue and exit the matchmaking process.

Room Ownership

Each user-generated matchmaking room is associated with the user who created the room. That user who created the room becomes the room’s owner. This role may have the permission to update the settings of the room, if you have configured the pool to allow this. During the course of the multiplayer session, it may be necessary to transfer ownership of the room. The requests to update room data and transfer ownership can be found on the Rooms page.

If the room owner leaves without transferring ownership, your pool may be configured to automatically transfer ownership to the user who has been in the room the longest. Enable this setting by choosing Yes for Enable host migration when the room owner leaves the room? when creating your pool.

Next Steps

Next, you can add a skill component or data settings and queries for more advance matching scenarios. For more information, see Adding Skill and Using Queries.