Using the Xcode iOS Simulator

Xcode’s iOS Simulator provides a way to test applications on Apple’s back-catalog of iOS devices without the need to stockpile physical testing devices. This page provides a walkthrough of how to set up and use the iOS Simulator with Unreal Engine projects.

Prerequisites

To use the iOS Simulator, you need the following:

• An Apple Silicon Mac (An M1 Mac or newer) running MacOS Ventura or newer.

  • An Xcode installation compatible with your current version of UE. Refer to iOS Development Requirements for more information.

• A physical iOS test device for the initial setup.

  • A UE project with:C++ source code

  • iOS target platform

You also need to install the iOS Simulators you want to use. For instructions on installing iOS simulators, see Apple’s documentation.

As of UE 5.3, tvOS simulator support is not currently available. Additionally, only the 1st and 3rd-person projects have been tested and confirmed as working with the iOS Simulator. Other projects may use additional plugin libraries that aren’t updated to support the iOS Simulator yet.

Enable iOS Simulator Support for your UE Project

To enable support for the iOS simulator in your project:

1. Open Unreal Editor, then open your Project Settings.

2. Under Project Settings > Platforms > iOS > Build, check Enable iOS Simulator Support.

3. Under the iOS > Rendering section, check Support Apple A8.

4. Re-run GenerateProjectFiles.command to regenerate your Xcode projects. This updates the Xcode .xconfig files to support the iOS Simulator.

5. Restart Unreal Editor.

6. Click the Platforms dropdown and do at least one Quick Launch to an iOS device. This creates a build that contains cooked content for iOS.

7. Open your iOS project in Xcode. Click Edit Scheme, then select Run, and navigate to the diagnostics section. Disable Metal API Validation.

If you do not disable Metal API validation, your project will throw errors when you attempt to launch the iOS Simulator from Xcode.

Your Xcode project for iOS now has everything it needs to use the iOS Simulator.

Upgrade Existing Projects to use the iOS Simulator

If you are adding iOS Simulator support to a project that is already compiled and cooked, you may have errors when attempting to compile with iOS Simulator Support enabled due to issues with your shader libraries. To remedy these errors, delete all cooked content for your project after you enable the Enable iOS Simulator Support setting, then launch your project to your iOS device again.

The iOS Simulator needs a different shader library compared to physical devices, so UE projects create two Metal libraries: one standard, and one called Metal-Sim for the Simulator.

Launch the iOS Simulator from Xcode

1. Open your project’s UE5 (IOS).xcworkspace file in Xcode.

2. Click the Target Device dropdown, then click iOS Simulator. A dropdown menu opens, displaying the iOS devices you can simulate.

3. Choose an iOS device compatible with your current version of Unreal Engine. Refer to iOS Development Requirements for a list of supported devices.

4. Click the Play button to compile and run your project.

When your project finishes compiling, the iOS simulator launches in a window that imitates your target device. If your application has already been built and you have no code changes, it should compile in a very short time compared with installing to a physical iPhone.

Running Multiple Instances

You can run up to six iOS simulators for your application simultaneously. Running multiple simulators is useful for comparing rendering issues between different versions of iOS. To see which simulators you are currently using, click the Window button in the toolbar.

Expect your system to slow down dramatically when running three or more instances of the iOS simulator simultaneously.