This documentation details early functionality that is still under active development. The content and processes may significantly change over the next several release cycles.
Overview
Testing multiplayer functionality in your app is vital for troubleshooting your users’ multiplayer experience and ensuring they have a smooth process when playing together.
With multiplayer testing in Unreal you can reduce the number of separate users and headsets needed to test multiplayer functionality to a single headset, player/developer, and a single instance of Link.
This documentation provides two solutions for testing multiplayer in your Unreal App: Single Process mode and Multiple Processes mode.
Single Process Mode testing uses multiple PIE windows run in the same process via Link. Single process testing is generally faster and less resource intensive but, per Epic, “also has the potential for more issues” (Unreal Engine Documentation)
Multiple Process mode testing uses multiple PIE windows each running their own process via Link. Multiple process testing is generally more accurate than single process testing but it is far more resource-intensive. Generally multi process mode should be reserved for instances where Platform SDK features are necessary or when there are errors from single process mode testing.
Prerequisites
To set up multiplayer testing in your app, you will first need a VR application created in Unreal.
Note: This guide uses Link, which currently only works on PC.
To begin testing your multiplayer app in Unreal, you must first connect your Meta Quest headset to your computer and start Link. Check the Link for App Development for more information on using Link.
Once finished, in your headset you can start Link in your headset by opening the Anywhere UI (AUI) via the hand gesture or the Meta Quest button and selecting Quick Settings > Settings > Systems > Quest Link*> **Launch Quest Link.
Single process mode testing
Once your headset is connected via Link, you can begin testing your app’s multiplayer functionality using Unreal’s VR Preview functionality.
Single process testing is generally less resource intensive.
If you don’t have a multiplayer app ready, you can use the Blueprint below which modifies the VRTemplate project to work as a usable multiplayer test app. With this Blueprint you can use the Meta Quest Controller to shoot balls and the balls will spawn to all players in the multiplayer session.
If you want to switch active players on the fly in the sample Blueprint, use the following example where changing the vr.PrimaryPIEIndex allows you to switch the active player.
Note: This CVar is currently only available in the Single Process Mode of multiplayer testing.
To test multiplayer functionality in your Unreal app via Single Process mode, use the following process:
Open the Edit menu and select Editor Preferences.
In the Editor Preferences menu, enable and configure the following options:
Enable Run Under One Process to ensure all players are run in a single process (Default)
Set Play Number of Clients to a number larger than 1.
Change the Play Net Mode to Play As Listen Server. Standalone mode won’t use a server for the multiplayer app.
Go to Project Settings, enable and configure the following options:
Enable Set Active PIE to Primary and Set CVar PIE to Primary (Default)
You can optionally disable the Proximity Sensor. For more information on the Proximity Sensor, check the Meta Quest Developer Hub documentation for Unreal.
Once your Unreal project is configured, click the three dots on the play bar and select VR Preview to run your app.
Multiple PIE (Player in Editor) windows will be shown together via the Quest Link Debug window. The Quest Link debug window will always be synced with the current PIE window.
Your application can now be played and tested in the current PIE window. TO switch to another window and control another player, tab switch (Alt/CMD + Tab) to swap active windows.
Note:
If you setup the sample Blueprint using vr.PrimaryPIEIndex, you will be able to switch the active editor window using that configuration. In the current example you can press the A and B button on the Meta Quest controller to switch between player 0 and 1.
You can change whether to save and restore the player’s position or their position and rotation when switching between the active and non-active status by navigating to Project Settings > MultiPlayer Pose Restore Type as shown in the above image.
Single process sample video
The following is a sample video of two players sharing the same HMD:
In the sample video, all PIE windows are attached to the same Quest headset and, by switching the active PIE window, you can use the same Quest headset to test each player.
As player 1 in the sample video, we pressed X to shoot some balls at cubes, then we switched to player 0 and saw that the cubes were gone after being shot by player 1. Additionally, player movement is demonstrated using the controller buttons (for example, teleporting for movement) and other players’ PIEs were not affected.
Known Issues
Currently the head pose is shared between all users when using multiple PIE windows to test multiplayer.
Multiple processes mode testing
Once your headset is connected via Quest Link, you can begin testing your app’s multiplayer functionality using Unreal’s VR Preview functionality.
If you don’t have a multiplayer app ready, you can use the below Blueprint which modifies the VRTemplate project to work as a usable multiplayer test app. With this Blueprint you can use the Meta Quest Controller to shoot balls and the balls will spawn to all players in the multiplayer session.
To test multiplayer for your Unreal App via Multiple Process mode, use the following process:
Open your Unreal app and select Edit > Editor Preferences.
In the Editor Preferences menu, enable and configure the following options:
Disable Run Under One Process to ensure players are in separate multiplayer processes
Disable HMD For Primary Process Only to ensure every player can be connected to HMD
Set Play Number of Clients to a number larger than 1
Set Play Net Mode to Play as Listen Server
You can optionally disable the Proximity Sensor. For more information on the Proximity Sensor, check the Meta Quest Developer Hub documentation for Unreal.
To include Platform SDK in your testing process, you must first set up an app ID. Once the app id is set up you must set up an email and password for each player to get their own email and password as shown below.
You can use the following simple Blueprint which demonstrates working with the Platform SDK. Once implemented it will print the current user’s name on screen:
After configuring your Unreal project, click the three dots on the play bar and select VR Preview to run your app.
Multiple PIE (Play In Editor) windows will be showing the Quest Link Debug window and each window will run as its own process. The Quest Link Debug window will always be synced with the current PIE as shown below:
Note: As of the v66 release, the inactive player’s head pose is not updated when the HMD moves. You can change this behavior by navigating to Project Settings > Enable head pose update for inactive VRPreview player.
With multiple PIE windows open, you can now test multiplayer functionality of your app. Note that there may be noticeable performance penalties from running multiple PIE windows. You can reduce the number of multiple PIEs running at once to reach acceptable performance.
Multiple process sample video
The following is a sample video of three Unreal Engine instances running to test multiplayer functionality.
In the sample video, all PIE windows are attached to the same Quest headset and, by switching the active PIE window, you can use the same Quest headset to test each player.
As player 0 in the sample video, we pressed X to shoot some balls at cubes, then we switched to player 1 and saw the cubes were gone after being shot by player 0. Additionally, player movement is demonstrated using the controller buttons (for example, teleporting for movement) and other players PIEs were not affected. Further, a player’s Oculus ID obtained from the PlatformSDK is shown a a blue-colored message in the top-left corner whenever the A button is pressed.
Known Issues
Currently the head pose is shared between all users when using multiple PIE windows to test multiplayer.
You can use the following simple Blueprint which demonstrates working with the Platform SDK. Once implemented it will print the current user’s name on screen:
