Launch a Unity game from a SwiftUI iOS App

Since version 2019.3, Unity provides support for loading and unloading a Unity game from a native iOS or Android app through their Unity As A Library feature. This is a powerful way to integrate a game inside your native mobile app and separate game-specific logic from the iOS app logic.

Unity offers controls that let you manage when and how to load/activate/unload the runtime library within the native application. Beyond that, the mobile app build process mostly stays the same. Unity lets you create iOS Xcode and Android Gradle projects.

Nevertheless, the process of doing this can be quite challenging, especially if you want to integrate a Unity game in a SwiftUI app. But there’s no reason to worry because that’s exactly what we’re going to do in this article!

Without further ado, let’s roll up our sleeves and start! 😃

Create the iOS project

First, you need to create an empty iOS project inside a workspace. An easy way to do this is to first create an empty XCode project, and then go to File → Save As Workspace. Let’s name both the project and the workspace SwiftyUnity.

Important:
Make sure you select Storyboard as the Interface and UIKit App Delegate as the project Life Cycle. Don’t worry, we will convert this to a SwiftUI app later on, these steps are needed just to get the Unity integration working.

Also, since this will be a SwiftUI project, don’t forget to set the minimum iOS deployment target to 13.0.

Create the Unity project

Next, you need to create an empty Unity project. It doesn’t matter where it’s located, but it’s best to have it in the same folder where our workspace and the iOS project reside. Let’s call the Unity project UnityGame.

The only functionality we will add to the default Unity scene is a single button that leaves the game and returns to the iOS app. Add a button game object to the Unity scene and set the button text to “Quit Game”.

Now let’s add a script QuitBehavior.cs to our Button. It is very simple since all it needs to do is unload the Unity game and return to our iOS app.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class QuitBehavior : MonoBehaviour
{
    public void OnButtonPressed()
    {
    	  Application.Unload();
    }
}

We need to connect the OnButtonPressed listener to our button. Remember, to see the function in the list you have to mark it with public in the script attached to it!

This will be enough game functionality for now since our main goal is to load and unload the game from the iOS app, so now it’s time to build the Unity game as an iOS project.

Inside the Unity project, go to File → Build Settings. Here you will need to change the Platform from PC, Mac & Linux Standalone to iOS, then click on the Switch Platform button. You’ll need to wait a bit for Unity to recompile.

Time to export our Unity project as an iOS project. You don’t need to change any of the settings, just click Build. We will export the Unity project in a folder called UnityExport.

So far we should have three project folders in our root workspace folder:

• SwiftyUnity, the main iOS app.
• UnityGame, the Unity game project.
• UnityExport, created by exporting the Unity game as an iOS project.

If your folder structure doesn’t look like this, don’t worry. Everything will still work as long as you connect the projects properly, which we will do in the next step.

Connect Unity with iOS

It’s time to connect the exported Unity project with our SwiftUI app. Open the SwiftyUnity.xcworkspace, which currently only contains the SwiftyUnity project.

In Finder, locate the UnityExport project, and drag the
Unity-iPhone.xcodeproj file to the workspace.

Now both SwiftyUnity.xcodeproj and Unity-iPhone.xcodeproj belong to the same workspace. If your Unity-iPhone.xcodeproj is red after dragging, make sure that you set Location to Relative to Workspace in the right panel of the project.

Next, click on SwiftyUnity project and select the SwiftyUnity target. From the General menu, scroll down to the Frameworks, Libraries and Embedded Content section. Click on the + button to add a new framework.

Select UnityFramework.framework from the list and add it to the project.

Next, select the Data folder in Unity-iPhone project. In the right panel, you will see a Target Membership section. You need to check the box next to UnityFramework.

Next, open Info.plist and remove the Application Scene Manifest entry. This will temporarily break the app but we’ll resolve it later in the AppDelegate.

That’s enough configuration for now. It’s finally time to write some code!

And now… some code!

Let’s first add a new SwiftUI View called ContentView.swift, which will be our entry point to SwiftUI. We’ll add a single button that will launch the game. We will leave the button listener empty for now, and return here once we prepare the code that launches the Unity game.

import SwiftUI

struct ContentView: View {
    var body: some View {
        Button(action: {
            // TODO: Add code for launching Unity here
        }) {
            Text("Launch Unity!")
        }
    }
}

Since we initially created a UIKit Storyboard app (and not a SwiftUI app), we now need to connect our ContentView with the root ViewController that has been generated. So the next step is to update our ViewController.swift code:

import UIKit
import SwiftUI

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        let vc = UIHostingController(rootView: ContentView())
        addChild(vc)
        vc.view.frame = self.view.frame
        view.addSubview(vc.view)
        vc.didMove(toParent: self)
    }
}

The most important step, of course, is to implement the connection with the app and the game through UnityFramework that we imported earlier. If you want to learn more about the framework, you can visit the official docs here.

We will create a helper singleton class called Unity, which we can use for all our UnityFramework-related needs. Create a new class and fill it with the following code:

import Foundation
import UnityFramework

class Unity: UIResponder, UIApplicationDelegate {

    static let shared = Unity()

    private let dataBundleId: String = "com.unity3d.framework"
    private let frameworkPath: String = "/Frameworks/UnityFramework.framework"

    private var ufw : UnityFramework?
    private var hostMainWindow : UIWindow?

    private var isInitialized: Bool {
        ufw?.appController() != nil
    }

    func show() {
        if isInitialized {
            showWindow()
        } else {
            initWindow()
        }
    }

    func setHostMainWindow(_ hostMainWindow: UIWindow?) {
        self.hostMainWindow = hostMainWindow
    }

    private func initWindow() {
        if isInitialized {
            showWindow()
            return
        }

        guard let ufw = loadUnityFramework() else {
            print("ERROR: Was not able to load Unity")
            return unloadWindow()
        }

        self.ufw = ufw
        ufw.setDataBundleId(dataBundleId)
        ufw.register(self)
        ufw.runEmbedded(
            withArgc: CommandLine.argc,
            argv: CommandLine.unsafeArgv,
            appLaunchOpts: nil
        )
    }

    private func showWindow() {
        if isInitialized {
            ufw?.showUnityWindow()
        }
    }

    private func unloadWindow() {
        if isInitialized {
            ufw?.unloadApplication()
        }
    }

    private func loadUnityFramework() -> UnityFramework? {
        let bundlePath: String = Bundle.main.bundlePath + frameworkPath

        let bundle = Bundle(path: bundlePath)
        if bundle?.isLoaded == false {
            bundle?.load()
        }

        let ufw = bundle?.principalClass?.getInstance()
        if ufw?.appController() == nil {
            let machineHeader = UnsafeMutablePointer<MachHeader>.allocate(capacity: 1)
            machineHeader.pointee = _mh_execute_header

            ufw?.setExecuteHeader(machineHeader)
        }
        return ufw
    }
}

extension Unity: UnityFrameworkListener {

    func unityDidUnload(_ notification: Notification!) {
        ufw?.unregisterFrameworkListener(self)
        ufw = nil
        hostMainWindow?.makeKeyAndVisible()
    }
}

Let’s set up AppDelegate so we can run the app. Open AppDelegate.swift and remove all scene-related functions. We will also need to pass the main app window reference to Unity here since that’s the window we’ll return to once we unload the Unity game.

After these modifications, your AppDelegate should look like this:

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        Unity.shared.setHostMainWindow(window)

        return true
    }
}

Finally, all that is left is to launch the game from our ContentView.
We simply need to call the show() method from our Unity class inside the button listener. This is the result:

import SwiftUI

struct ContentView: View {
    var body: some View {
        Button(action: {
            Unity.shared.show()
        }) {
            Text("Launch Unity!")
        }
    }
}

That’s it! Let’s run the app and try it out!

Important: Make sure you run the app on a real physical iPhone device, and not on a simulator!

This gif shows what the final result should look like:

Voila! That’s it. We can load the Unity game from our native SwiftUI app, and return to the native side by tapping the Quit Game button. Pat yourself on the back, you deserved it!

Where to go from here?

Loading and unloading Unity is one thing. But you will often want to pass some data from the native app to the Unity game, as well as receive other data back from the game. For example, you might need to pass some player information to the game before it starts. Or send the game results back to the native iOS app, so it can format it and send it to a server.

You might even want to use a custom controller for your game via Bluetooth, which would be coordinated from the native side and passed over to Unity! The possibilities are endless, and it’s always a good idea to separate the native logic from the game logic wherever applicable.

UnityFramework provides this functionality as well. There is a way to send data both to and from Unity by making use of the Unity framework. If you are interested in this, take a look at this article, which will show you how to implement communication between iOS and Unity! 🚀

If you liked this article, check out Part 2:

➡️ Communicate with a Unity game embedded in a SwiftUI iOS App