Rooms

Once together in a room, users can navigate your VR application together, chat, and even launch a Matchmaking session from certain types of rooms (chat and Matchmaking will require separate integrations with Voice Chat (VoIP) and Matchmaking).

Once you’ve created the rooms, or allowed your users to create rooms themselves, use the room invites methods to help users to find their friends and add them to the rooms.

Integrating Rooms

The process to integrate rooms is different depending on what kind of experience you want your users to have. We’ll review the integration for both user-created private rooms and system-owned moderated rooms in this section, information about integrating user-created matchmaking rooms can be found in the Matchmaking guide. Then we'll introduce the methods you can call to interact with all rooms.

When integrating rooms, be sure to familiarize yourself with how Requests and Messages work in the Platform SDK. Notifications are a central component of the Rooms feature.

Integrate User-Created Private Rooms

This section details the methods that are available when creating and updating private user-generated rooms.

Some methods listed below can only be called by the Room Owner. The owner is the user who created the room. If the user who created the room leaves, ownership of the room will be transferred to the person who has been in the room the longest. Room ownership can also be transferred by calling ovr_Room_UpdateOwner().

• Create a Private User-Generated Room:

  Native - ovr_Room_CreateAndJoinPrivate2()

  Unity - Platform.Room.CreateAndJoinPrivate2()

  Rooms created with this method can not be promoted to a matchmaking room. If you want to allow users to enqueue the room as a matchmaking room, you should use the ovr_Matchmaking_CreateRoom2 method. Please see Matchmaking for more information about creating matchmaking rooms.

  Review the ovr_Room_CreateAndJoinPrivate2 page for information about the parameters and return data structure.

• Kick a User out of a Room:

  Native - ovr_Room_KickUser()

  Unity - Platform.Room.KickUser()

  This method can only be called by the room owner. Review the ovr_Room_KickUser page for information about the parameters and return data structure.

• Update Room Metadata:

  Native - ovr_Room_UpdateDataStore()

  Unity - Platform.Room.UpdateDataStore()

  This method can only be called by the room owner. Add up to 2,000 key/value pairs to the room metadata. Review the ovr_Room_UpdateDataStore page for information about the parameters and return data structure.

• Update Room Join Policy:

  Native - ovr_Room_UpdatePrivateRoomJoinPolicy()

  Unity - Platform.Room.UpdatePrivateRoomJoinPolicy()

  Update the room join policy, or the definition of who can join the room. This method can only be called by the room owner. Review the ovr_Room_UpdatePrivateRoomJoinPolicy page for information about the parameters and return data structure.

• Update Room Membership Lock Status:

  Native - ovr_Room_UpdateMembershipLockStatus()

  Unity - Platform.Room.UpdateMembershipLockStatus()

  Call this method to lock the membership of the room, calling this and setting to true will prevent additional users from joining the room. This method can only be called by the room owner. Review the ovr_Room_UpdateMembershipLockStatus page for information about the parameters and return data structure.

• Update Room Owner:

  Native - ovr_Room_UpdateOwner()

  Unity - Platform.Room.UpdateOwner()

  This method can only be called by the room owner. Review the ovr_Room_UpdateOwner page for information about the parameters and return data structure.

• Update Room Description:`

  Native - ovr_Room_SetDescription()

  Unity - Platform.Room.SetDescription()

  This method can only be called by the room owner. Review the ovr_Room_SetDescription page for information about the parameters and return data structure.

Integrate User-Created Matchmaking Rooms

Information about how to configure the matchmaking service and integrate user-created matchmaking rooms can be found in the Matchmaking guide.

Integrate Moderated Rooms

Moderated rooms are created through S2S REST calls. The client app should not have any interaction with creating or maintaining the moderated room. Please review the Server-to-Server API Basics for information about making S2S API calls, specifically about using the access tokens.

With moderated rooms, only your trusted servers can create or make changes to the rooms.

Create a Moderated Room

Calling this endpoint will create a new moderated room.

$ curl -d "access_token=$APP_ACCESSTOKEN"  -d "max_users=MY_MAX_USER_COUNT" 
        https://graph.oculus.com/room_moderated_create

You’ll need to include the max_users parameter which identifies the max simultaneous users for the room.

Example response:

{"id": 963119010431337}

In response the API will return the moderated_room_id as the id value. Call this Id when adding users to the room.

Delete a Moderated Room

Calling this endpoint will delete a moderated room.

$ curl  -X DELETE -d "access_token=$APP_ACCESSTOKEN" 
        https://graph.oculus.com/$MODERATED_ROOM_ID

Example response:

{"success": true}

Interacting with Rooms

This section describes the methods can be called to get information and interact with all types of rooms.

• Retrieve Information About a Room:

  Native - ovr_Room_Get()

  Unity - Platform.Room.Get()

  Review the ovr_Room_Get page for information about the parameters and return data structure.

• Get Current Room Information:

  Native - ovr_Room_GetCurrent()

  Unity - Platform.Room.GetCurrent()

  Review the ovr_Room_GetCurrent page for information about the parameters and return data structure.

• Get Current Room Information for Another User:

  Native - ovr_Room_GetCurrentForUser()

  Unity - Platform.Room.GetCurrentForUser()

  Review the ovr_Room_GetCurrentForUser page for information about the parameters and return data structure.

• Join a Room:

  Native - ovr_Room_Join2()

  Unity - Platform.Room.Join2()

  Review the ovr_Room_Join2 page for information about the parameters and return data structure.

• Leave a Room:

  Native - ovr_Room_Leave()

  Unity - Platform.Room.Leave()

  Review the ovr_Room_Leave page for information about the parameters and return data structure.

Integrating Invites

Rooms invites allow users to invite others to join them in a social VR experience. Room invites can be received whether the invited person is currently in VR or not. However, users can only be invited to apps they’re entitled to.

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

Use a Custom UI

1. Make sure the user has joined the room for which he or she is sending invites. You can call ‘Get Current Room Information’ to confirm.
2. Get a list of users that can be invited to that room. Call:

   Native - ovr_Room_GetInvitableUsers2()

   Unity - Platform.Room.GetInvitableUsers2()

   You’ll get information for each inviteable person (friends of the user who also own your app) that includes the Oculus username and a user-specific invite token.

   Review the ovr_Room_GetInvitableUsers2 page for information about the parameters and return data structure.

3. Then call to invite the selected user to the Room:

   Native - ovr_Room_InviteUser()

   Unity - Platform.Room.InviteUser()

   Review the ovr_Room_InviteUser page for information about the parameters and return data structure.

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

Use the Oculus UI

1. Make sure the user has joined the room for which he or she is sending invites. You can call ‘Get Current Room Information’ to confirm.
2. To open the Oculus UI, temporarily background your app and call:

   Native - ovr_Room_LaunchInvitableUserFlow()

   Unity - Platform.Room.LaunchInvitableUserFlow()

   Review the ovr_Room_LaunchInvitableUserFlow page for information about the parameters and return data structure.

3. 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.

Accepting an Invite and Joining a Room from 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. The Oculus will provide the invite notification to the user for both Rift and Gear VR Home.
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
     }

   • For a Unity app, use the following callback:

     Oculus.Platform.Rooms.SetRoomInviteNotificationCallback (
         (Oculus.Platform.Message<string> msg) =>{
             if (msg.IsError) {
                 // Handle error  
             } else {
                 string roomID = msg.GetString();
                 // we can now try to join the room
             }
         }
     );

Room Updates

Rooms relies on notifications and the message queue for updates to the room and invite notifications , please see Requests and Messages for information about how the queue works.

Rooms Quickstart

Now that we've reviewed the different types of rooms you can create and how you're able to interact with them, let's review a very basic rooms integration that supports invites.

This integration will allow users to create a private room, not used for matchmaking, for a social VR experience.

1. Create the Room: A user calls ovr_Room_CreateAndJoinPrivate2() to create and join a private user-created 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. maxUsers is the maximum number of users that can be added to a room.
   2. Once created, the room owner has the ability to lock the membership of the room 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 room that was just created. The invite interface will be opened where the user may find and invite users to the room.
3. Join the Room: Recipients of invites will receive a notification on the message queue that they have been invited to join a room.
   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 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 user may call ovr_Room_Leave() to leave the room.