SharedSpaces was built by the VR Developer Tools team to demonstrate how you can quickly get people together in VR using the Oculus Social Platform APIs. This version was built for the Unity engine using Photon Realtime as the transport layer and Unity Netcode for GameObjects. Other versions are available, in particular one built for the Unreal Engine.
This codebase is available both as a reference and as a template for multiplayer VR games. The Oculus License applies to the SDK and supporting material. The MIT License applies to only certain, clearly marked documents. If an individual file does not indicate which license it is subject to, then the Oculus License applies.
See the CONTRIBUTING file for how to help out.
First, ensure you have Git LFS installed by running this command:
git lfs installThen, clone this repo using the "Code" button above, or this command:
git clone https://github.com/oculus-samples/Unity-SharedSpaces.gitTo run the showcase, open the project folder in Unity 2021.3.26f1 or newer. Load the Assets/SharedSpaces/Scenes/Startup scene.
After loading the scene, you may encounter this pop-up:
Click "Import TMP Essentials" to import the necessary TextMesh Pro assets.
To get the sample working, you will need to configure the NetDriver with your own Photon account. Their base plan is free.
- Visit photonengine.com and create an account
- From your Photon dashboard, click “Create A New App”
- Fill out the form making sure to set type to “Photon Realtime”. Then click Create.
Your new app will now show on your Photon dashboard. Click the App ID to reveal the full string and copy the value.
Paste your App ID in Assets/Photon/Resources/PhotonAppSettings.
The Photon Realtime transport should now work. You can check the dashboard in your Photon account to verify there is network traffic.
In order to keep the project organized, the Oculus Integration and Photon Voice 2 packages are stored in the Packages folder. To update them, import their updated Asset Store packages, then copy them into their respective Packages folders.
The Oculus Integration package is released under the Oculus SDK License Agreement.
The Photon Voice 2 package is released under the License Agreement for Exit Games Photon.
Also, the Photon Realtime package is referenced in Packages/manifest.json as com.mlapi.contrib.transport.photon-realtime.
|
A. Overview of SharedSpaces B. SharedSpaces in Action C. Oculus Application Configuration 1. Application Identifier 2. Destinations |
| Oculus | Group presence with destination, lobby and match ids. |
| Photon Realtime | Transport via a room named after the lobby or match id. |
| Netcode for GameObjects | Replication between room members with the master client as host. |
SharedSpaces networking is divided into three layers. The Oculus layer provides presence information needed to find and connect with friends. The Photon layer provides the transport layer for sending messages to other players. And the Netcode for GameObjects layer handles the replication of game objects.
In this overview we will explore each of these layers and show how we connected them together to make a simple multiplayer application which allows people to connect and play together, without the need for a dedicated server.
SharedSpaces is made of a few connected levels, known as destinations. In the center is your personal lobby with doors leading to the surrounding matches. The matches on the left are private and are reachable from your own lobby only. The match on the right is public, reachable from any lobby.
We use this layout as a direct representation of the new group presence apis. To get you to a SharedSpaces destination, we first set your destination and a pair of session identifiers in your group presence: one for your lobby session id, which should not change very often, and one for your match session id, only set when you join a match.
The destinations are specific areas of your application that are defined on the Oculus dashboard under Platform Services > Destinations. The lobby session id represents a tight group of people that want to stay together between games and possibly play as part of the same team during matches. The match session id is shared by people currently playing a match together, whether they are on the same team or not.
When you first launch SharedSpaces, you start in your own private lobby for which we create a unique id. To form a group to be with before and after matches, you invite people to share your lobby. If they accept the invitation, their lobby session id will be updated to be the same as yours, and whenever you will be in the lobby at the same time, you will be together in the same space.
You can think of the lobby as the base camp for your group. Different groups always go back to their respective lobbies after matches.
Members of your group are free to travel at any time between your lobby and their private matches. This only affects the match session ids of their group presence.
You can also grant access to your private match to anyone. You invite them from that match, and they join you when they accept the invitation. In SharedSpaces, accepting an invitation to a match only affects your match session id, not your lobby session id.
As a consequence, when they leave the match through the lobby door, users effectively go back to their separate lobbies if they are not members of the same group.
SharedSpaces also has the purple room to represent a public match that is reachable from all lobbies. Again, anybody is free to go from their lobby to the purple room at any time, and it only affects their match session id. It is a space where you can meet people from outside your group without a prior invitation.
To connect users, Photon has the concept of room. People in the same match or lobby instance will be in the same Photon room in order for data to flow between them. The transport layer is responsible for routing packets between your users who are most likely behind network firewalls.
Photon rooms have unique names. The name of the room that we will use comes directly from the social layer: we either use your match session id, if you have one, or your lobby session id, otherwise.
A key feature of the Photon room system is that it keeps track of the oldest member in the room, called the “master client”, here identified with stars.
Let’s look at Alice, Bob and Charlie entering the Purple room. Charlie is first to join, so the room is created for him and he is marked as its master client. Alice and Bob join shortly after and they are added as normal clients.
If Charlie, as the master client, leaves the room, a new master client is selected and all remaining clients are notified of that change. This is a key feature for the next networking layer.
You can find extensive documentation on Netcode for GameObjects on the Unity Documentation site.
For some applications, like SharedSpaces, we can host the server on one of the headsets as a listen-server. In that mode, the game acts both as a server and as its first connected client. It will accept connections from the other players.
So for each room, we need to select one of the users to be the listen-server. This decision comes from the transport layer: the master client of the corresponding Photon room will be our host.
When the player hosting leaves, we perform a host migration. Here we can see that Alice is leaving the purple room. Photon picks Bob as the new master client. The remaining members of the room are notified and they reestablish their Unity connections.
We end up with two Photon rooms, the Purple room is now hosted by Bob, with Charlie and Donna connected to him. Alice just left the room through the door to her lobby, but since she is the only one there, she becomes both the master client and host of her group lobby.
Let’s have a look at SharedSpaces in action.
When Alice starts SharedSpaces, she starts alone in her private lobby. She is the master client and host of the lobby, as indicated by the star next to her name.
Alice wants Bob to form a group with her so that they can be together between matches. To do that, she steps on the invite panel switch and she sends him an invitation from her lobby. By accepting, SharedSpaces starts on Bob’s headset with a deeplink message that will let him join Alice in game. From now on, Bob will have the same lobby session id as Alice and they will share the same lobby.
Bob goes through the blue door to start a private match, followed by Alice. They end up in the same Blue Room and they now have the same match session id that corresponds to their private room. Since Bob was there first, he is the one hosting the room and Alice is connected to him.
Alice decides to invite her friend Charlie to join their match, and he happens to be in his own lobby when he accepts the invitation. Charlie has his match session id updated with the private match id, but on the other hand he still retains his own lobby session id. He is still part of a different group.
When Bob leaves the blue room, Photon notifies Alice and Charlie that the master client has changed. A host migration is needed: Alice opens a new listen-server, since she is the new master client of the blue room, and Charlie connects to her.
As for Bob, he started hosting his group lobby.
Now when Charlie leaves the blue room, he does not join Bob. They are not part of the same group since they do have different lobby session ids. Instead, he goes back to his own separate lobby. This can be checked by stepping on the roster panel switch and you will see your different groups explicitly listed.
In the case of Alice, therefore, going back to lobby means that she will rejoin Bob who is waiting for her.
To have Charlie join their group, Alice or Bob simply need to send him an invitation from their lobby. Again, by accepting an invitation to lobby, you also accept to join a group. Charlie’s lobby session id is updated and the three of them will now share the same lobby between matches.
To build and run your own copy of SharedSpaces, you will need to create an application for it on the Oculus developer dashboard.
You Oculus application identfier must be placed in Assets/Resources/OculusPlatformSettings.asset.
The identifier (App ID) can be found in the API section.
2. Destinations
You need to recreate the SharedSpaces destinations in your own application. Destinations can be found under Platform Services.
You need to recreate the SharedSpaces destinations in your own application. Destinations can be found under Platform Services.
SharedSpaces has five destinations: a Lobby, three private rooms (the red, green and blue rooms), and one public room (the purple room). Here are the settings for each of them.
| API Name | Deeplink Message | Display Name | Description |
|---|---|---|---|
| Lobby | {"is_lobby":"true","map":"Lobby"} | Lobby | The Lobby |
| RedRoom | {"map":"RedRoom"} | Red Room | The Red Room |
| GreenRoom | {"map":"GreenRoom"} | Green Room | The Green Room |
| BlueRoom | {"map":"BlueRoom"} | Blue Room | The Blue Room |
| PurpleRoom | {"map":"PurpleRoom","public_room_name":"ThePurpleRoom"} | Purple Room | The Purple room |
In addition to these settings, you need to set Deeplink Type to Enabled and add an image for your destination. In the case of SharedSpaces, the destination is Audience is set to Everyone. Also make sure to set the max group launch capacity for each destination so that the group launch feature can be used.
You will need to request access to platform data needed by SharedSpaces. Under Data Use Checkup, add the following items and submit for certification.
- User ID
- User Profile
- Deep Linking
- Friends
- Invites
We implemented the User reporting that is required for all multiplayer applications. We used the unhandled solution that uses the default system, opposite to devs that have their own reporting flow.
The implementation can be found in SharedSpacesApplication.cs.
Here is how to set it up in the dashboard: Setup User reporting Settings