Launch your game on mobile (Android)

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 Android mobile device, development 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 follow:

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

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

Step 1: Set up your Android mobile device

  1. You need to enable USB debugging on your Android mobile device. This is so that you can connect it to your development machine, install packages and launch directly to the device using the USB cable. The method in which you enable USB debugging depends on which version of Android and what hardware you are using.

    To enable USB debugging, follow the instructions in the Android developer documentation for your device and version of Android.

  2. Connect your mobile device to your development machine using a USB cable. If your device displays a pop-up window requesting your permission to allow USB debugging, select Yes.

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 2: Set up your development machine

You need to install a development kit on your development machine to use Unreal Editor for Android. If you are using Unreal Editor 4.24 then you need to install CodeWorks. If you are using Unreal Editor 4.25 then you need to install Android Studio.

Unreal Editor 4.24

  1. You need to install a specific version of the Android Software Development Kit (SDK) called CodeWorks for Android 1R7u1 so that you can develop Android projects with Unreal Engine 4.24.

    To install the CodeWorks for Android SDK on your development machine, follow these steps in the Unreal Engine documentation: Installing CodeWorks for Android. This also installs Java 8 which is required by CodeWorks.

  2. Set up the Unreal Editor for Android by following these steps in the Unreal Engine documentation: Setting up Unreal Editor for Android.

Your default path and environment variables on Windows might change as a result of installing the CodeWorks for Android SDK. If your Windows Path variable has paths that are useful to you, then you should make a copy of the values and then compare them to the new values after installing CodeWorks. If there are any paths you want to restore, you can fix the values and save the changes by following these instructions.

To check and restore your Windows Path variable, follow these steps:

  1. Navigate to Control Panel > System and Security > System.
  2. Select Advanced system settings and make sure the Advanced tab is selected.
  3. Select Environment Variables.
  4. In the System Variables window, scroll down and select Path.
  5. Select Edit.
  6. The Edit environment variable window is displayed. You can check your paths and restore them to their previous values here. For more information on Windows environment variables, see Set the Path and Environment Variables for Command-Line Builds.
  7. To save the changes, select OK.

Unreal Editor 4.25

  1. You need to install a specific version of the Android Native Development Kit (NDK) called Android Native Development Kit Revision 21 (NDK r21) and Android Studio so that you can develop Android projects with Unreal Engine 4.25.

    Note: If you are upgrading from Unreal Editor 4.24 to 4.25 then you need to uninstall CodeWorks for Android and any existing NDK components first, as well as delete the folder CodeWorks was installed to.

    To install the Android NDK and Android Studio on your development machine, follow these steps in the Unreal Engine documentation: Setting Up Android SDK and NDK for Unreal.

  2. Set up the Unreal Editor for Android by following these steps in the Unreal Engine documentation: Setting up Unreal Editor for Android.

Step 3: 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 4 and 5 (below) the Unreal Editor builds your game package and installs it on your mobile device.

Tip: You might not want to include changes to your game code when you build your package file, for example if you are only working on art assets. To exclude changes to the game code from the package file, navigate to Edit > Editor Preferences > Level Editor > Play > Play on Device > Build game before launch and select Never.

Step 4: 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 subnet mask, and set the IP address of your local deployment in the Unreal Editor.

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 and ensure that your cursor is in the text entry box of the Local Deployment IP field.

  4. Enter the IP address of your 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 development machine using a USB cable.

  7. 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, a local deployment starts with one server worker instance and the Unreal Editor installs your game and launches it on your mobile device automatically.

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.

Step 5: Connect to a cloud deployment

You can start cloud deployments from Windows development machines only. You cannot start cloud deployments from macOS development machines.

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.

Before you start a cloud deployment, in addition to generating schema and a snapshot in Step 3 (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, schema descriptor, and worker metadata).

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 and launches it on your mobile device automatically.

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 Android 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.

    Remove SpatialOS Settings from Android device: Remove all amended command-line arguments from the game that is installed on your mobile device and return the command-line arguments to default ones. 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.

    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.

(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 Android 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 .apk with other users and to choose specific texture formats 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. Navigate to File > Package Project > Android to select the texture format that you want to use for your game and choose where to save the packaged file.

    Choose the appropriate texture format for compressing textures that is supported by your Android device. Different devices support different methods of texture compression. If you are unsure which format is appropriate, choose one of the following:

    • Android (Multi: ATC, DCT, ETC2): Includes all formats in the package.
    • Android (ETC2): Supported by all OpenGL 3.x class devices and supports alpha compression
      For more information on how to choose the correct texture format, see Packaging Android Projects.

When you upload a package to the Google Play store, you need to supply an .obb file separately if you want to include larger assets. However, if you are sharing the game with users then you might want to only share a single package file which the users can install directly on their device without any additional steps. To package all assets in the .apk file, in the Editor, navigate to Project Settings > Platforms > Android and select Package game data inside .apk.

For more information about the .obb file and packages, see APK Expansion Files.

  1. After you have selected a texture format and specified where to save the packaged file, 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 locating the .apk file you have created. You can either:

  • install the package file using helper scripts, or
  • install the package directly from the command line, if you have included the .obb file within the package (see the tips on how to include the .obb within the package file above).

Install the package using helper scripts
To install the package on your mobile device using helper scripts, follow these steps:

  1. In File Explorer (or Finder if you are using macOS) navigate to the location where you saved your package file (in step 3 of Package your project in Unreal Editor).

  2. Double-click the script called:
    Install_<your_project_name>-<architecture> (where your_project_name matches the name of your game and architecture is the specification of the Application Binary Interface for your mobile device’s CPU).
    The package is installed on your mobile device.
    Note: If you already have a package installed on your mobile device, this script automatically removes the old version and installs the new version.

Install the package using the command line
To install the package using the command line, you must include the .obb file in the package (see (Optional) Include the .obb within the package file). Follow these steps:

  1. Open a terminal window and navigate to the location where you saved the package file.

  2. Run adb install <your_apk>.apk (where your_apk is the filename of the package).
    The package is installed on your mobile device.

Tip: If you receive a warning on your mobile device that the installation failed, check to see if the game appears on your device. The installation might have failed to complete, but your game might be partially installed. In this case, you need to approve further permissions on your device to complete the installation. Open the game on your device and approve all of the permissions that your device requests. Then close the game and run the install script again. This should allow the script to fully install your game.

Debug your game

To help diagnose issues with your mobile game, install Android Studio on your development machine (if you have not already done so). You need to restart the machine when the installation is complete.

Follow the Unreal documentation on debugging your game.

The Unreal Editor might recreate your gradle files when packaging your game. This means you might have to re-enter any debug settings you have used in Android Studio.


2020-08-07 Page updated with editorial review: for Unreal Editor 4.25 requirements and other changes
2020-07-08 Page added with editorial review

Updated about a year ago


Launch your game on mobile (Android)


Suggested Edits are limited on API Reference Pages

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