How to Implement Simple, Browse and Advanced Matchmaking (Deprecated)
Updated: May 23, 2024
For more information on the deprecation of this API, click here.
Third-party solutions, such as Photon, can be used as an alternative to implement matchmaking in your app. For an example of how Photon, and other third-party solutions integrate with the Platform API, check here.
This topic will show you how to implement matchmaking in your apps. Its recommended that you integrate matchmaking in steps, starting with simple matchmaking and then adding 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 page.
This is a Platform SDK feature requiring Data Use Checkup
To use this or any other Platform SDK feature, you must complete a Data Use Checkup (DUC). The DUC ensures that you comply with Developer Policies. It requires an administrator from your organization to certify that your use of user data aligns with platform guidelines. Until the app review team reviews and approves your DUC, platform features are only available for test users.
Before you start your implementation, you should consider the type of game you’re making and the type of matchmaking it needs. Read about the different types of matchmaking in the Matchmaking Overview.
Simple Matchmaking
The most basic matchmaking scenario is a 2 player game where the match is not based on skill. In this scenario the system matches users and puts them in a room for that match. A room is created to host the match, and removed by the system when the match is over. For example, a board game like checkers or tic-tac-toe would be a good candidate for simple matchmaking.
To create an app with simple matchmaking:
Create a matchmaking pool. Navigate to Developer Dashboard, then the Platform > Matchmaking section. Use the following settings:
Pool Key = TicTacToe, BestOfThree or any value you’d like to use in your game.
Users per Match = 2 for all fields.
Skill Component = None
Should Pool Manage Rooms? = No
Should Consider Ping Time? = No
Save and Deploy to save the pool.
After you’ve created the pool, add code 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.
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.
(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.
In your notification handler, call ovr_Room_Join2 with the roomID from the notification to place the user into the room.
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.
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.
Browse Matchmaking
Browse matchmaking means that users can browse and join existing rooms, and create rooms for other users to join. For this scenario you must enable the matchmaking pool to manage a queue of rooms.
The following steps show how to implement matchmaking in a game that allows users to browse and select the match that they want to join.
1. Create the matchmaking pool.
Navigate to Developer Dashboard, then the Platform > Matchmaking section. Select Create Pool. Provide the following configuration:
Pool Key = FreeForAll_Browse or any value you’d like to use in your game.
Should Pool Manage Rooms = Yes
Who can create rooms? Select Users
Can unmatched people join matchmaking rooms? - Yes
Can the matchmaking service keep matching into the same room? - Yes
Enable host migration when the room owner leaves the room? - Yes. Note, there is extra implementation to migrate rooms. See Room Ownership
Users per Match = 2 for Min Users. 8 for Max Users. (Don’t specify Min or Max Preferred users for browse. The user defines these values when they create the room.)
Skill Component = None
Should Consider Ping Time? = No
When you’ve finished the pool configurations, select Save and Deploy to save the pool.
2. 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:
Call ovr_Matchmaking_Browse2 to get a list of the available rooms.
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.
Call ovr_Room_Join2 when the user chooses room.
If the user wants to create a room and host a match:
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.
Handle the ovrMessage_Matchmaking_CreateAndEnqueueRoom2 or ovrMessage_Matchmaking_EnqueueRoom2 response.
(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.
Note: 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.
Advanced Matchmaking with Optional Browse
Advanced matchmaking applies to multi-player games that have multiple modes of play and involve 2-8 players. In this scenario, players may also join or leave games in progress. Optionally, you can enable users to browse for rooms to join.
To support this type of game, you must enable the matchmaking pool to manage a queue of rooms. You should also allow both users and the matchmaking service to create rooms with the option to enable users to browse for matches. For example, a first-person shooter might require a queue of rooms with browse enabled because the game has multiple maps or users may wish to browse or be matched to sessions already in progress.
1. Create your matchmaking pool.
Navigate to Developer Dashboard, then the Platform > Matchmaking section. Create a pool with the following configurations:
Pool Key = CaptureTheFlag_TwoVsTwo or any value you’d like to use in your game.
Users per Match = 2 for Min Users. 4 for Min Preferred. 6 for Max Preferred. 8 for Max Users.
Skill Component = None
Should Pool Manage Rooms? = Yes
Who can create rooms? To enable advanced matchmaking and browsing, select Users and System. If you do not want to allow browsing, choose System only.
Can unmatched people join matchmaking rooms? - Yes
Can the matchmaking service keep matching into the same room? - Yes
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 implementation.)
Should Consider Ping Time? - No
When you’re finished entering the pool configurations, select Save and Deploy to save the pool.
2. 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:
Call ovr_Matchmaking_Enqueue2. The user will be continually re-enqueued until they are successfully matched or cancel the process.
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.
(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.
Be listening for the match notification, ovrMessage_Notification_Matchmaking_MatchFound.
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:
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.
Handle the ovrMessage_Matchmaking_CreateAndEnqueueRoom2 or ovrMessage_Matchmaking_EnqueueRoom2 response.
(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.
The Matchmaking service will search for matches.
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.
Note: 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.
