iOS Quick Start Guide

Set up an Unreal Engine project for iOS, tvOS, or iPadOS.

Choose your operating system:

Windows

macOS

Linux

This quick start guide explains all the steps required to build an Unreal Engine project for Apple's iOS, iPadOS, and tvOS platforms. By completing this guide, you will:

  • Set up Xcode on your Mac.

  • Connect to your device in Xcode.

  • Register your device with your Apple Developer account.

  • Create a Provisioning Profile and Certificates for your project.

  • Configure your project for iOS.

  • Build and run your project on an iOS device.

This guide covers creating signed builds for C++ projects. For Blueprint-only projects on Windows, there is an alternate workflow for building iOS projects. Refer to Building Blueprint-Only Projects for iOS for more information.

Additionally, while this guide refers to iPhone and iOS as an example, note that the same setup steps are used for tvOS. To connect to a tvOS device, refer to the Connecting to a tvOS Device page.

1. Requirements

To build projects for Apple's platforms, you need the following:

  • A computer running MacOS with Unreal Engine installed.

  • An installation of Xcode that is compatible with your current version of Unreal Engine.

  • An Apple Developer Account.

  • An iOS device that is compatible with your current version of Unreal Engine.

The following software versions are compatible with the current version of Unreal Engine:

  • Current UE Version: 5.0

    • Supported Target SDK versions: iOS 14 or later

    • Recommended MacOS and Xcode Versions

      • Latest MacOS Monterey

      • Latest Xcode 13

    • Supported MacOS Version

      • MacOS Big Sur 11.6.4

    • Minimum MacOS and Xcode Versions

      • MacOS Catalina 10.15.7

      • Xcode 12.4. Note that Xcode 13 is required to test locally with iOS 15 devices.

The following iOS hardware versions are compatible with the current version of Unreal Engine:

  • iOS 14

    • iPhone 6S or later

    • iPod Touch 7th generation

  • iPadOS 14

    • iPad 5th generation or later

    • iPad Air 2 or later

    • iPad Mini 4 or later

    • iPad Pro (all models)

  • tvOS 14

    • Apple TV HD

    • Apple TV 4K (first generation)

    • Apple TV 4K (second generation)

For software compatibility information about older versions of Unreal Engine, refer to the iOS Development Requirements page.

2. Software Setup

  1. If you do not already have Xcode installed on your Mac, download and install it from the App Store. You will need to sign in with your Apple ID.

    Download Xcode from the App Store

  2. Once Xcode is installed, open it, click Xcode > Preferences, open the Locations tab, then verify that the Command Line Tools path is set to the current version of Xcode. If this path is not set, you will not be able to open Unreal Editor, as the Metal shader compiler will not be able to find Xcode.

    Make sure to set your Command Line Tools path

3. Creating Your Project

To set up a Mobile project, open Unreal Editor and create a new project with the following specifications:

[INCLUDE:sharing-and-releasing-projects/General-Mobile-Development/quickstart/#CreatingMobileProject]

The above specifications and project name are from the Creating a Mobile Project guide. Refer to that page for more details on these specifications.

4. Connecting Your Device With Xcode and Registering it With Your Apple Developer Account

To use your iOS device for testing, you need to connect it to your computer, make sure it is recognized by Xcode, and register it in your Apple Developer Account as a testing device for your apps. The device registration will be used later for creating a Provisioning Profile. Follow these steps to set up your device:

  1. Connect your iOS Device to your computer with a USB cable.

  2. Open Xcode, then click Window > Devices and Simulators.

  3. Unlock your device to grant Xcode access to it. When you see the Trust This Device prompt on your iOS device, click Yes, then provide your passcode. Xcode will fetch debug symbols for the device.

  4. Log in to your Apple Developer account at developer.apple.com. If you do not have an Apple ID and a developer account, create one.

    While Epic's software is available free of charge, Apple Developer accounts cost a fee of $99 per year. Keep this in mind when registering your account.

  5. Once you have logged in, click Certificates, Identifiers & Profiles.

  6. Click Devices, then click Register a Device.

  7. Fill out the following information about your device:

    • Set the Platform to iOS, tvOS, watchOS.

    • Set the Device Name to a unique, recognizable name.

    • Look at the information about your device in Xcode in Window > Devices and Simulators. Copy the Identifier, then return to the Register a Device page and paste it into the UUID field.

    Click Continue when you are finished.

  8. Double-check that the information about your device is correct. If you input the wrong UUID, you may see the wrong type of device listed. Click Register to finish registering your device with your Apple developer account. When registration is complete, click Done.

5. Provisioning and Signing

The following is a short summary of how to obtain a Code Signing Certificate and Provisioning Profile for your app, which are required to package an iOS project. For fully detailed steps, refer to the iOS Provisioning guide.

  1. Connect your Apple Developer ID with Xcode in Xcode > Preferences > Accounts.

  2. Create an Identifier (App ID) for your app. Provide a Bundle Identifier name with the format com.(OrganizationName).(ProjectName). In this example, the Bundle Identifier is com.YourCompany.MobileTestProject.

  3. Open your project's Xcode project file, then make sure it has the same Bundle Identifier as you specified for your App ID. Do the same in Unreal Editor in Project Settings > Platforms > iOS.

  4. Under Signing & Capabilities, enable Automatically Manage Signing, then set your Team to the name associated with your Apple Developer account. Xcode will automatically generate a code signing certificate. Alternatively, you can create one manually in the Certificates, Identifiers, and Profiles section of the Apple Developer Page.

  5. Open the Apple Developer page, then open Certificates, Identifiers, and Profiles. Create a new Provisioning Profile using your Identifier, your registered device, and your signing certificate. Download it to a convenient location, such as a Provisioning folder.

  6. Go to the Apple Certificate Authority Page and download the latest WWDR Intermediate Certificate. Open the Keychain Access app and drag the certificate into the System keychain. This is not necessary to package your project for testing, but it is necessary for shipping.

  7. Open your project in Unreal Editor, then open Project Settings > Platforms > iOS. Give the editor a few moments to discover your Provisioning Profile and your Signing Certificate, then select each of them.

6. Packaging Your Project

After completing the above sections, click the Platforms dropdown, then click iOS > Package Project. If all of your components are set up correctly, your project will package successfully. You can also use the Quick Launch option to launch on your selected device directly.

Final Result

After following the steps in this guide, you will have an iOS project set up, ready to launch on your test device,