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:
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 that this feature accesses user data and may require you to complete the Data Use Checkup form prior to submitting your app to the Oculus Store. For more information, see Complete a Data Use Checkup.
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.
The next sections lists methods or links to more information about how to create and update different types of 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.
Task Description | Function |
---|---|
Create a private user-generated room. These rooms cannot be changed to matchmaking rooms. For matchmaking rooms, use CreateRoom2 method. For more information, see Matchmaking. | ovr_Room_CreateAndJoinPrivate2() |
Remove a user from a room. This method can only be called on behalf of the room owner. | ovr_Room_KickUser() |
Update a room’s metadata. Use this method to add up to 2,000 key/value pairs to the room metadata. This method can only be called on behalf of the room’s owner. | ovr_Room_UpdateDataStore() |
Update the room join policy, or the definition of who can join the room. This method can only be called on behalf of the room’s owner. | ovr_Room_UpdatePrivateRoomJoinPolicy() |
Lock the membership of the room. Calling this method with true prevents additional users from joining the room. This method can only be called on behalf of the room’s owner. | ovr_Room_UpdateMembershipLockStatus() |
Transfer ownership of the room to another user. This method can only be called on behalf of the current room’s owner. | ovr_Room_UpdateOwner() |
Set or change the description of the room. This method can only be called on behalf of the room’s owner. | ovr_Room_SetDescription() |
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.
Task Description | Link |
---|---|
Create a moderated room. | Create a Moderated Room |
Update a room’s metadata. Use this method to add up to 2,000 key/value pairs to the room’s data store. | Update a Room’s Metadata |
Get information about a room such as the users associated with the room, the max number of users or the room join policy. | Retrieve Information About a Room |
Delete a moderated room | Delete a Moderated Room |
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.
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.
Task Description | Function |
---|---|
Retrieve information about a room. | ovr_Room_Get() |
Retrieve information about the current room. | ovr_Room_GetCurrent() |
Get information about a room that contains a specified user. | ovr_Room_GetCurrentForUser() |
Join a specified room. | ovr_Room_Join2() |
Leave a specified room. | ovr_Room_Leave() |
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.
To build your own UI for room invites, make sure your integration does the following:
Make sure the user has joined the room for which they are sending invites. You can call GetCurrentRoomInformation
to confirm.
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:
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 Developer DashboardPlatform Services > 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.
Then invite the user to the Room passing the room ID and the invite token retrieved with GetInvitableUsers2
:
ovr_Room_InviteUser(roomID, inviteToken)
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.
To use the Oculus UI for room invites, follow these steps:
ovr_Room_GetCurrent()
to confirm.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 Developer DashboardPlatform > Matchmaking page. If you don’t want to include recently met users, you may use that page to opt out.
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:
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 }
There are two ways to receive updates for rooms.
ovr_Notification_GetRoomInvites()
for native apps, or Notifications.GetRoomInviteNotifications()
for Unity apps. This method requires you to frequently check for invites and room updates.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.
Following are the basic steps add private user-owned rooms to your app.
ovr_Room_CreateAndJoinPrivate2()
on behalf of a user to create and add them to a room. This user becomes the owner of the room. 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.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.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.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.ovr_Room_Get()
with the roomId
of the room. The response will be a Room message that contains the details about the room.ovr_Room_Join2()
with the roomId
of the room.ovr_Room_Leave()
to leave the room.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. It is available in the Developer Dashboard, under an app’s Platform Services > Matchmaking and then select the Debugger tab. 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: