Guide to Integrating Android Plugins in Unity Projects: Hybrid Builds, Mutual Calls, and Debugging

This article explains how to use Android or Java libraries in Unity projects, covering the creation and usage of Android plugins, bidirectional communication between Unity (Mono/IL2CPP) and Android (Dalvik/ART) virtual machines, best practices for designing Unity interfaces that wrap Java APIs, constructing Unity‑Android hybrid projects with Gradle and MSBuild/xbuild, debugging techniques via ADB, and supplemental information such as AAR support and AndroidManifest configuration.

Using Android Plugins in Unity

An Android plugin consists of a JAR file and a wrapper (C# or DLL). The JAR must be placed under /Assets/Plugins/Android in the Unity project, together with any additional dependencies and resources (e.g., AndroidManifest.xml , res folder). If the plugin requires special permissions, they must be added to a manually supplied AndroidManifest.xml in the same directory. The wrapper code (C# file or DLL) resides under /Assets ; for a DLL, add it as a dependency in the Unity C# project.

Unity‑Android Mutual Calls

Communication occurs between two VMs: Unity’s Mono/IL2CPP and Android’s Dalvik/ART. Unity accesses Java objects via AndroidJavaObject and AndroidJavaClass , while Android invokes Unity methods through AndroidJavaProxy or the static method UnityPlayer.UnitySendMessage . Example code for obtaining a Java singleton and calling its methods:

AndroidJavaObject player = new AndroidJavaClass("example.Player").CallStatic<AndroidJavaObject>("getInstance");
player.Set("volume", 0.8f);
player.Call("setDataSource", "http://example.com/stream.m4a");
int duration = player.Call<int>("getDuration");
AndroidJavaObject info = player.Call<AndroidJavaObject>("getAudioInfomation");

The article details the method table of AndroidJavaObject ( Call , Call<T> , CallStatic , CallStatic<T> , Get<T> , GetStatic<T> , Set(T) , SetStatic(T) ) and notes the limitation that invoking a method returning AndroidJavaObject throws an exception if the Java side returns null .

Best Practices for Unity Interface Design

To expose Java APIs in C#, the article proposes a reflection‑based approach: a base class AndroidObjectMirror holds an AndroidJavaObject reference, manages its global reference lifecycle, and provides an InitFromJava hook for subclasses to bind fields and methods. Subclasses mirror Java classes by delegating calls to the wrapped AndroidJavaObject , e.g.:

int Add(int a, int b) {
    return AJObject.Call<int>("add", a, b);
}

The Reflection.Reflect<T> utility creates mirror instances, handling null checks and exceptions.

Building Unity‑Android Hybrid Projects with Gradle

The source outlines a multi‑module Gradle layout:

Android SDK module (produces a JAR)

Android Demo (quick test)

Unity Bridge (wraps the Android SDK)

Unity Demo (demonstrates the bridge)

Android SDK is built via Gradle tasks that compile Java, package a JAR, optionally run ProGuard, and copy the output to a latest folder. The Unity Bridge uses a custom CSharpBuildTask that invokes xbuild (or msbuild ) on a solution file. The Unity Demo relies on Unity Pro’s command‑line build through a UnityBuildTask that calls BuildPipeline.BuildPlayer . A root‑level plugin ( SDKBuildPlugin ) ties together tasks such as buildAndroidSDK , copyAndroidSDKToDemo , buildUnitySDK , copyUnitySDKToDemo , buildUnityDemo , and buildAndroidDemo to automate the full hybrid build.

Debugging

Both C# and Java code are debugged remotely via ADB. Steps: connect device over USB, run adb tcpip 5555 , obtain the device’s IP with ifconfig , then connect via adb connect <IP>:5555 . Afterward, attach to the process from MonoDevelop/Xamarin or Android Studio. Notes about required plugins for Xamarin and ensuring the Android project containing Java code is loaded in Android Studio are provided.

Appendix

Unity 5.2.0b3+ supports AAR files, allowing resources to be bundled inside the AAR and eliminating the need to place them under /Assets/Plugins/Android . The appendix also links to a sample AndroidManifest.xml .