Rooms and Matchmaking with the Unreal Sessions

Matchmaking and Rooms in Unreal uses the OSS Sessions interface.

The Oculus OSS Sessions integration is based on the concepts introduced in Epic’s Sessions and Matchmaking guide. Most of the functionality for Rooms and Matchmaking build on Epic’s IOnlineSession APIs.

Both the Rooms and Matchmaking integrations using the OSS Sessions interface are limited in scope. For a full-featured Room and Matchmaking integration, use the native C APIs.

Please note that when a session is created, either Room or Matchmaking, a VoIP connection is not created. You’ll have to integrate Voice Chat (VoIP) if you want to enable voice chat in your app.

About Rooms

Oculus uses Rooms as a place for players to gather, these Rooms map to Sessions in Unreal. Oculus Rooms can be expressed in your app in multiple ways: user rooms, matchmaking rooms, and moderated rooms. We’ll discuss how to add matchmaking rooms in the next section, while moderated rooms are created by the server-to-server API calls defined on the Rooms page.

User rooms are not enqueued in the matchmaking service and can not later be promoted.

Integrate User Rooms

The following steps describe a basic Rooms integration.

Blueprint

  1. User wants to join a room:
    • Add the Join Session blueprint Node.
  2. User wants to create a room:
    • Add Create Session to your app blueprint. Leave the name of Oculus Matchmaking Pool blank.

Code

  1. User wants to join a room:
    • Call JoinSession().
  2. User wants to create a room:
    • Call CreateSession() with NewSessionSettings.Settings as null.

About Matchmaking

The process to add matchmaking requires that you first create the matchmaking pools, then add the matchmaking service to your app. This guide will review some of the basics and background required for the Unreal integration, but we recommend that you review the complete native Matchmaking guide for a complete overview of the matchmaking service as well as how to create and manage Moderated Rooms.

Matchmaking Modes

There are different kinds of matchmaking that you can set up. Choose the multiplayer experience that you want your players to have.

  • System matches for 2-4 users that all join at the same time

    Choose No for Should Pool Manage Rooms?. This means the system manages a pool of users looking for matches, and rooms are created for players once a match has been made. Simple Matchmaking is designed for 2-4 player games, like chess, checkers or tennis, where users don’t need the ability to join matches in progress. For more information how to set up simple matchmaking , see the Simple Matchmaking section of the Matchmaking How-to.

  • System matches for user-created rooms, and the ability to join/leave games in progress

    Choose Yes for Should Pool Manage Rooms?, and both Users and System for Who can create rooms? This means the system manages a pool of users looking for matches and a list of rooms for that pool, where each room might have different matchmaking settings. You configure whether rooms are created by the user, by the matchmaking service, or both. Advanced matchmaking is designed for more complicated games with multiple match options, and where users may join, or leave, during the course of a match. For more information about how to set up an advanced match, see the Advanced Matchmaking section of the Matchmaking How-to.

  • System manages a pool of rooms that can be browsed by users.

    Choose Yes for Should Pool Manage Rooms?, and Users for Who can create rooms?. This results in a pool of rooms. Users can create and host rooms or choose from a list of rooms to join. Browse also supports more complicated games with multiple match options and users may join and leave a match in progress. For more information about how to set up a browse scenario, see the Browse section of the Matchmaking How-to.

Before integrating Matchmaking, you’ll need to create your pools of users. Please see the Pools section of the Configuration Overview page for information about creating Matchmaking and skill components. Please note that the Data Settings and Matchmaking Queries described on that page are not available through the OSS interface.

Integrate Matchmaking

The following steps describe a basic matchmaking integration.

Blueprint

  1. Create a matchmaking pool. Example pools can be found on the Matchmaking Quickstart w/Advanced Options page.
  2. User wants to join a match:
    • Add Join Session to your app blueprint to enqueue the player in the Matchmaking service.
  3. User wants to create a match:
    • Add Create Session to your app blueprint, pass the name of the Matchmaking pool you created. The room will be automatically enqueued in the Matchmaking service.
  4. (Optional) At any time, you may use the Set Session Enqueue to enqueue or dequeue the current session in the matchmaking pool.

Code

  1. Create a matchmaking pool. Example pools can be found on the Matchmaking Quickstart w/Advanced Options page.
  2. User wants to join a match:
    • Call StartMatchmaking() to enqueue the user in the Matchmaking service. Pass the key for the matchmaking pool you created to start matchmaking.
  3. User wants to create a match: Call CreateSession() with NewSessionSettings.Settings as the key for the matchmaking pool you created and NewSessionSettings.bShouldAdvertise as true to enqueue the session in the Matchmaking service. If the user wants to remove the room from the Matchmaking service, call UpdateSession() with UpdatedSessionSettings.bShouldAdvertise as false.

Integrate Matchmaking - Browse

The following steps describe a basic browse matchmaking integration.

Blueprint

  1. Create a matchmaking pool that supports browsing. Example pools can be found on the Matchmaking Quickstart w/Advanced Options page.
  2. User wants to join a match:
    • Add Find Matchmaking Sessions to your app blueprint and pass the name of your Matchmaking pool to retrieve a list of available sessions. If using Moderated rooms, add Find Moderated Sessions instead.
    • Then when the user has selected their desired session, pass the SessionName to the Join Session blueprint Node.
    • Optional - When you display the list of rooms to the user, you can retrieve metadata about the room by adding the Get Current Players, Get Max Players, Get Ping in MS, and Get Server Name nodes.
  3. User wants to create a match (if supported):
    • Add Create Session to your app blueprint, pass the name of the matchmaking pool you created. The room will be automatically enqueued.
  4. (Optional) At any time, you may use the Set Session Enqueue to enqueue or dequeue the current session in the matchmaking pool.

Code

  1. Create a matchmaking pool that supports browsing. Example pools can be found on the Matchmaking Quickstart w/Advanced Options page.
  2. User wants to join a match:
    • First call FindSessions() and pass the name of your matchmaking pool to retrieve a list of available sessions. Define QuerySettings as OCULUSPOOL in the SearchSettings if finding Matchmaking rooms or define QuerySettings as OCULUSMODERATEDROOMSONLY if using Moderated rooms.
    • Then when the user has selected their desired session, call JoinSession().
  3. User wants to create a match (if supported):
    • Call CreateSession() with NewSessionSettings.Settings as the key of your matchmaking pool and NewSessionSettings.bShouldAdvertise as true to enqueue the session in the Matchmaking service. If the user wants to remove the room from the matchmaking service, call UpdateSession() with UpdatedSessionSettings.bShouldAdvertise as false.