In the Discover GitHub repo, the ColocationDriverNetObj class provides the backbone of the colocation flow. It is defined in /Assets/Discover/Scripts/Colocation/ColocationDriverNetObj.cs.
Discover uses the Colocation package (com.meta.xr.colocation). Discover’s Packages/manifest.json installs this package from the colocation-package folder of the Unity-LocalMultiplayerMR repo at commit 075b8f0e1641bc6cacef05a57f25e82b985cb4bb. Paths on this page that start with colocation-package/ refer to that repo. The snippets on this page match the main branch of Discover and that package commit.
The following dissects the key aspects of this flow.
Start the flow
The async Init() function represents how the flow starts. Photon Fusion calls Spawned() on the network object, which calls Init().
This function is common to both client players and the host player. It finds the camera rig, gets the logged-in user, and stores the player ID that OculusPlatformUtils.GetUserDeviceGeneratedUid() returns. It then invokes the SetupForColocation() member function of the same class.
private void SetupForColocation()
{
Debug.Log("SetUpAndStartColocation: Initialize messenger");
m_networkMessenger.RegisterLocalPlayer(m_playerDeviceUid);
// Instantiates the manager for the Oculus shared anchors, specifying the desired anchor prefab.
Debug.Log("SetupForColocation: Instantiating shared anchor manager");
m_sharedAnchorManager = new SharedAnchorManager { AnchorPrefab = m_anchorPrefab };
NetworkAdapter.SetConfig(m_networkData, m_networkMessenger);
Debug.Log("SetupForColocation: Initializing Colocation for the player");
// Starts the colocation alignment process
m_colocationLauncher = new AutomaticColocationLauncher();
m_colocationLauncher.Init(
NetworkAdapter.NetworkData,
NetworkAdapter.NetworkMessenger,
m_sharedAnchorManager,
m_ovrCameraRigTransform.gameObject,
m_playerDeviceUid,
m_oculusUser?.ID ?? default
);
// Hooks the event to react to the colocation ready state
m_colocationLauncher.ColocationReady += OnColocationReady;
m_colocationLauncher.ColocationFailed += OnColocationFailed;
if (HasStateAuthority)
{
m_colocationLauncher.CreateColocatedSpace();
}
else
{
// Don't try to colocate if we join remotely
if (SkipColocation)
{
OnColocationCompletedCallback?.Invoke(false);
}
else
{
m_colocationLauncher.ColocateAutomatically();
}
}
}
SetupForColocation() does the following:
It registers the local player ID with the PhotonNetworkMessenger component.
It creates a SharedAnchorManager that uses the anchor prefab set on the component.
It passes the PhotonNetworkData and PhotonNetworkMessenger components to NetworkAdapter.SetConfig().
It creates an AutomaticColocationLauncher, initializes it, and subscribes to its ColocationReady and ColocationFailed events.
The host (checked with HasStateAuthority) calls CreateColocatedSpace(). Other players call ColocateAutomatically(), unless they joined remotely and SkipColocation is set.
Network interfaces
The Colocation package does not depend on a specific networking library. Discover implements two package interfaces with Photon Fusion.
The INetworkMessenger interface is defined in colocation-package/Runtime/INetworkMessenger.cs. This interface is how players ask each other to share an anchor and report the result.
namespace com.meta.xr.colocation
{
/// <summary>
/// An interface used to send RPC calls used for a player to join someone else's colocated space
/// </summary>
public interface INetworkMessenger
{
event Action<ShareAndLocalizeParams> AnchorShareRequestReceived;
event Action<ShareAndLocalizeParams> AnchorShareRequestCompleted;
public void SendAnchorShareRequest(ulong targetPlayerId, ShareAndLocalizeParams shareAndLocalizeParams);
public void SendAnchorShareCompleted(ulong targetPlayerId, ShareAndLocalizeParams shareAndLocalizeParams);
}
}
The INetworkData interface is defined in colocation-package/Runtime/INetworkData.cs. It stores the players and anchors that every player can read through the networking system.
namespace com.meta.xr.colocation
{
/// <summary>
/// An interface that is used to keep track of all players and anchors and can be accessed by any player
/// </summary>
public interface INetworkData
{
public void AddPlayer(Player player);
public void RemovePlayer(Player player);
public Player? GetPlayerWithPlayerId(ulong playerId);
public Player? GetPlayerWithOculusId(ulong oculusId);
public List<Player> GetAllPlayers();
public void AddAnchor(Anchor anchor);
public void RemoveAnchor(Anchor anchor);
public Anchor? GetAnchor(ulong ownerOculusId);
public List<Anchor> GetAllAnchors();
public uint GetColocationGroupCount();
public void IncrementColocationGroupCount();
}
}
Photon Fusion RPCs in PhotonNetworkMessenger
The PhotonNetworkMessenger class is defined in /Assets/Discover/Scripts/Colocation/PhotonNetworkMessenger.cs. It implements INetworkMessenger with Photon Fusion RPCs.
RegisterLocalPlayer() sends the local player ID and the Photon Fusion player ID to the host. The host stores both IDs in networked lists:
public void RegisterLocalPlayer(ulong localPlayerId)
{
Logger.Log($"{nameof(PhotonNetworkMessenger)}: RegisterLocalPlayer: localPlayerId {localPlayerId}",
LogLevel.Verbose);
Logger.Log($"{nameof(PhotonNetworkMessenger)} RegisterLocalPlayer: fusionId {Runner.LocalPlayer.PlayerId}",
LogLevel.Verbose);
AddPlayerIdHostRPC(localPlayerId, Runner.LocalPlayer.PlayerId);
}
[Rpc(RpcSources.All, RpcTargets.StateAuthority)]
private void AddPlayerIdHostRPC(ulong localPlayerId, int localNetworkId)
{
Logger.Log("Add Player Id Host RPC: player id", LogLevel.Verbose);
PlayerIds.Add(localPlayerId);
Logger.Log("Add Player Id Host RPC: network id", LogLevel.Verbose);
NetworkIds.Add(localNetworkId);
PrintIDDictionary();
}
When the colocation package sends a message to a player, the messenger looks up that player’s Photon Fusion ID and calls an RPC on the host:
private bool TryGetNetworkId(ulong playerId, out int networkId)
{
for (var i = 0; i < PlayerIds.Count; i++)
{
if (playerId == PlayerIds[i])
{
networkId = NetworkIds[i];
return true;
}
}
networkId = 0;
Logger.Log($"PhotonNetworkMessenger: playerId {playerId} got invalid networkId {networkId}", LogLevel.Error);
return false;
}
public void SendAnchorShareRequest(ulong targetPlayerId, ShareAndLocalizeParams shareAndLocalizeParams)
{
Logger.Log(
$"{nameof(PhotonNetworkMessenger)}: Sending anchor share request to player {targetPlayerId}. (anchorID {shareAndLocalizeParams.anchorUUID})",
LogLevel.Verbose);
var fusionData = new PhotonShareAndLocalizeParams(shareAndLocalizeParams);
SendMessageToPlayer(MessageEvent.ANCHOR_SHARE_REQUEST, targetPlayerId, fusionData);
}
public void SendAnchorShareCompleted(ulong targetPlayerId, ShareAndLocalizeParams shareAndLocalizeParams)
{
Logger.Log(
$"{nameof(PhotonNetworkMessenger)}: Sending anchor share completed to player {targetPlayerId}. (anchorID {shareAndLocalizeParams.anchorUUID})",
LogLevel.Verbose);
var fusionData = new PhotonShareAndLocalizeParams(shareAndLocalizeParams);
SendMessageToPlayer(MessageEvent.ANCHOR_SHARE_COMPLETE, targetPlayerId, fusionData);
}
private void SendMessageToPlayer(MessageEvent eventCode, ulong playerId,
PhotonShareAndLocalizeParams fusionData)
{
Logger.Log($"Calling SendMessageToPlayer with MessageEvent: {eventCode}, to playerId {playerId}",
LogLevel.Verbose);
if (TryGetNetworkId(playerId, out var fusionId))
{
Logger.Log($"Calling FindRPCToCallServerRPC playerId {playerId} maps to fusionId {fusionId}",
LogLevel.Verbose);
FindRPCToCallServerRPC(eventCode, fusionId, fusionData);
}
else
{
Logger.Log($"Could not find fusionId for playerId {playerId}", LogLevel.Error);
}
}
The host then forwards the message to the target player, and the target player raises the matching INetworkMessenger event:
[Rpc(RpcSources.All, RpcTargets.StateAuthority)]
private void FindRPCToCallServerRPC(MessageEvent eventCode, int fusionId,
PhotonShareAndLocalizeParams fusionData, RpcInfo info = default)
{
Logger.Log("FindRPCToCallServerRPC called", LogLevel.Verbose);
PlayerRef fusionPlayerRef = fusionId;
Logger.Log("Created PlayerRef right before calling HandleMessageClientRPC", LogLevel.Verbose);
HandleMessageClientRPC(fusionPlayerRef, eventCode, fusionData);
}
[Rpc(RpcSources.All, RpcTargets.All)]
private void HandleMessageClientRPC([RpcTarget] PlayerRef playerRef, MessageEvent eventCode,
PhotonShareAndLocalizeParams fusionData)
{
Logger.Log($"HandleMessageClientRPC: {eventCode}", LogLevel.Verbose);
switch (eventCode)
{
case MessageEvent.ANCHOR_SHARE_REQUEST:
AnchorShareRequestReceived?.Invoke(fusionData.GetShareAndLocalizeParams());
break;
case MessageEvent.ANCHOR_SHARE_COMPLETE:
AnchorShareRequestCompleted?.Invoke(fusionData.GetShareAndLocalizeParams());
break;
default:
throw new ArgumentOutOfRangeException(nameof(eventCode), eventCode, null);
}
}
AutomaticColocationLauncher class
The AutomaticColocationLauncher class is defined in colocation-package/Runtime/AutomaticColocationLauncher.cs. Init() stores the network interfaces, the shared anchor manager, the camera rig, and the player IDs. It also subscribes to the two INetworkMessenger events.
The host calls CreateColocatedSpace(), which calls CreateNewColocatedSpace(). This function creates an alignment anchor, saves it to the cloud, adds the anchor and the player to the network data, and aligns the player to the anchor:
Other players call ColocateAutomatically(), which calls ColocateAutomaticallyInternal(). This is where shared spatial anchors come into play:
private async void ColocateAutomaticallyInternal()
{
Logger.Log($"{nameof(AutomaticColocationLauncher)}: Called Init Anchor Flow", LogLevel.Verbose);
var successfullyAlignedToAnchor = false;
List<Anchor> alignmentAnchors = GetAllAlignmentAnchors();
foreach (var anchor in alignmentAnchors)
{
if (await ShareAndLocalizeAnchor(anchor))
{
successfullyAlignedToAnchor = true;
Logger.Log(
$"{nameof(AutomaticColocationLauncher)}: successfully aligned to anchor with id: {anchor.automaticAnchorUuid}",
LogLevel.Info);
_networkData.AddPlayer(new Player(_myPlayerId, _myOculusId, anchor.colocationGroupId));
AlignPlayerToAnchor();
ColocationReady?.Invoke();
break;
}
}
if (!successfullyAlignedToAnchor)
{
CreateNewColocatedSpace();
}
}
This gets all the alignment anchors by calling GetAllAlignmentAnchors(), which reads the anchor list from INetworkData:
private List<Anchor> GetAllAlignmentAnchors()
{
var alignmentAnchors = new List<Anchor>();
List<Anchor> allAnchors = _networkData.GetAllAnchors();
foreach (var anchor in allAnchors)
{
if (anchor.isAlignmentAnchor)
{
alignmentAnchors.Add(anchor);
}
}
return alignmentAnchors;
}
In Discover, GetAllAnchors() is defined in /Assets/Discover/Scripts/Colocation/PhotonNetworkData.cs as part of the PhotonNetworkData class. It reads the networked AnchorList, which AddAnchor() fills:
public void AddAnchor(Anchor anchor)
{
AnchorList.Add(new PhotonNetAnchor(anchor));
}
public List<Anchor> GetAllAnchors()
{
var anchors = new List<Anchor>();
foreach (var photonAnchor in AnchorList)
{
anchors.Add(photonAnchor.GetAnchor());
}
return anchors;
}
Share and localize an anchor
For each alignment anchor, ShareAndLocalizeAnchor() asks the anchor’s owner to share it:
The call to OVRSpatialAnchor.LoadUnboundAnchors() loads the spatial anchors given by this list of IDs:
Uuids = anchorIds
The anchor owner shares these anchors with the requesting player, and that player retrieves them by ID.
AlignCameraToAnchor class
The Colocation package uses the first shared spatial anchor to align the player. This assumes that the anchor is visible to both players (host and client).
AlignPlayerToAnchor() adds an AlignCameraToAnchor component to the camera rig. This class is defined in colocation-package/Runtime/AlignCameraToAnchor.cs:
public OVRSpatialAnchor CameraAlignmentAnchor { get; set; }
private void Update()
{
Align(CameraAlignmentAnchor);
}
public void RealignToAnchor()
{
Align(CameraAlignmentAnchor);
}
private void Align(OVRSpatialAnchor anchor)
{
// Align the scene by transforming the camera.
// The inverse anchor pose is used to move the camera so that the scene appears as if it was parented to the anchor.
// Get the anchor's raw tracking space pose to align the camera.
// Note that the anchor's world space pose is dependent on the camera position, in order to maintain consistent world-locked rendering.
OVRPose trackingSpacePose;
if (!TryGetPose(anchor, out trackingSpacePose))
{
this.enabled = false;
return;
}
// Position the anchor in tracking space
Transform anchorTransform = anchor.transform;
anchorTransform.SetPositionAndRotation(trackingSpacePose.position, trackingSpacePose.orientation);
// Transform the camera to the inverse of the anchor pose to align the scene
transform.position = anchorTransform.InverseTransformPoint(Vector3.zero);
transform.eulerAngles = new Vector3(0, -anchorTransform.eulerAngles.y, 0);
// Update the world space position of the anchor so it renders in a consistent world-locked position.
OVRPose worldSpacePose = trackingSpacePose.ToWorldSpacePose(Camera.main);
anchorTransform.SetPositionAndRotation(worldSpacePose.position, worldSpacePose.orientation);
}
This moves the camera rig so that the player is positioned relative to the shared spatial anchor, the same way for every player who uses that anchor.
AlignCameraToAnchor realigns on every frame. When colocation is ready, Discover disables it and adds its own AlignCameraToAnchorManager component, which realigns only when the player recenters or puts on the headset:
private void OnColocationReady()
{
Debug.Log("Colocation is Ready!");
// The AlignCameraToAnchor scripts updates on every frame which messes up Physics and create frame spikes.
// We need to disable it and add our own align manager that is applied only on recenter
var alignCamBehaviour = FindFirstObjectByType<AlignCameraToAnchor>();
if (alignCamBehaviour != null)
{
alignCamBehaviour.enabled = false;
var alignmentGameObject = alignCamBehaviour.gameObject;
var alignManager = alignmentGameObject.AddComponent<AlignCameraToAnchorManager>();
alignManager.CameraAlignmentBehaviour = alignCamBehaviour;
alignManager.RealignToAnchor();
}
OnColocationCompletedCallback?.Invoke(true);
}