Develop
Develop
Select your platform

Shared Activities in Mixed Reality Motif

Updated: Oct 1, 2025
Shared Activities Thumbnail⁠
Create convincing shared activities in MR that encourage authentic, intuitive interactions with the Shared Activities in Mixed Reality motif. This project uses the Multiplayer Building Blocks to quickly and effortlessly set up a networked experience using the Networked Meta Avatars. This motif shows developers how to easily extend Building Blocks and build custom shared experiences, like chess and movie co-watching, on top of them.

Requirements

Below is a complete list of requirements for this project.

Requirements List

PackageVersion
Unity-MRMotifs samples on GitHub⁠
Latest
Unity 6⁠
Unity 6 or later
URP or BiRP
Recommended: URP
OpenXR Plugin - com.unity.xr.openxr
1.15.0
Meta XR Core SDK⁠ - com.meta.xr.sdk.core
78.0.0
Meta XR Interaction SDK⁠ - com.meta.xr.sdk.interaction.ovr
78.0.0
Meta XR Interaction SDK Essentials⁠ - com.meta.xr.sdk.interaction
78.0.0
Meta Avatars SDK⁠ - com.meta.xr.sdk.avatars
38.0.1
Meta Avatars SDK Sample Assets⁠ - com.meta.xr.sdk.avatars.sample.assets
38.0.1
Meta XR Platform SDK⁠ - com.meta.xr.sdk.platform
78.0.0
Meta XR Simulator⁠ - com.meta.xr.simulator
78.0.0
Photon Fusion⁠
2.0.6
Photon Voice⁠
2.59
Import Photon Voice Setup Guide⁠
Required
ParrelSync⁠
1.5.2 (Optional)

The concept of Shared Activities in MR

The animation below illustrates the Shared Activities MR Motif. In MR, each user wants to place their own local board or screen without causing misalignment for others. Instead of moving the anchor (e.g., a chessboard), the solution is to adjust remote avatars’ position and rotation. This allows each player to position the board as needed while keeping others correctly aligned.
Shared Activities Visualization
For example, if Client B is one meter behind the board, facing 45 degrees away, Client A can move their board freely while still seeing Client B in the correct relative position and rotation.

Shared Activities sample scenes

Chess

The Chess scene updates chess piece positions and rotations, similar to what the AvatarMovementHandlerMotif does. The ChessBoardHandlerMotif assigns State Authority to the player moving a piece and updates networked positions and rotations relative to the board. It switches the chess pieces' Rigidbody to physics for the State Authority and kinematic for others, ensuring all clients sync with the State Authority.

The Movie Cowatching scene contains the MovieControlsHandlerMotif which differs from the previous Chess sample by synchronizing UI elements instead of transforms, such as button and toggle states. It uses Networked Properties like NetworkBools and NetworkedFloats to track slider values and toggle states.
Movie Cowatching
Notably, both samples integrate Photon Fusion’s IStateAuthorityChanged interface, allowing the system to wait for State Authority transfer before a player interacts with a component.

Multiplayer setup & achieving successful entitlement checks

To build a multiplayer experience with Meta XR SDKs, there are really just a couple of steps to keep in mind. Make sure to go through each step.
1. After installing all requirements from above, set up a multiplayer scene with the following Building Blocks:

Core Building Blocks Overview

  • [BuildingBlock] Camera Rig: On the Camera Rig feel free to add any additional Building Blocks such as grab and ray interaction or hands and controller tracking. Or simply use the OVRCameraRig prefab located at Assets/MRMotifs/Shared Assets/Prefabs.
  • [BuildingBlock] Passthrough: Make sure the CenterEyeAnchor's Background Type is set to Solid Color and set the Background Color's alpha to 0.
  • [BuildingBlock] Network Manager: Contains the heart of any multiplayer session: Network Runner⁠ and Network Events. The Multiplayer Building Blocks use FusionBBEvents instead of direct Network Events. FusionBBEvents wraps Photon Fusion’s INetworkRunnerCallbacks and exposes them as static events, allowing multiple classes to subscribe without implementing the interface directly. This simplifies event handling, promotes modularity, and keeps network logic separate from other game systems for cleaner code.
  • [BuildingBlock] Platform Init: This component is responsible for initializing the Meta platform, fetching the access token, and checking if the user is entitled to access the platform. This is later necessary to load the avatar, based on the user’s account and if they are entitled.
  • [BuildingBlock] Auto Matchmaking: Here sits the component which is responsible for connecting the player to the right game mode (shared) and room. By default every client will simply be spawned in the same room.
  • [BuildingBlock] Networked Avatar: Responsible for spawning the local and remote Meta Avatars and syncing their movement over the network.
  • [BuildingBlock] Player Name Tag: Responsible for spawning a name tag above the avatar with the user’s name or, if the user is not logged in, a random name.
  • [BuildingBlock] Player Voice Chat: Responsible for setting up the voice chat and creating a speaker for each avatar.

2. A crucial part of a multiplayer setup, using Meta Avatars, is the entitlement check, which enables Meta Platform features like avatars:

Meta Platform Setup Instructions

  1. Create a developer account on the Meta Quest Dashboard⁠, and either create or join a team and create your app (Meta Horizon Store).
  2. Retrieve its App ID by navigating to the Development > API section. Find the ID under “App ID - Used to initialize the Platform SDK”.
  3. Add this App ID to the Unity project through the Unity Editor under Meta → Platform → Edit Settings, under Application ID.
  4. Complete the Data Use Check Up for your app, which can be found under Requirements → Data Use Check Up in the Dashboard. For using the Meta Avatars, fill the usage for User ID, User Profile, and Avatars. Make sure that for all of them Use Avatars under Usage is selected and an arbitrary description, such as Using Meta Avatars in my multiplayer experience, under Description, is written.
  5. To use other platform features such as the Friends Invite feature included in this MR Motif, then additional Data Use Check Ups have to be filled out, such as Deep Linking, Friends, and Invites. Do not forget in this case, to create one or more destinations first. Later, the API name and Deep Link Message are needed to invite friends to the experience.
  6. If everything was filled out correctly, the request should be accepted in a few minutes in most cases.
  7. In the Unity Editor under the platform settings, check the Use Standalone Platform checkbox. Then go back to the Developer Dashboard. Under Development > Test Users, create a new Test User. This helps developers test the app with another account besides their own, which can be helpful for debugging. Make sure to at least fill in the prefixes and the password. Now, in the Unity Editor under Meta > Platform > Edit Settings, under Unity Editor Settings, click on the checkbox for Use Standalone Platform and fill in the Test User credentials, and then log in.
  8. Lastly, upload an APK of the app to a release channel, e.g. the Alpha channel. It is recommended to use the Meta Quest Developer Hub for this. Under App Distribution, select the team and the application to upload the APK to. Make sure everyone testing the app is part of the team or is invited as alpha tester. To be extra sure, the same APK version can also be installed additionally on the devices through the Device Manager in the Meta Quest Developer Hub.

3. After setting up the scene with the Multiplayer Building Blocks, and making sure that the entitlement check passes successfully, everything is ready to build truly shared experiences.
Movie Cowatching in XR Simulator

How to move Avatars and other GameObjects in a Shared Mixed Reality Activity

In Shared Mixed Reality Activities, networking a single object (e.g., a chessboard) can cause misalignment when moved. Instead, each player maintains a local copy of the board and shares their avatar's position relative to it. The State Authority manages networked arrays⁠ of positions and rotations, updated as players move their boards. This ensures all avatars stay correctly aligned by reading from these arrays each frame or as needed.
1. At the core of avatar movement is the AvatarEntity, which manages loading, configuration, and synchronization of Meta Avatars in multiplayer by streaming state data like position and rotation.
The AvatarBehaviourFusion class integrates this with Photon Fusion, networking avatar states across clients to keep remote avatars updated. It is attached to the FusionAvatar prefab, which is spawned into the Fusion scene by the AvatarSpawnerFusion class. This class handles spawning and entitlement checks, ensuring avatars are dynamically loaded and synchronized in real-time.
  1. Retrieve its App ID by navigating to the Development > API section. Find the ID under “App ID - Used to initialize the Platform SDK”.
  2. Add this App ID to the Unity project through the Unity Editor under Meta > Platform > Edit Settings, under Application ID.
  3. Complete the Data Use Check Up for your app, which can be found under Requirements > Data Use Check Up in the Dashboard. For using the Meta Avatars, fill the usage for User ID, User Profile, and Avatars. Make sure that for all of them Use Avatars under Usage is selected and an arbitrary description, such as Using Meta Avatars in my multiplayer experience, under Description, is written.
  4. To use other platform features such as the Friends Invite feature included in this MR Motif, then additional Data Use Check Ups have to be filled out, such as Deep Linking, Friends, and Invites. Do not forget in this case, to create one or more destinations first. Later, the API name and Deep Link Message are needed, in order to invite friends to the experience.
  5. If everything was filled out correctly, the request should be accepted in a few minutes in most cases.
  6. In the Unity Editor under the platform settings, check the Use Standalone Platform check box. Then go back to the Developer Dashboard. Under Development > Test Users, create a new Test User. This helps developers test the app with another account besides their own, which can be helpful for debugging. Make sure to at least fill in the prefixes and the password. Remember or note down the password. Now, in the Unity Editor under Meta > Platform > Edit Settings, under Unity Editor Settings, click on the check box for Use Standalone Platform and fill in the Test User credentials, and then log in.
  7. Lastly, upload an APK of the app to a release channel, e.g. the Alpha channel. It is recommended to use the Meta Quest Developer Hub for this. Under App Distribution, select the team and the application to upload the APK to. Make sure everyone testing the app is part of the team or is invited as alpha tester. To be extra sure, the same APK version can also be installed additionally on the devices through the Device Manager in the Meta Quest Developer Hub.
  • Components That Can’t Be Manipulated:
    • AvatarEntity: Controls the avatar’s head and hands based on the main camera and body tracking via OVR Manager. Since this ensures natural movement, the remote avatar’s head or chest cannot be moved.
    • CenterEyeCamera: The main camera's transform is controlled by the headset and cannot be set at runtime.
    • OVR Camera Rig: Moving this rig affects the local avatar. It is used in AvatarSpawnerHandlerMotif for initial positioning but is left untouched afterward, as direct access to remote players' rigs is not possible, making updates difficult.
  • Components That Can Be Manipulated: The AvatarBehaviourFusion parent object can be moved safely without causing issues. In AvatarMovementHandlerMotif, this acts as the "remote version" of another player's OVR Camera Rig. When a player moves, their position and rotation are sent to a networked list. Other players read from this list, ensuring each avatar appears in the correct relative position to their object while allowing personal placement of elements like a chessboard.
Since remote avatars are moved using networked arrays of positions and rotations, the Networked Transform component of Photon Fusion is no longer needed. In the AvatarMovementHandlerMotif class, this component is disabled for each remote avatar to prevent Fusion from applying additional offsets, which could misalign avatars from the local chess board.

Troubleshooting Guide

Multiplayer development is not easy. However, following the setup guide should make sure that the app runs as expected. Below is a list of issues developers commonly face:

OvrAvatarAnimationBehavior.cs script missing in project

Unfortunately this appears because the OvrAvatarAnimationBehavior.cs is located in the Avatars samples. To install the samples go to the Package Manager > Meta Avatars SDK > Go to the samples tab and import the samples.

An avatar appears blue/purple

This indicates that the avatar asset could not be loaded. Make sure there are either avatar sample assets assigned in Unity or the user is entitled to use this app (see setup above). The issue could also be caused by the number of avatar presets the app is trying to load. On the Avatar Spawner Fusion class, located on the Networked Avatar Building Block, make sure the Preloaded Sample Avatar Size is 17 or less for the Avatar SDK v28 or higher, or 32 or less for older versions.

My avatar is not moving

Most likely the issue here is how the Building Blocks are trying to assign the input of the OVR Rig to the Avatars. Please stick to v31 or v38.0.1 or later.

I cannot see other avatars

This is a known issue. If this is happening in the editor, make sure to pan the camera around and move to where the other player is expected to be for its visuals to show up. On the headset, move around or simply wait a few seconds for the other clients to show up. If they still cannot be seen, it is most likely that the entitlement check failed on a client.

Can't copy CoreAssets from package folder to Avatar2 Assets folder error

Simply delete the CoreAssets folders found in the Avatar2 folder under Assets → Oculus → Avatar2 and restart the editor for the package to correctly copy the right core assets into the project.

.zip assets missing error from the Meta Avatar SDK Sample Assets package

Copy the missing files from the packages (Meta Avatars SDK and Meta Avatars SDK Sample Assets) into the corresponding Assets folders, or reinstall the Meta Avatars SDK Sample Assets.

Missing Fusion namespaces

Close Unity, delete the Photon folder under Assets, open Unity and reimport Fusion 2 as well as Photon Voice.

Missing BuildingBlock namespaces, even though Meta Core SDK is installed

This means some of the scripts are throwing errors before the packages have had a chance to compile. This usually happens when adding and removing the Photon folder during the development process. It most likely means the build settings did not clear the Scripting Define Symbols in the Player Settings. In that case make sure there are no symbols such as FUSION_WEAVER, FUSION2, or PHOTON_VOICE_DEFINED, before Photon Fusion 2 is imported!

I cannot upload my APK through the Meta Quest Developer Hub

This can have various reasons, indicated on the error message. More often than not, the upload fails because of a missing or unnecessary permission in the Android Manifest. To make the Android manifest compatible with the store, an editor extension can be found under Meta, then Tools, and then click on Create store-compatible AndroidManifest.xml.
However, if there are still unwanted Android permissions present, that cannot be removed either manually or with the editor extension, then it can be explicitly removed directly within the Android Manifest file. This is how a permission that is unexpectedly appearing might be removed. Simply add this line to the AndroidManifest.xml file in Unity:
<uses-permission android:name="android.permission.THE_UNWANTED_PERMISSION" tools:node="remove" />

Resources

Did you find this page helpful?
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2026 Meta