Unreal Engine 5.4 VisionOS Build on Apple Vision Pro

Youtube Walkthrough:

Epic dropped Quick Start Documentation:

Apple Vision Pro Quick Start Guide | Tutorial

Intro:

Due to Unreal Engine 5 having only very early Apple Vision Pro support the process is a bit convoluted. This is an attempt to be explicit in steps to build.

In order to help others attempting and asking questions on X and Epic Forums I have aggregated the steps it took to get things up in a decent enough state on UE 5.4

Disclaimer:

• These steps might age poorly as rapid early development continues.

Setting Up:

You need to have your Vision Pro developer mode on and connected to the same network. There is a process to set mode then pair your headset:

This step by step process will assume you have an Apple Developer account and entitlements are ready to go.

Meaning you can already build an app in Xcode using your team and have tested that the process of signing an app works. Also ensure you are logged into Xcode with our developer account.

• Please refer to Epic’s QuickStart documentation for Xcode checks.
• You can acquire previous Xcode versions from apple developer site with a dev account. For more: https://developer.apple.com/
• You will need to set up for “Always Allow” apps using terminal if you have not done development yet [We seemed to need this for the setup engine and generate project files command files]

You will also need M1, M2, or M3 device to build for Vision OS. I use the cheapest Mac Mini M2 with 8gb ram on a build machine for reference.

Building For AVP:

1. Xcode 15.3

• Go to your Apple Developer account
• Grab Xcode 15.3 Final: https://developer.apple.com/download/all/

• Alternatively download Xcode from app store if at time of writing:

2. Copy Xcode 15.3 [skip step if downloaded from App Store]

• Move“Xcode” unzipped from Xcode_15.3.xip into Applications folder
• (If you already have Xcode off the app store confirm it is 15.3 or make sure to rename it to anything like “Xcode_OG” before moving 15.3 Xcode from your downloads into the folder)

3. Open Xcode

• You will be asked which platforms to install
• Choose iOS 17.4 and VisionOS 1.1
• If you are past the window revisit platforms by going to toolbar:
  Xcode -> Settings -> Platforms
• Be sure you apple developer account is logged in at the @ Accounts tab
• Once installed minimize window

4. Github Unreal Engine 5.4

• Grab UE5 5.4 from GitHub source
• https://github.com/EpicGames/UnrealEngine/tree/5.4

5. Terminal set Always Allow

• Open Terminal in Finder -> Applications -> Utilities
• Type in: sudo spctl — master-disable
  Note: if having trouble Jack Yang recommended sudo spctl — global-disable
• Password in terminal (it will not be visible as you input it) and hit enter
• Navigate to System Settings -> Privacy & Security -> Security
• Set “Allow Applications downloaded from” to “Anywhere”

6. Unzip UE5.4 and Setup Engine

• Open parent folder (ie “UnrealEngine-5.4”)
• Run Setup.Command
• Wait for it to finish

7. Generate Project

• Run GenerateProjectFiles.command
• Wait for it to finish

8. Find Workspace

• Open “UE5 (Mac).xcworkspace”

9. Set Up Xcode 15.3

• Change the “UnrealGame” to “UnrealEditor”

10. Build Editor

• Go to the toolbar in Xcode
• toolbar: Product -> Build

11. Coffee

• Grab coffee and allow engine to compile

12. Directory

• Once finished go to the “UnrealEngine-5.4” parent folder again
• Navigate to:
  /Engine/Binaries/Mac/
• Then select UnrealEditor and open

13. Select Games

• Allow editor to compile shaders and come up fully
• Once editor is up, select “Games”

14. Template

• Select “Virtual Reality” Template as your base to start.

15. Project Create

• Create the project inside the “UnrealEngine-5.4” folder
• Where the “Engine” folder lives, adjacent to said folder.

16. Project Launch

• Will populate, compile, and then come up.

17. Plugin On

• Turn on Vision OS Open XR Plugin

18. Platform On

• Turn on Support Vision OS Platform

19. Anti Aliasing OFF [This step is under evaluation as to if important or not with latest updates]

• Go to Project Settings and turn off AA

20. Turn off iOS Mobile Rendering and on Desktop Rendering

• Mobile Metal Renderer seems to have issues in my tests at this stage.
• I went with desktop instead of mobile
• The combination seemed to work around the artifacts and warping issues others were having out there.
• [Epic QuickStart Update] “If you switch over to the Deferred desktop renderer, run with -norhithread (Xcode product scheme has a place to put command line arguments) to avoid an error complaining that we call cp_frame_ functions from two threads (see image)”

21. Toggle Multi View and Instanced Stereo [Updated From Epic QuickStart]

• “Disable MobileMultiview and InstancedStereo
• They will not appear to be enabled, but click the checkbox to enable, and click again to disable (this will improve)”

22. Xcode Signing

• Add your dev information to Xcode project settings
• This is the area for your Team id and “com.yourcompany.yourapp”
• Add Apple Dev Account ID
• Add Bundle ID
• Remove Bundle ID Prefix
• Add Published App Name

23. Add Plist Permissions

• You will need to add permissions for any Vision OS asks
• Example used in the “Additional Plist Data” section iOS project settings

<key>NSHandsTrackingUsageDescription</key><string>Hand Usage</string><key>NSMicrophoneUsageDescription</key><string>Mic Needed </string><key>NSWorldSensingUsageDescription</key><string>World Sensing</string>

24. Create a C++ class

• toolbar: Tools -> Create New C++ Class
• Project will ask to recompile.
• Hit Next then Create Class
• Allow project to recompile
• Restart editor after to ensure project works and shaders compile
• Might be long recompiling shaders due to the previous Metal changes.

25. Turn off Dynamic Shadows [optional]

• Discovered there were dynamic shadows eating up significant performance.
• Go to the directional light and turn off dynamic shadows to remove shadow casters from scene.
• This was a part of hitting 90 fps for initial evaluations and recommended for initial build then addressed when ready.

26. Package VisionOS

• Build should cook, package, and drop an .app at the target location.
• It will take some time due to compiling from source, shader generation, and your hardware.

27. Back to Xcode

• toolbar: Window -> Devices and Simulators
• Confirm your Apple Vision Pro is connected and ready
• Hit the + to add an app
• Find your .app that has been built and hit Open
• Here it is called “MyProject” .app in the /MyProject/VisionOS/ folder

28. Launch App

• Launch the app while inside the Apple Vision Pro
• If successful packaging a Swift window will come up on launch.

29. Hit the button

• You should see your scene.
• If you haven’t crashed congratulations!

30. Crash?

• If you crash on your scene coming up you will need to debug. This means you will want to push your build from Xcode rather than manually installing the .app
• If you launch and see a swift window but crash on button press you signed and built fine and need to debug your crash in Xcode.
• If you are not launching at all it is likely permissions (plist) or your apple dev signing.

31. Return to Engine Directory to switch to “VisionOS” Xcode

• Quit your UE5 (Mac) workspace completely
• Go to the “Unreal-Engine-5.4” location again.

32. Open VisionOS Workspace

• Instead of (Mac) now open “UE5 (VisionOS).xcworkspace”

33. Running From Xcode and Debugging

Go to the area where you switched to Unreal Editor last time, and instead change it to “MyProject” or what name the project had at create.

• Put on your Apple Vision Pro
• Make sure “Vision Pro” is seen by your network and selected as target
• Hit the “Play” button to build and push to your Vision Pro from Xcode.

• The build will then push the app and come up with debugging in the console log once it launches in your headset. It will take longer than the .app possibly a minute or two.
• Repro the steps you did with the original .app and force the crash.
• Then in your output you should have information and/or break that can lead you to the reason. Could be rendering based or plist permissions but the hint will be there.
• What I have run across so far had to do with rendering, multi view, generally all checkbox render settings issues.
• Debug and fix until it runs!

Special thank you:

• Alex Coulombe “iBrews”
• Yannick Comte “cyannick”
• Michael Becker “michae1becker”

For sharing and showing it was finally possible in UE5.

• Steve Talkowsi “SteveTalkowski”

For working through missing steps and testing out doc.

Thank you all!

That should help get Apple Vision Pro Unreal Builds working until improved official support fully arrives. Thanks for reading and good luck on your projects!