This version of the guide is out of date. Click here for the latest version.
Rooms are a VR feature that allows users to gather and interact in your app.
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.
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}
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.
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
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.
Native - ovr_Room_InviteUser()
Unity - Platform.Room.InviteUser()
Review the ovr_Room_InviteUser page for information about the parameters and return data structure.
Use the Oculus UI
Native - ovr_Room_LaunchInvitableUserFlow()
Unity - Platform.Room.LaunchInvitableUserFlow()
Review the ovr_Room_LaunchInvitableUserFlow page for information about the parameters and return data structure.
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:
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 }
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.