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 you users to create rooms themselves, use the room invites methods to help users to find their friends and add them to the rooms.

Creating 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}

Integrating Rooms

Rooms integration varies depending on which kinds of rooms you are integrating into your game. We’ll review the integration for both user-generated and moderated rooms in this section.

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.

Creating and Moderating Private User 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, the role of Room Owner will be transferred to the person who has been in the room the longest.

• 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 2k 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()

  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()

  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.

Interacting with Rooms

This section details 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

Invites allow your users to initiate a shared experience by asking other users to join them in a social VR experience. You can use room invites when the inviting user is in a User Generated Room or a Moderated Room. Only private User-Generated and Moderated Rooms support Invites, Matchmaking rooms do not support room invites.

Room invites can be received whether the invited person is currently in VR or not. However, people can only be invited to apps or content they’re entitled to, either because they own it, or because they’re a developer of the content.

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. 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 and changes to the room, please see Requests and Messages for information about how the queue works.