Creating an AAR plugin for Unity

Prerequisites: Unity, Android Studio

Synopsis

1. Create an Android Library module in Android Studio
2. Add the unity-classes.jar library into your module
3. Update the gradle file
4. Export the AAR plugin into Unity.

Intro

If you have been making a Unity game for Android there’s a good chance that you needed some functionality native to the Android OS that you couldn’t access through Unity.

For example you may want to present a toast message or fine tune location input or get access to Bluetooth functionality.

To achieve this functionality you can either

1. Export your project to Android Studio and edit it from there.
2. Create a plugin with the functionality.

Exporting your project is good for a simple project, but if you’re project is fairly large and you need to make changes in Unity and then in native code several times, going back and forth quickly becomes cumbersome.

Instead you can create a plugin Unity can use, specifically an AAR plugin which is the new standard for Android apps. When Unity detects a plugin anywhere within the assets folder it’ll automatically install whenever you build and run allowing you to skip the export stage and stay completely inside Unity (this also helps you create portable code to use in other projects).

What we’re making

I’ll be walking you through how to create a simple plugin to display a toast from Unity.

1. Export your Unity project to Android Studio.

This step is actually optional but if this is your first time making the plugin I highly recommend this as you can test your code before you make the plugin. If you skip this step then go to step 3.

In Unity > File > Build Settings > Export Project > Export

Exporting your project to Android Studio

2. Open your project with Android Studio.

Once your inside you can open up UnityPlayerActivity.java and start making changes right away. Press the play button at the top and it’ll deploy to your device (or an emulator if you set one up) just like in Unity.

Opened project in Android Studio

3. Create the module for the AAR plugin

File > New > New Module

Select Android Library

Name it ToastPlugin (or whatever you want) and click Finish

You should now have a new project in your project viewer.

There’s our new module!

4. Getting access to Unity

If you just want to have one-way communication from Unity to Android you can skip this. If you want two-way communication or communication from Android to Unity then you’ll need access to the UnityPlayer java object.

First go back to your Android Studio project folder (not the module folder), open up the libs folder, and copy unity-classes.jar

Example location

Alternatively if you didn’t export the Android Studio project you can find it in your Unity folder here:

...\Unity\Editor\Data\PlaybackEngines\AndroidPlayer\Variations\mono\Release\Classes\classes.jar

Paste the jar file into your modules libs folder and rename it to something else (eg. unity.jar).

We now have the Unity library in our project, we just need to tell Android Studio to be aware of it now.

5. Setting up the Gradle file

Gradle is Android’s build tool to customize build logic as well as handle dependencies.

Open it up on the project viewer and you should get something like this:

Gradle file for the module

In the dependencies section replace everything with:

dependencies {
    // change "unity.jar" to whatever you renamed your file
    // compileOnly exposes the jar's functionality during development but won't package it along with the built plugin.
    compileOnly files ('libs/unity.jar')
}

Note: this may have removed the unit test libraries. Check your project folders and delete any test classes or it won’t compile.

Removing test classes

Now if you want to use more libraries you would normally do something like this:

dependencies {
    // Dependency on a local library module (this won't work!)
    implementation project(":mylibrary")

    // Dependency on a remote binary (this won't work!)
    implementation 'com.example.android:app-magic:12.3'

    // Dependency on local binaries (warning this will compile unity-classes.jar again - not good!)
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

However this plugin is going to be used in Unity, not in Android Studio so it can’t actually download remote binaries (or access projects because … well it’s a Unity project not an Android Studio project).

Instead if you want to another library then you’ll need to download the jar (just google your dependency + jar) and use this instead.

dependencies {   
    // Dependency on specific binaries
    implementation files('libs/gson-2.8.5.jar')
}

In the above example I downloaded the gson library jar file and placed it in the modules libs folder. This time you need to use implementation files because you want the built jar file packaged with your AAR plugin (unlike the unity-classes.jar which is provided already).

Warning: This means if you’re using multiple libraries you might get a jar conflict!

6. Writing some code

Now that the plugin module is fully setup, lets actually implement some functionality.

In Android Studio create a new class called UnityToast.java that looks like this:

public class UnityToast
{
    // This function will be called from Unity
    public static void ShowToast(String message)
    {
        // Display the toast popup
        Toast.makeText(UnityPlayer.currentActivity, message, Toast.LENGTH_SHORT).show();

        // Send a message back to Unity 
        UnityPlayer.UnitySendMessage(
                // game object name 
                "ToastObject",  
                // function name 
                "ReceiveFromAndroid",                       
                // arguments 
                "Displayed toast with message: " + message  
        );
    }
}

And in Unity create a new game object in scene called “ToastObject”, Add a script called ToastHelper.cs that looks like this:

public class ToastHelper : MonoBehaviour
{
    AndroidJavaClass ajc;
    void Start ()
    {
        ajc = new AndroidJavaClass("cheung.jason.toastplugin.UnityToast"); 
        SendToAndroid("Hello World");
    }
    private void SendToAndroid(string message)
    {
        ajc.CallStatic("ShowToast", message);
    }
    // This function will be called from Android
    private void ReceiveFromAndroid(string message)
    {
        Debug.Log("Received message from toast plugin: " + message);
    }
}

This script will send a toast message to the plugin when it starts and also receive an acknowledgement from the plugin.

7. Export AAR plugin

Now that all the code is setup we can export the AAR plugin into Unity.

On the right side of the screen > Gradle > toastplugin > Tasks > build > clean + build + assembleRelease

Assembling the AAR plugin

Open your module in explorer and find the AAR file located in

…/project_name/toastplugin/builds/outputs/

And then drag it into Unity’s Asset folder.

8. Your done!

Plug your Android device in and then Build & Run. It should show you a “Hello World!” toast message when the game starts.

You can now keep making changes in Unity without going back to Android Studio. I personally recommend using the gson library (a JSON de/serializer for Android) if you need to pass more structured data between your plugin.

If you don’t like working purely in strings or need the absolute maximum performance then you might want to take a look at native C++ plugins for Android. This route is obviously a lot more complex.