Happy path for VR dev on MacOS is broken by default

TL;DR Skip to the Fix Unreal 5.2.1 Editor for VR Dev on MacOS section at the bottom for the fix. The rest of the post is just an explanation of why it’s happening for context.

Unreal 5.2.1 is currently what’s recommended for Unreal VR dev for Quest in the Oculus Developer documentation.

This is usually considered the happy path, since the alternative is to compile the Oculus-VR fork of Unreal Engine. While that’s a very good idea to consider for projects in production, oftentimes you just want to prototype something or build something small or you’re just getting started with a new project. In these cases, compiling Unreal Engine, which is known for taking an ungodly amount of time for obvious reasons, is not a good or great idea. For example, if you want to get to work within an hour rather than wait until tomorrow.

Which comes to the crux of the problem, Unreal Engine 5.2.1 crashes upon Editor launch on MacOS when the VR Template is enabled. This is not good, since the VR Template has a lot of what you’d want to start a VR project. You could just start fresh and enable what you need for VR and manually add the useful assets, but not only is that time consuming, you could run into the exact same issue.

The crux of the issue is that the default VR Template still uses an out of date system for VR, which is InstancedStereo rendering which was added in UE4. This has been deprecated in favor of Mobile Multiview, despite still stating it’s experimental in the UE5 documentation. However, InstancedStereo isn’t supported at all on modern MacOS. Which is normally fine, because setting InstancedStereo to True is usually handled by the engine by automatically just ignoring that and using Mobile Multiview in its stead. However, that system fails to properly make that switch on MacOS, causing it to fall back to InstancedStereo which isn’t supported and thus crashes the Editor on launch.

Now, an easy solution to this problem is just to use Windows where this error doesn’t occur. But let’s ignore that for the sake of this conversation.

So let me tell you how to fix it and get back to developing an Unreal VR app on a Mac, you animal.

Fix Unreal 5.2.1 Editor for VR Dev on MacOS

  1. Open DefaultEngine.ini in the Config folder of your Unreal Project with a text editor
  2. Search the text for “InstancedStereo” (should be on Line 73 by default)
  3. Change vr.InstancedStereo = True to vr.InstancedStereo = False
  4. Save DefaultEngine.ini
  5. Open your VR Template project

Happy Hacking :slight_smile: