Launch your game on mobile (iOS)

You can launch your game directly from the Unreal Editor to your mobile device by using the Launch button in the Unreal Editor. Launching your game to your mobile device means you can iterate on changes to your game and quickly confirm the changes on your device. For more information on Unreal Engine’s support for launching your game to your mobile device, see Launching to Devices.

This guide takes you through setting up your iOS mobile device, Windows development machine, macOS build machine and the Unreal Editor so that you can launch your game to your mobile device and connect to a SpatialOS deployment.

Before following this guide, you must do the following for both your Windows development machine and macOS build machine:

You also need to do the following for your Windows development machine:

If you do not already have an Unreal Engine project, then you can use the Example Project to follow this guide.

We support development using the GDK for Unreal on both Windows and macOS. We strongly recommend that you use Windows as your development machine. If you choose to use Windows as your development machine, you also need a macOS machine to build and sign game packages for iOS devices.

In this guide, we assume you use Windows as your development machine and macOS for only building and signing game packages.

To launch your game on mobile (iOS), follow the steps below.

Step 1: Install iTunes on your Windows development machine

To manually install game packages on your iOS device, you need to install iTunes on your Windows machine. To do this, download and install iTunes from Apple.

Note: The version of iTunes that is currently available on the Windows 10 store might cause problems when using Unreal Engine. Ensure you download an older version of iTunes directly from Apple. The version number does not matter. Install iTunes, then upgrade it to the latest version.

Step 2: Set up your iOS mobile device

You need to make sure your iOS mobile device trusts your Windows development machine. To do this, follow these steps:

  1. Open iTunes on your Windows development machine.

  2. Connect your mobile device to your Windows development machine using a USB cable. If your device displays a pop-up window requesting your permission to trust your computer, select Trust.

  3. iTunes displays the following message:
    Do you want to allow this computer to access information on <your mobile device name>
    Click Continue to allow your Windows development machine access to your mobile device.
    Your mobile device name is displayed in iTunes to show that it is connected.

If you want to connect your mobile device to a local SpatialOS deployment, then you must connect your development machine and mobile device to the same local area network and subnet mask. This is because the IP address of your mobile device is required to launch to that device, and it must be an IP address on your local area network.

Step 3: Set up your iOS signing certificate

To set up your iOS signing certificate, follow these steps on your macOS build machine:

  1. You need an Apple Developer Organization to develop clients for iOS and complete this guide. To sign up for the Apple Developer Organization, go to Apple Developer Program, click Enroll and follow the instructions provided.

  2. You need an iOS signing certificate on your macOS build machine to develop and distribute your iOS game. To create a certificate request, follow these steps in the Apple documentation: Create a certificate signing request.

  3. Go to the iOS Certificates page on the Apple Developer site and log in.

  4. Click the Add (+) button, select iOS App Development and click Continue.

  5. To generate a new certificate for your game, click Choose File and select the certificate signing request (.csr file) you created earlier.

  6. Click Continue. This creates a new certificate.

  7. Click Download.

  8. To install the certificate on your macOS build machine, double-click on the ios_development.cer file you just downloaded. It opens in Keychain Access, indicating that it is installed.

  9. You need to export the certificate from your macOS build machine to your Windows development machine. To do this, in Keychain Access on your macOS build machine, go to Keychains > login and Category > Certificates.

  10. To export the certificate you created earlier, right-click on it and select Export. Make sure the File Format is set to Personal Information Exchange (p.12) and click Save.

  11. Leave the password field blank and click OK.

  12. When you see the prompt: Keychain Access wants to export key from your keychain, enter your macOS build machine password and click Allow. An encrypted file containing your certificate is saved to the location you specified with the p.12 file extension.

  13. Use a secure method to transfer the p.12 file to your Windows development machine.

Step 4: Set up your Apple provisioning profile

To use Unreal Engine to launch to your mobile devices, you need to add them to your provisioning profile on the Apple Developer site. You then need to download the profile and install it in the Unreal Editor.

Register devices to your Apple Developer organization

To add your mobile devices to your Apple provisioning profile, you first need to register the devices to your Apple Developer organization. To do this, follow these steps on your macOS build machine:

  1. Go to the Certificates, Identifiers & Profiles > Devices page on the Apple Developer site.

  2. To add one of your mobile devices, click the Add (+) button at the top right of the screen.

  3. Select iOS, watchOS tvOS from the Platform drop-down menu.

  4. Enter a Device Name of your choice.

  5. Enter the Device ID (UDID) of your mobile device and click Continue.

To find the UDID for your mobile device, follow these steps:

  1. Plug your iOS device into your macOS build machine.
  2. In Finder, click on your mobile device.
  3. Click on the description of your device (under the name). For example:
    iPhone 6s ∙ 56 GB (20 GB Available) ∙ 92%
    The information displayed changes each time you click. Click until the UDID is displayed.
  4. Right-click on the UDID and select Copy UDID.
  1. Check that the information you have entered is correct and click Continue.

  2. You need to repeat the above steps for every mobile device you want to use to launch from the Unreal Editor.

Create an application ID (App ID)

To create a provisioning profile, you need to create an application ID (App ID) to identify one or more of your applications from a single development team. To do this, follow these steps on your macOS build machine:

  1. Go to the Certificates, Identifiers & Profiles > Identifiers page on the Apple Developer site and log in.

  2. Set the Identifiers filter to App IDs.

  3. To add a new App ID, click the Add (+) button at the top right of the screen.

  4. Select Register a new identifier > App IDs and then select Continue.

  5. Enter a name for the App ID.

  6. You do not need to change the App ID Prefix.

  7. To use a single App ID for multiple applications, select the Wildcard App ID radio button.

  8. Follow the example format provided by Apple and enter a Bundle ID.

  9. You don't need to enable anything in the Capabilities section.

  10. Click Continue.

  11. Check that the information you have entered is correct and click Continue.

Create and download your provisioning profile

Your provisioning profile includes your iOS signing certificate, the devices you have set up and the App ID. There are two types of provisioning profile. The first profile is a development provisioning profile that you need to build and install your game. The second profile is a distribution provisioning profile that you need to use to submit your game to the iOS App Store. To create a development provisioning profile, follow these steps on your Windows development machine:

  1. Go to the Certificates, Identifiers & Profiles > Profiles page on the Apple Developer site.

  2. To add a new provisioning profile, click the Add (+) button at the top right of the screen.

  3. Select the iOS App Development radio button.

  4. Click Continue.

  5. Select the App ID you created earlier and click Continue.

  6. Select the iOS signing certificate that you created in Step 3 above and click Continue.

  7. Select all the devices that you added to the provisioning profile earlier and click Continue.

  8. Enter a Profile Name that is a useful reference for your project and click Generate.

  9. To download the .mobileprovision file, click Download.

Step 5: Install your iOS signing certificate and provisioning profile in the Unreal Editor

You need to install the iOS signing certificate and provisioning profile on your Windows development machine. Follow these steps to do so:

  1. Open your project in the Unreal Editor and go to Edit > Project Settings > Platforms > iOS > Mobile Provision.

  2. Select Import Provision and select the .mobileprovision file you created earlier.

  3. Select Import Certificate and select the iOS signing certificate (p.12 file) that you created in Step 3.

Step 6: Set up an SSH connection between your Windows and macOS machines

You need an SSH connection between your Windows machine and your macOS machine so that you can use a Windows machine to create an iOS build on your macOS machine. To set up an SSH connection and build for iOS, follow these steps in the Unreal Engine documentation: Building for iOS on Windows.

Step 7: Prepare your game for mobile in the Unreal Editor

You need to generate schema and snapshots for SpatialOS before you can launch directly onto your mobile device. You also need to ensure that the Unreal Editor installs a package file on your mobile device when you launch your game. A package file includes all the code, resources, assets and metadata for your game.

To prepare your game for mobile in the Unreal Editor, follow these steps:

  1. In the Editor, on the GDK Toolbar, select Schema. This generates schema iteratively if you have already generated schema for your project. If you haven’t already generated schema for your project then the GDK uses a full scan to do so.
    For more information on generating schema, see Schema.

  2. To generate a snapshot, select Snapshot.
    For more information on generating a snapshot, see Snapshots.

  3. By default, the Unreal Editor does not build your game code in the package file when you launch your game.
    To ensure that the Unreal Editor includes your game code every time you launch your game, navigate to Edit > Editor Preferences > Level Editor > Play > Play on Device > Build game before launch and select Always from the drop-down menu.
    Note: When you select Launch in Step 8 and 9 (below) the Unreal Editor builds your game package and installs it on your mobile device.

Step 8: Connect to a local deployment

When you want to try out your game, you need to start a SpatialOS deployment. A local deployment is for testing only. You can run multiple clients in a local deployment, which is useful for fast development iteration. To connect your game to a local deployment, you need to ensure that your development machine and mobile device are on the same local area network, and set the IP address of your local deployment in the Unreal Editor.

When you launch your game on your Windows development machine, the SSH connection you set up earlier is used to start a build on your macOS build machine. The launch process transfers the final build using the SSH from the macOS build machine to the Windows development machine. Logs for this build appear in the Output log in the Unreal Editor on your Windows development machine.

To set up the Unreal Editor and connect to a local deployment, follow these steps:

  1. Identify the IP address of your Windows development machine by following these instructions: https://lifehacker.com/how-to-find-your-local-and-external-ip-address-5833108 \ Make a note of the IP address because you will need it later.

  2. In the Unreal Editor, select the Start Deployment drop-down menu.

  3. Select Connect to a local deployment.

  4. Enter the IP address of your Windows development machine in the Local Deployment IP field.

  5. If you already have a local deployment running, select Stop Deployment.

  6. Ensure that your mobile device is connected to your Windows development machine using a USB cable.

  7. To avoid the build process failing on your macOS build machine when the display turns off, go to System Preferences > Energy Preferences and select Prevent computer from sleeping automatically when display is off.

  8. Select the Launch drop-down menu and select your mobile device. The Unreal Editor begins the process of packaging your game and displays the following message:
    Processing Assets for IOS…
    Note this process can take a long time to complete when you run it for the first time.
    When the package process is complete, a local deployment starts with one server worker instance and the Unreal Editor installs your game on your mobile device.

  9. To play your game, open the app on your mobile device.

  10. To finish playing your game, close the app on your mobile device and select Stop Deployment in the Unreal Editor.

Tip: If you have a blank screen on your mobile device when you launch your game, you might need to wait a short time for the game to appear. If you continue to see a blank screen, check that your mobile device is connected to your local area network and that a SpatialOS deployment is running.

Tip: You can unplug the USB cable from your mobile device after the game has launched because the transfer of data has finished. You need to plug the USB cable back in to launch a new version of your game.

Step 9: Connect to a cloud deployment

You can start cloud deployments from Windows development machines only. Cloud deployments are not available from macOS development machines. However, you can use your macOS machine to connect to a cloud deployment that you have started on your Windows machine.

To do this, copy the file <GameRoot>/Content/Spatial/SchemaDatabase.uasset from your Windows machine to your macOS machine in the same directory (<GameRoot>/Content/Spatial/)

A cloud deployment runs on remote networked nodes. You can use a cloud deployment during development to share your game with test users and run it at scale. You share your Windows game with test users through the SpatialOS Launcher, where they can download and install the game.

Before you start a cloud deployment, in addition to generating schema and a snapshot in Step 7 (above), you also need to:

  • Identify your SpatialOS cloud project name.
  • Select cloud deployment options for your game, including:
    • associate your game with its SpatialOS cloud project name.
    • choose its host server node region.
  • Ensure that the GDK prepares your game’s server-workers and client-workers by building workers.
  • Define your game’s assembly (which contains the built-out workers).

To do this, follow the steps in the Example Project tutorial: Start a cloud deployment. Make a note of the cloud deployment name for later.

When your cloud deployment is running and you see the message Cloud Deployment Started! you can connect your mobile device to the deployment by following these steps:

  1. In the Unreal Editor, select the Start Deployment drop-down menu.

  2. Ensure that Connect to a cloud deployment is selected.

  3. Click in the Cloud Deployment Name field and enter the name of the cloud deployment you want to connect to. You made a note of this cloud deployment name while following the steps in the Example Project tutorial.
    Note: If you leave the cloud deployment name blank then the GDK randomly selects a running deployment for your current project that has dev_login set as the deployment tag.

  4. Ensure that your mobile device is connected to your development machine using a USB cable.

  5. Select the Launch drop-down menu and select your mobile device. The Unreal Editor begins the process of packaging your game. This process can take a long time to complete when you run it for the first time.
    When the package process is complete, the Unreal Editor installs your game on your mobile device.

  6. To play your game, open the app on your mobile device.

  7. To finish playing your game, close the app on your mobile device and select Stop on your deployment’s Console page.

(Optional) Package your game in the Unreal Editor

Normally you should use the Unreal Editor to install your game on your mobile device using the Launch button (see the guide above). However, you can choose to package your game for iOS before you launch directly onto your mobile device. This creates the intermediate files that Unreal Engine needs when it launches to your mobile device, as well as packaging all the code, resources, assets and metadata for your game. You might want to do this to share your .ipa with other users for testing and production.

To build and package your game in the Unreal Editor, follow these steps:

  1. In the Unreal Editor, go to Edit > Project Settings > SpatialOS GDK for Unreal > Editor Settings > Mobile and select the Include Command Line Arguments when Packaging checkbox.

  2. On the GDK Toolbar, select Schema. This generates schema iteratively if you have already generated schema for your project. If you haven’t already generated schema for your project then the GDK uses a full scan to do so.
    For more information on generating schema, see Schema.

  3. To generate a snapshot, select Snapshot.
    For more information on generating a snapshot, see Snapshots.

  4. To package your game, navigate to File > Package Project > iOS and select where the generated package file (.ipa) should be saved. The Unreal Editor begins the process of packaging your game. This process can take a long time to complete when you run it for the first time.

(Optional) Manually install the package on your mobile device

Normally you should use the Unreal Editor to install your game on your mobile device using the Launch button (see the guide above). However, you can choose to install your game manually by following these steps:

  1. Connect your mobile device to your development machine using a USB cable. If your device displays a pop-up window requesting your permission to trust your computer, select Trust.
    Your mobile device name is displayed in iTunes to show that it is connected.

  2. In File Explorer, navigate to the location where you saved your package file (in step 3 of Package your project in Unreal Editor).

  3. Select your package file (.ipa) and copy it using the keyboard shortcut (Ctrl + C ).
    Note: You cannot use your mouse to drag and drop the package file in iTunes.

  4. In iTunes, in the devices section, right-click on your iOS device and select Paste.

  5. In the Unreal Editor, navigate to Edit > Project Settings > SpatialOS GDK for Unreal > Editor Settings > Mobile.

  6. Select Push SpatialOS Settings to iOS device.

  7. To play your game, open the app on your mobile device.

  8. To finish playing your game, close the app on your mobile device and select Stop on your deployment’s Console page.

Troubleshooting your iOS device

Your mobile device might not appear in iTunes and your game might not successfully install on your mobile device. To try to fix these problems, follow these steps in this order:

  1. Check that your provisioning profile is valid and that the mobile device you have connected to the development machine is included in the provisioning profile. To check your provisioning profile, follow the Unreal Engine documentation: iOS Provisioning.

  2. To check if you have given your mobile device permission to trust the development machine, disconnect your mobile device from the development machine and connect it again. If your device displays a pop-up window requesting your permission to trust your computer, select Trust.

  3. To check if you have a different game with the same bundle identifier installed, in the Unreal Editor, navigate to Edit > Project Settings > Platforms > iOS > Bundle Information > Bundle Identifier and make sure it is unique for the current game.

  4. To check if you have an older version of the same game on your mobile device, in iTunes, select your mobile device and select Summary. Delete all older versions of the same game.

  5. Restart your mobile device and restart iTunes.

  6. Update iTunes to the latest version available from Apple.
    Note: The version of iTunes that is currently available on the Windows 10 store might cause problems when using Unreal Engine. Ensure you download an older version of iTunes directly from Apple.

Change the deployment that your mobile game uses

You can connect to a different deployment with an existing game on your mobile device. This means you can develop your game and push changes to your mobile without creating a new package. To do this, change the command-line arguments to your game when it is launched so that your game uses different deployment settings.

To change command-line arguments to your game on your mobile device follow these steps:

  1. Ensure that your mobile device is connected to your development machine using a USB cable.

  2. In the Unreal Editor, navigate to Edit > Project Settings > SpatialOS GDK for Unreal > Editor Settings > Mobile.

  3. You can choose from these options:
    Push SpatialOS Settings to iOS device: Push a new version of the command-line arguments to the game that is installed on your mobile device. Note that you must have only one mobile device connected to your development machine for this to be successful.
    Override Mobile Connection Flow: When you push new versions of command-line arguments to the game that is installed on your mobile device, the GDK takes the arguments from the deployment that is set in the Start Deployment drop-down menu. You can override this without changing the deployment in the Start Deployment drop-down menu. To do this, select Override Mobile Connection Flow and then choose a different deployment to use with the Mobile Connection Flow setting (see below).
    Mobile Connection Flow: To override the deployment that is set in the Start Deployment drop-down menu, choose one of these options:

    • Connect to a local deployment: Your mobile game automatically connects to a local deployment.
    • Connect to a cloud deployment: Your mobile game automatically connects to a cloud deployment.
      You need to select Override Mobile Connection Flow (see above) to enable this setting.

    Local Runtime IP Override: Enter an IP address of a mobile device connected to your local area network. This means the command-line arguments are applied to a different IP address to the one that is specified in the Start Deployment drop-down menu.
    Note: To connect to a local deployment, in the Unreal Editor select Play > Mobile Preview ES3.1 (PIE) and click Play. This starts a local deployment and a client worker and server worker (which is needed for your mobile client).
    Mobile Client Worker Type: The name of your client-worker type. By default this is UnrealClient. For more information on client-worker types, see Worker types and worker instances.
    Extra Command Line Arguments: Specify additional command-line arguments that are not directly related to the connection flow.
    Start PIE Clients when launching on a device with local deployment flow: Choose to start PIE game clients when you launch your game on your mobile device using the Launch button. This means you can test your game easily with multiple clients across multiple platforms.

Troubleshooting: Permissions are too open

When you build your game you might see this error: Warning: Unprotected private key file!

This refers to your SSH key permissions and is warning you that they are too open. For example:

@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
Permissions 0660 for '/cygdrive/C/Users/<username>/AppData/Roaming/Unreal Engine/UnrealBuildTool/SSHKeys/<ip>/<username>/RemoteToolChainPrivate.key' are too open.
It is recommended that your private key files are NOT accessible by others. This private key will be ignored.

To downgrade the permissions of your private key, follow the steps below.

  1. Download the Cygwin installer and run setup.exe.
  2. In the Cygwin Setup window, click Next.
  3. Select the Install from Internet radio button and click Next.
  4. To install Cygwin, choose the default root directory, select the All Users radio button and click Next.
  5. To install the Cygwin Setup files, choose the default directory and click Next.
  6. Select the Use System Proxy Settings radio button and click Next.
  7. Use the selected download site. If the download fails then choose another site and click Next.
  8. In the Select Packages window, change Default to Uninstall for all packages.
  9. Select Category on the View drop-down menu, type cygwin in the Search field and press Enter on your keyboard.
  10. Expand All in the Package column and then expand Base.
  11. Change Uninstall to Default for the Base packages.
  12. Select base-cygwin and cygwin and click Next. The following window is displayed and shows all the software that is installed:
  1. Click Next to start the download.
  2. When Cygwin is installed, open the Cygwin64 terminal.
  3. To go to the folder that contains the private key, run the following:
cd "/cygdrive/C/Users/<Windows username>/AppData/Roaming/Unreal Engine/UnrealBuildTool/SSHKeys/<ip>/<macOS username>/"

Where <ip> is the IP address of your macOS machine.

  1. To downgrade the permissions of your private key, run the following:
    chgrp Users RemoteToolChainPrivate.key
    chmod 600 RemoteToolChainPrivate.key

2020-08-14 Page updated with editorial review: updated to reflect new Xcode 11 workflow

2020-08-13 Page updated with editorial review: add small tips

2020-08-07 Page updated with editorial review: removed Unreal Editor 4.23 requirements

2020-07-28 "Troubleshooting: permissions are too open" added with full editorial review

2020-06-29 Page added with full editorial review

Updated about a year ago


Launch your game on mobile (iOS)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.