Unity as a Library: Bring Unity Features to Your Android App 🎮

Photo by Mika Baumeister on Unsplash

Unity is a game engine developed by Unity Technology, running on Windows, MacOS and Linux, for building cross-platform games and applications (Android, iOS, Windows, PlayStation…). It has been there for 15 years now, and it gave us the opportunity to build high quality graphic experiences or games on mobile. Unity is becoming more and more popular: according to the company, “50% of the new mobile games are made with Unity”. A lot of studios (Blizzard, Square Enix, White Elk…) are trusting Unity for developing their games or AR/VR standalone applications.

Unity has recently improved the support for building great game experience on Android and gave us Unity as a Library to add a Unity game in an existing Android application as a proper library integration. Let’s see how to export a small Unity experience and add it to your own application, how to easily extend the UnityPlayerActivity generated on the library, and how to add some native UI components to your extended Activity in order to interact with game!

First steps with Unity

First, we are going to build a tiny 3D experience with Unity (version 2020.1.11f1), with no need of an extended knowledge of the game engine. Our main focus here, is to have an Android library that can be used in an existing Android application.

Source code of the Unity project can be found on my Github account:

Oleur/unity-uaal-sample

Here is what the Unity editor looks like with a scene and some 3D assets added to it:

Unity 2020.1.11f1 editor

When starting a new project, for instance a 3D game here, you will be able to easily add 3D components thanks to the “GameObject” menu located at the top on the editor. You can select multiple shapes, lights or even UI components , but you can also import a more complex 3D asset that you have locally or remotely if you get assets from the Unity Asset Store.

Therefore, we can create and attach a C# script to the 3D capsule we added on the scene. Keep in mind that the script file name should match the class name of your script. To attach it to the asset, click on “Add Component” and choose “New Script”. For the example, in the created script, we are going to implement a ChangeColor() method for changing the color of the material and 4 others functions for moving the object in the scene (a similar behavior you can find with the keypad arrows while playing a game).

Every script attached to an object extends the base class MonoBehaviour, it offers some lifecycle methods that are very helpful for developing your apps and games. Let’s have a look at a newly created script:

public class MyAsset : MonoBehaviour {
    // Start is called before the first frame update
    void Start() {
        
    }
    // Update is called once per frame
    void Update() {
    }
}

You can override these methods, alongside many others depending on what you need, and implement the behavior of the 3D asset. Here for example, let’s override Update() for handling the click on the capsule from the touch screen and we are going to expose the ChangeColor() method that will be used by our Android application to change the color of the object.

In order to be notified by the Android application, the exposed method signature must be as the following:

// Exposed method to be notified by UnitySendMessage()
void MyMethod(string params) {
    // Do something
}

What is very annoying here, is that the parameter of the function must be string type so it might be complicated to pass some complex data with the UnitySendMessage() method.

Now let’s have a look at the final script:

Once the scripting is done without any compilation error, we can convert our Unity project to an Android project that will be used with Android Studio.

Exporting your Unity project as an Android library

Now that we are all good on the Unity side, let’s focus on the integration of this game in an existing Android application. To export the project, go to the “File” menu and click on “Build Settings”, there you will be able to export the Unity project as an Android Studio compatible project. Make sure to target the Android platform and to have checked the “Export Project” box. If you already have some Java/Kotlin files in your Unity game, do not forget to check the “Symlink Sources” box before exporting.

As you may know, applications published on Google Play needs to support 64-bit architectures. To do so, click on the “Player Settings” and scroll to “Other Settings” to enable IL2CPP for the scripting backend configuration. Then, when exporting the project, ARM64 devices will be supported.

Build Settings window for exporting the project

IL2CPP configuration

You are now all set for working directly with the Unity project exported as Android Studio project. When you open this project on Android Studio, you will see about this screen:

Unity project as an Android project

Let’s explore the project structure. It is composed of two module (launcher and unityLibrary), the first one is for actually launching the application where you can implement all the Android stuff you want: creating new Activity, Views or Fragment… and the second is the unity game as library module. In this one, you will have access to the UnityPlayerActivity that can be extended, the most interesting here is that we can use the UnityPlayer to send messages to our Unity game.

Now let’s bring this module in an existing Android application.

Take advantage of the Unity library

Now that we have our Unity game as an Android module library, we can import it in an existing Android application. For the demonstration, we are going to keep it simple with a main Activity with an ImageView and a Button to start the Unity experience. The UnityPlayerActivity will be extended to add some native UI components (MaterialButtons for example) in order to send actions to our Unity game.

Source code of the sample Android app can be found on my Github account:

Oleur/android-unity-as-library-sample

From the exported project, you can either implement you app directly on the launcher module generated by Unity or import the unityLibrary module in our existing app. Let’s work with the second solution!

After importing the Unity module in our application, let’s have a look at the generated UnityPlayerActivity. What interests us here is the UnityPlayer. If we look at its implementation behind the hood, it is a FrameLayout. It will hold the SurfaceView where the Unity experience will be rendered and handle all the things that the game needs to run correctly on Android. Do not forget to add this string resource otherwise the Unity game will crash.

<string name=”game_view_content_description”>Game view</string>

Now that we know how the UnityPlayerActivity is structured, we can extend it in our app module to get the best of it. Thanks to the UnityPlayer, we can add any UI native components to the screen in order to interact with the game. Here, we will add two buttons at the top of the screen, one for changing the color of the capsule and the other for quitting the Unity game. At the bottom, there will be 4 buttons for moving the capsule around in the scene. Let see how we can achieve that!

The UnityPlayer object provides a static method to send native messages to the Unity game objects. To send the action, you have to provide the game object you want to target, the method name on our script and the parameters (as a String) you want to pass.

// Send native message to Unity
UnitySendMessage(String gameObject, String method, String params)

All together, the UnityGameActivity looks like this and can be started from anywhere in your app.

And here’s what this a̶m̶a̶z̶i̶n̶g̶ ̶A̶A̶A̶ game looks like in our application :)

Unity as a Library in action!

In this article we explored how to take advantage of Unity as a Library to bring amazing games or AR/VR experiences in your Android applications. In a new article, I will go into the details of what is generated inside the Unity library (Gradle files, Java/C++ classes…).

If you are interested in learning more about the Unity game engine and how to master it, Unity provides a lot of high quality resources for beginners and advanced learners.

Thanks for reading, I hope it gave you a glimpse at Unity and showed you how easy is it to integrate Unity features in existing apps. Do not hesitate to ping me on Twitter I will share more stuff on Android in the coming weeks 😀 🎮