Oculus Rooms

Note: You are viewing the Unreal version of this topic. To view this topic for Unity development, see Oculus Rooms (Unity). To view this topic for native development, see Oculus Rooms (Native).

Oculus provides the Rooms feature so that you can enable virtual places for your users to come together to interact in your app.

There are three types of rooms:

• User-created private rooms for friends to interact in VR. These rooms are created on behalf of, and owned by, a user who can invite friends to join. When everyone has left a room, it is destroyed.
• System-moderated rooms that are persistent, server created, server moderated and maintained rooms.
• User-created matchmaking rooms These are created on behalf of a user, and used by the Matchmaking service for friends to participate in multiplayer game sessions.

After rooms are created; whether by the system or users, you can use the client room invite methods to help users find their friends and add them to rooms.

From a room users can optionally chat, and even launch a matchmaking session from some room types. Note that to combine rooms with chat and matchmaking, you must implement these features as well. For more information, see Voice Chat (VoIP) and Matchmaking.

Note: For Unreal development, see the OSS Sessions - Rooms and Matchmaking topic. You can also use the Platform native API listed in this topic and information found in the Platform Unreal Development - Get Setup guide.

Cross Platform Rooms

To support rooms across platforms, put your apps in the same application grouping. See Cross-Device Development with App Groupings for information about application groupings.

Create and Update Rooms

The next sections lists methods or links to more information about how to create and update different types of rooms.

User-Owned Private Rooms

Use the following methods to create and update user-owned rooms. Some of the APIs can only be on behalf of the room owner, which is the user that created the room. If the owner leaves the room, ownership of the room will be automatically transfer to the user who has been in the room the longest. Room ownership can also be manually transferred by calling ovr_Room_UpdateOwner().

Additional detail about each function can be found in the Platform SDK Reference Content.

System Moderated Rooms

Moderated rooms are created and managed by your trusted server. You use REST APIs to create and manage system-moderated rooms, but clients can join and leave these rooms. For more information, see Server APIs for Moderated Rooms.

Matchmaking Rooms

Matchmaking rooms are created by the matchmaking system. Information on how matchmaking works and APIs for matchmaking rooms can be found in the Matchmaking Guide guide.

Get, Join, and Leave Rooms (all types)

You can use the methods described in this section to get information and interact with all types of rooms (user-created, system-moderated and matchmaking) on behalf of a user from a client app. Details about each function can be found in the Platform SDK Reference Content.

Add Room Invites

Users can invite other users to join them in a social VR experience with room invites. A user can only be invited to apps they have an entitlement for. Also users can receive a room invite even if they are not in currently in VR.

You can enable users to send invites by constructing your own custom UI or using the Oculus UI provided with the Platform SDK.

Use a Custom UI

To build your own UI for room invites, make sure your integration does the following:

1. Make sure the user has joined the room for which they are sending invites. You can call GetCurrentRoomInformation to confirm.

2. Get a list of users that can be invited to that room. Call:

   ovr_Room_GetInvitableUsers2()

   These methods return a list of users that can be invited. This means friends of the current user that own the app, or non-friends who are logged in and recently interacted with the current user. Each item in the list contains:

   • An Oculus username
   • User-specific invite token

   Note: For APIs to retrieve recently met users (for display purposes), see Users, Friends, and Relationships, but note that you must use GetInvitableUsers2 to get invite tokens necessary for invites.

   Users are return in the order of how likely they are to join current user in a room. For example, the first users on the list would be users who are online and in the app. Also, the invitable users returned will be for the room the calling user is currently in. You may retrieve a list of invitable users for another room by providing the room id as a parameter in the call.

   Note: Apps created after September 2017 will automatically be opted-in to include recently met users in response to ovr_Room_GetInvitableUsers2. Apps created prior to that date may opt in to include the recently met results on the Rooms and Matchmaking page. If you don’t want to include recently met users, you may use that page to opt out. You can also specify in the request, using roomOptions, to not include recently met users.

3. Then invite the user to the Room passing the room ID and the invite token retrieved with GetInvitableUsers2:

   ovr_Room_InviteUser(roomID, inviteToken)

4. If you request room updates for the room when calling ovr_Room_Join2 by using the subscribeToUpdates parameter, your app will receive a notification of type ovrMessage_Notification_Room_RoomUpdate when the user joins. Be sure to listen for this notification.

Note: Each invite token can only be used once. To re-invite the same user, repeat the process and send a new invite.

Use the Oculus UI

To use the Oculus UI for room invites, follow these steps:

1. Make sure the user has joined the room for which he or she is sending invites. You can call ovr_Room_GetCurrent() to confirm.

2. To open the Oculus UI, temporarily background your app and call:

   ovr_Room_LaunchInvitableUserFlow()

   The user will see an interface outside of your app, in the SystemUI, that allows users to invite others. The platform will take care of the rest.

Note: Apps created after September 2017 will automatically be opted-in to include recently met users in the invitable user flow. Apps created prior to that date may opt in to include the recently met results on the Rooms and Matchmaking page. If you don’t want to include recently met users, you may use that page to opt out.

Enable Invites from Oculus Home

You can configure your app to launch invites directly from Oculus Home. This allows your users to jump directly into a social session in your app.

To accept invites outside of your application:

1. Oculus will provide the invite notifications to the user in Oculus Home on both Rift and mobile devices.
2. If the user accepts this notification Oculus will then launch your application.
3. To detect that the user launched from accepting an invite, you can look for an invite-accepted message when launching your app.

For a native app, when polling the message queue, look for the ovrMessage_Notification_Room_InviteAccepted message.

For example:

int messageType = ovr_Message_GetType(response);
if (messageType == ovrMessage_Notification_Room_InviteAccepted)
  {
    const char *roomIDString = ovr_Message_GetString(response);
    ovrID roomID;
    ovrID_FromString(&roomID, roomIDString));
    // we can now try to join the room
  }

Handle Updates and Notifications

There are two ways to receive updates for rooms.

1. You can check and pull notifications for a user by calling ovr_Notification_GetRoomInvites() for native apps, or Notifications.GetRoomInviteNotifications() for Unity apps. This method requires you to frequently check for invites and room updates.
2. You can add a listener to your game loop for notifications. This will notify you any time you receive a notification or message.On native apps, you’ll listen for ovrMessage_Notification_Room_InviteReceived. See the Requests and Messages page for an overview of notifications and the message queue.

Note: If using the second method and listening for notifications, it is recommended that you call the GetRoomInvites method on app startup to retrieve any existing notifications.

You’ll receive a notification any time a user enters, leaves, or is removed from a room. The roomId will be 0 if the user has left or been removed from a room.

Steps to Integrate User-Owned Rooms

Following are the basic steps add private user-owned rooms to your app.

1. Create the Room: Call ovr_Room_CreateAndJoinPrivate2() on behalf of a user to create and add them to a room. This user becomes the owner of the room.
   1. Specify the joinPolicy and maxUsers for the room when sending the create request. joinPolicy defines who is able to join the room; see RoomJoinPolicy for the available policies. Use maxUsers to specify the max number of users to the room. The max value for this parameter is 1,024.
   2. Once created, you can lock the room for the room owner by calling ovr_Room_UpdateMembershipLockStatus(). This will prevent new members from being able to join the room. Any users that are in the room at the time of lock will be able to rejoin.
2. Invite Friends Using the pre-built Oculus invites interface is the simplest way for your app to allow users to invite their friends. The app calls ovr_Room_LaunchInvitableUserFlow() with the roomId of the newly-created room. The invite interface opens so the user may find and invite users to the room.
3. Enable Users to Join the Room: Recipients of invites will receive a notification that they have been invited to join a room. This notification will be in their message queue.
   1. Handle the notification on the message queue and extract the roomId from the notification payload. Please see the Requests and Messages page for information about how the Platform SDK uses messages, notifications, and the queue.
   2. The invitee’s client can retrieve information about the room using ovr_Room_Get() with the roomId of the room. The response will be a Room message that contains the details about the room.
   3. If the invitee decides to join the room, add them using ovr_Room_Join2() with the roomId of the room.
   4. At any time the a client may call ovr_Room_Leave() to leave the room.

Test Using the Rooms and Matchmaking Debugger

The Room and Matchmaking Debugger is available to help developers identifying what connections and interactions a user or room makes with a room or matchmaking pool. Enter the ID of a user or room to get a list of the recent connections.

The table will display a chronological list of events for that user or room. Each row represents a single event with additional information about the occurrence. The results show what event occurred, when it occurred, what user initiated the event, and the room in which the event happened (if in a room). You can select any room or user ID returned in the table to retrieve the connection or interaction information about that user or room.

To retrieve the user and room ID’s:

• Retrieve the User ID - Please see the Users, Friends, and Relationships page for information about the SDK requests you can use to retrieve a User ID. Please note that this ID is not the same as the Org Scoped ID.
• Retrieve the Room ID - Use the SDK methods listed above to retrieve the User IDs.

Related Topics

• Server APIs for Moderated Rooms
• Rooms and Matchmaking with Unreal Sessions
• Matchmaking
• Users, Friends, and Relationships