Unreal Engine 5.5 VisionOS Build on Apple Vision Pro
* Unreal Engine 5 has official Apple Vision Pro support in Unreal 5.5!
Intro:
UPDATE | iBrews has released a fantastic walkthrough video here:
The new documentation here is now split in two parts.
A) Epic Launcher Blueprint Project
- Ready out of box with very fast build times!
B) Source Code C++ Engine project
- Complex with debugging and longer build times.
This will cover all potential needs.
*It is HIGHLY recommended you build with Epic Launcher Unreal Engine in a Blueprint Project first to confirm everything is in working order before you move to a more complex source code C++ github UE project.
Move to the stable release of 5.5 version if you are still on 5.4 but please see the deprecated older documentation from Unreal Engine 5.4 if needed:
Disclaimer:
- These steps still 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/
- [Source Engine Only] 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 and this is not needed for launcher]
You will also need M1, M2, M3, or M4 device to build for Vision OS. I use the cheapest Mac Mini M2 with 8gb ram on a build machine for reference.
Example of expected blueprint project build times:
Min spec M2 Mini vs M4 Mini:
A) Building Launcher Blueprint Project for Vision Pro
- Xcode 16.1
- Go to your Apple Developer account
- Grab Xcode 16.1 Final: https://developer.apple.com/download/all/
- Download Xcode from app store if at time of writing:
2. Copy Xcode 16.1 [skip step if downloaded from App Store]
- Move“Xcode” unzipped from Xcode_16.1.xip into Applications folder
- (If you already have Xcode off the app store confirm it is 16.1 or make sure to rename it to anything like “Xcode_OG” before moving 16.1 Xcode from your downloads into the folder)
3. Open Xcode
- You will be asked which platforms to install
- Choose iOS 18.1 and VisionOS 2.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. Install Epic Launcher
- Download and install the launcher on your M-chip Mac
5. Install Unreal Engine 5.5 and the VisionOS prebuilt binaries.
- Download and install the launcher on your M-chip Mac along with the necessary platforms iOS and VisionOS
6. Select Games
- Allow editor to compile shaders and come up fully
- Once editor is up, select “Games”
7. Template
- Select “Virtual Reality” Template as your base to start.
8. Project Create
- Create the project. Blueprint projects can be placed almost anywhere.
9. Project Launch
- Will populate, compile, and then come up.
10. Plugin On
- Turn on Vision OS Open XR Plugin
11. 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
12. 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>
13. 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.
14. 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
15. Launch App
- Launch the app while inside the Apple Vision Pro
- If successful packaging a Swift window will come up on launch.
16. Hit the button
- You should see your scene.
- If you haven’t crashed congratulations!
B) Building Source Code C++ Project for Vision Pro
- Xcode 16.1
- Go to your Apple Developer account
- Grab Xcode 16.1 Final: https://developer.apple.com/download/all/
- Alternatively download Xcode from app store if at time of writing:
2. Copy Xcode 16.1 [skip step if downloaded from App Store]
- Move“Xcode” unzipped from Xcode_16.1.xip into Applications folder
- (If you already have Xcode off the app store confirm it is 16.1 or make sure to rename it to anything like “Xcode_OG” before moving 16.1 Xcode from your downloads into the folder)
3. Open Xcode
- You will be asked which platforms to install
- Choose iOS 18.1 and VisionOS 2.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.5
- Grab UE5 5.5 from GitHub source either Release at date of article or 5.5 channel as time moves on.
- https://github.com/EpicGames/UnrealEngine (Release)
- https://github.com/EpicGames/UnrealEngine/tree/5.5 (Channel)
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.5 and Setup Engine
- Open parent folder (ie “UnrealEngine-5.5”)
- 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 Unreal Engine 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. 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
20. 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>
21. 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.
22. 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.
23. 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
24. Launch App
- Launch the app while inside the Apple Vision Pro
- If successful packaging a Swift window will come up on launch.
25. Hit the button
- You should see your scene.
- If you haven’t crashed congratulations!
26. 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.
27. Return to Engine Directory to switch to “VisionOS” Xcode
- Quit your UE5 (Mac) workspace completely
- Go to the “Unreal-Engine-5.4” location again.
28. Open VisionOS Workspace
- Instead of (Mac) now open “UE5 (VisionOS).xcworkspace”
29. 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!
Thanks for reading and good luck on your projects!
