Test Your Quest VR Game Without a Headset: Meta XR Simulator in Unreal Engine (and the First Crashes to Expect)

Table of Contents

Unreal Engine 5.8 with OpenXR, Meta XR Simulator 207. Updated November 2026. Written by the Algosyntax team.

Quick answer: install the Meta XR Simulator, turn on XR Simulator runtime enabled in it, and then start the Unreal editor. VR Preview now runs in the simulator with a mouse and keyboard. For a hands-only app, switch the simulator’s input from Controller to Hand. The simulator runs Windows builds with the desktop renderer, so use it for gameplay and UI, not to judge how Quest looks or performs.

We built most of VR Musician, our hand-tracked Quest 3 piano app, this way.

Step 1: Make the simulator the OpenXR runtime

  1. Install Meta XR Simulator from Meta’s developer site.
  2. Open it and turn on XR Simulator runtime enabled. That makes it the active OpenXR runtime on your PC.
  3. Restart the Unreal editor.
  4. Open the menu next to the Play button and choose VR Preview.

VR Preview is greyed out

The editor log shows:

xrEnumerateInstanceExtensionProperties failed, suggests no runtime is installed

Unreal’s OpenXR plugin looks for a runtime only once, when the editor starts. If you enabled the simulator after opening the editor, restart the editor.

Step 2: Use hands instead of controllers

By default the simulator pretends you hold controllers, so a hands-only app ignores you. In the simulator’s left sidebar go to Inputs > Global Input Settings and set Left and Right to Hand.

  • Keys 1 to 4 switch the hand pose: aim, poke, pinch, grab.
  • Holding the left mouse button pinches.
  • WASD moves. Open the simulator’s Input bindings panel for the rest of the keys.

What the simulator can and can’t tell you

Good for Not good for
Gameplay, menus, hand interaction, placing things around the player How the game looks on Quest. It renders with the desktop renderer.
Frame pacing and profiling on PC Quest frame rates
Testing a packaged Win64 build Running your Android APK. It can’t.

A packaged Development Windows build runs on whatever OpenXR runtime is active and keeps the console (stat fps, stat unit), which makes it the best PC test of real performance. To see the Quest look, use the editor’s mobile preview; see Preview what Quest will show in the editor. Before you ship, test on a real headset.

The first crashes and bugs we hit in VR Preview

1. Fatal error on launch: Lumen plus MetaHuman hair

FHairEnvironmentLightingPS's required shader parameter FParameters::RadianceCache::RadianceProbeIndirectionTexture was not set

With Lumen as the global illumination method, groom (strand) hair is lit from Lumen’s radiance cache. In stereo VR that cache isn’t set up for the VR view, and the engine stops. Quest has no Lumen anyway, so turn it off for a VR project in Config/DefaultEngine.ini, then restart the editor:

[/Script/Engine.RendererSettings]
r.DynamicGlobalIlluminationMethod=0
r.ReflectionMethod=2
r.Lumen.TraceMeshSDFs=0

2. A dry square in the rain that follows your head

In VR only, puddles were missing in a square under the player that grew as we rose and changed when we turned our head. The cause was a top-down Scene Capture 2D (used to find where rain can’t reach) with Render in Main Renderer turned on. In a stereo frame it got the wrong depth.

To test whether this is your problem, type r.SceneCapture.AllowRenderInMainRenderer 0 in the console. If the artefact disappears, it is. We fixed it by turning bRenderInMainRenderer off on that capture whenever stereo is on (GEngine->StereoRenderingDevice->IsStereoEnabled()). That costs a separate small render of the capture, but only in VR.

3. Small red text over the VR view

If Common UI is enabled (often only because another plugin needs it) but your game doesn’t use it, it prints a warning about the game viewport client. Hide it with this line under [SystemSettings] in DefaultEngine.ini:

CommonUI.Debug.CheckGameViewportClientValid=0

4. VR Preview runs at 20 fps

VR Preview uses the editor’s scalability settings, which default to Epic, and renders the scene twice. See VR performance in Unreal Engine 5: how we went from 20 to 68 fps.

FAQ

Do I need the Meta XR plugin for the simulator? No. We used Unreal’s built-in OpenXR and OpenXR Hand Tracking plugins. Hand joints come from Get Hand Tracking State.

Can Android Studio’s emulator run my Quest APK? No. It only runs flat 2D apps.

What is the .vrs file the simulator saves? A recording of a simulator session for replaying input, not a log.

Related tutorials